From b61ee25ee7e922b36bb4ae6d505a5f6cbe5b23e6 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 12 Mar 2015 15:35:13 +0100 Subject: Update Getting Started Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Hans Bolinder. --- system/doc/getting_started/seq_prog.xml | 823 ++++++++++++++++---------------- 1 file changed, 422 insertions(+), 401 deletions(-) (limited to 'system/doc/getting_started/seq_prog.xml') diff --git a/system/doc/getting_started/seq_prog.xml b/system/doc/getting_started/seq_prog.xml index 699b9487ed..5d96aed8d4 100644 --- a/system/doc/getting_started/seq_prog.xml +++ b/system/doc/getting_started/seq_prog.xml @@ -31,11 +31,15 @@
The Erlang Shell -

Most operating systems have a command interpreter or shell- Unix - and Linux have many, while Windows has the Command Prompt. Erlang has - its own shell where you can directly write bits of Erlang code - and evaluate (run) them to see what happens (see - shell(3)). Start +

+ Most operating systems have a command interpreter or shell, UNIX + and Linux have many, Windows has the command prompt. Erlang has + its own shell where bits of Erlang code can be written directly, + and be evaluated to see what happens + (see the shell(3) + manual page in STDLIB). +

+

Start the Erlang shell (in Linux or UNIX) by starting a shell or command interpreter in your operating system and typing erl. You will see something like this.

@@ -45,41 +49,39 @@ Erlang R15B (erts-5.9.1) [source] [smp:8:8] [rq:8] [async-threads:0] [hipe] [ker Eshell V5.9.1 (abort with ^G) 1> -

Now type in "2 + 5." as shown below.

+

Type "2 + 5." in the shell and then press Enter (carriage return). + Notice that you tell the shell you are done entering code by finishing + with a full stop "." and a carriage return.

 1> 2 + 5.
 7
 2>
-

In Windows, the shell is started by double-clicking on the Erlang - shell icon.

-

You'll notice that the Erlang shell has numbered the lines that - can be entered, (as 1> 2>) and that it has correctly told you - that 2 + 5 is 7! Also notice that you have to tell it you are - done entering code by finishing with a full stop "." and a - carriage return. If you make mistakes writing things in the shell, - you can delete things by using the backspace key as in most - shells. There are many more editing commands in the shell - (See the chapter "tty - A command line interface" in ERTS User's Guide).

-

(Note: you will find a lot of line numbers given by the shell - out of sequence in this tutorial as it was written and the code - tested in several sessions.)

-

Now let's try a more complex calculation.

+

As shown, the Erlang shell numbers the lines that + can be entered, (as 1> 2>) and that it correctly says + that 2 + 5 is 7. If you make writing mistakes in the shell, + you can delete with the backspace key, as in most shells. + There are many more editing commands in the shell + (see tty - A command line interface in ERTS User's Guide).

+

(Notice that many line numbers given by the shell in the + following examples are out of sequence. This is because this + tutorial was written and code-tested in separate sessions).

+

Here is a bit more complex calculation:

 2> (42 + 77) * 66 / 3.
 2618.0
-

Here you can see the use of brackets and the multiplication - operator "*" and division operator "/", just as in normal - arithmetic (see the chapter - "Arithmetic Expressions" in the Erlang Reference Manual).

-

To shutdown the Erlang system and the Erlang shell type - Control-C. You will see the following output:

+

Notice the use of brackets, the multiplication operator "*", + and the division operator "/", as in normal arithmetic (see + Expressions).

+

Press Control-C to shut down the Erlang system and the Erlang + shell.

+

The following output is shown:

 BREAK: (a)bort (c)ontinue (p)roc info (i)nfo (l)oaded
        (v)ersion (k)ill (D)b-tables (d)istribution
 a
 %

Type "a" to leave the Erlang system.

-

Another way to shutdown the Erlang system is by entering +

Another way to shut down the Erlang system is by entering halt():

 3> halt().
@@ -88,67 +90,70 @@ BREAK: (a)bort (c)ontinue (p)roc info (i)nfo (l)oaded
 
   

     Modules and Functions
-    
A programming language isn't much use if you can just run code
+    
A programming language is not much use if you only can run code
       from the shell. So here is a small Erlang program. Enter it into
-      a file called tut.erl (the file name tut.erl is
-      important, also make sure that it is in the same directory as
-      the one where you started erl) using a suitable
-      text editor. If you are lucky your editor will have an Erlang
-      mode which will make it easier for you to enter and format your
-      code nicely (see the chapter
-      "The Erlang mode for Emacs" in Tools User's Guide), but you can manage
-      perfectly well without. Here's the code to enter:

+      a file named tut.erl using a suitable
+      text editor. The file name tut.erl is important, and also
+      that it is in the same directory as the one where you started
+      erl). If you are lucky your editor has an Erlang mode
+      that makes it easier for you to enter and format your code
+      nicely (see The Erlang mode for
+      Emacs in Tools User's Guide), but you can manage
+      perfectly well without. Here is the code to enter:

     
 -module(tut).
 -export([double/1]).
 
 double(X) ->
     2 * X.
-    
It's not hard to guess that this "program" doubles the value of
-      numbers. I'll get back to the first two lines later. Let's compile
-      the program. This can be done in your Erlang shell as shown below:

+    
It is not hard to guess that this program doubles the value of
+      numbers. The first two lines of the code are described later.
+      Let us compile the program. This can be done in an Erlang shell
+      as follows, where c means compile:

     
 3> c(tut).
 {ok,tut}

-    
The {ok,tut} tells you that the compilation was OK. If it
-      said "error" instead, you have made some mistake in the text you
-      entered and there will also be error messages to give you some
-      idea as to what has gone wrong so you can change what you have
-      written and try again.

-    
Now let's run the program.

+    
The {ok,tut} means that the compilation is OK. If it
+      says "error" it means that there is some mistake in the text
+      that you entered. Additional error messages gives an idea to
+      what is wrong so you can modify the text and then try to compile
+      the program again.

+    
Now run the program:

     
 4> tut:double(10).
 20

-    
As expected double of 10 is 20.

-    
Now let's get back to the first two lines. Erlang programs are
-      written in files. Each file contains what we call an Erlang
-      module. The first line of code in the module tells us
-      the name of the module (see the chapter
-      "Modules"
-      in the Erlang Reference Manual).

+    
As expected, double of 10 is 20.

+    
Now let us get back to the first two lines of the code. Erlang
+      programs are
+      written in files. Each file contains an Erlang
+      module. The first line of code in the module is
+      the module name (see
+      Modules):

     
 -module(tut).
-    
This tells us that the module is called tut. Note
-      the "." at the end of the line. The files which are used to store
+    
Thus, the module is called tut. Notice
+      the full stop "." at the end of the line. The files which are
+      used to store
       the module must have the same name as the module but with
-      the extension ".erl". In our case the file name is tut.erl.
-      When we use a function in another module, we use the syntax,
-      module_name:function_name(arguments). So

+      the extension ".erl". In this case the file name is tut.erl.
+      When using a function in another module, the syntax
+      module_name:function_name(arguments) is used. So the
+      following means call function double in module tut
+      with argument "10".

     
 4> tut:double(10).

-    
means call function double in module tut with
-      argument "10".

-    
The second line:

+    
The second line says that the module tut contains a
+      function called double, which takes one argument
+      (X in our example):

     
 -export([double/1]).
-    
says that the module tut contains a function called
-      double which takes one argument (X in our example)
-      and that this function can be called from outside the module
-      tut. More about this later. Again note the "." at the end
-      of the line.

-    
Now for a more complicated example, the factorial of a number
-      (e.g. factorial of 4 is 4 * 3 * 2 * 1). Enter the following code
-      in a file called tut1.erl.

+    
The second line also says that this function can be called from
+      outside the module tut. More about this later. Again,
+      notice the "." at the end of the line.

+    
Now for a more complicated example, the factorial of a number.
+      For example, the factorial of 4 is 4 * 3 * 2 * 1, which equals 24.

+    
Enter the following code in a file named tut1.erl:

     
 -module(tut1).
 -export([fac/1]).
@@ -157,30 +162,34 @@ fac(1) ->
     1;
 fac(N) ->
     N * fac(N - 1).
-    
Compile the file

-    
-5> c(tut1).
-{ok,tut1}

-    
And now calculate the factorial of 4.

-    
-6> tut1:fac(4).
-24

-    
The first part:

+    
So this is a module, called tut1 that contains a
+      function called fac>, which takes one argument,
+      N.

+    
The first part says that the factorial of 1 is 1.:

     
 fac(1) ->
     1;
-    
says that the factorial of 1 is 1. Note that we end this part
-      with a ";" which indicates that there is more of this function to
-      come. The second part:

+    
Notice that this part ends with a semicolon ";" that indicates
+      that there is more of the function fac> to come.

+    
The second part says that the factorial of N is N multiplied
+      by the factorial of N - 1:

     
 fac(N) ->
     N * fac(N - 1).
-    
says that the factorial of N is N multiplied by the factorial of
-      N - 1. Note that this part ends with a "." saying that there are
+    
Notice that this part ends with a "." saying that there are
       no more parts of this function.

-    
A function can have many arguments. Let's expand the module
-      tut1 with the rather stupid function to multiply two
-      numbers:

+    
Compile the file:

+    
+5> c(tut1).
+{ok,tut1}

+    
And now calculate the factorial of 4.

+    
+6> tut1:fac(4).
+24

+    
Here the function fac> in module tut1 is called
+      with argument 4.

+    
A function can have many arguments. Let us expand the module
+      tut1 with the function to multiply two numbers:

     
 -module(tut1).
 -export([fac/1, mult/2]).
@@ -192,36 +201,36 @@ fac(N) ->
 
 mult(X, Y) ->
     X * Y.
-    
Note that we have also had to expand the -export line
+    
Notice that it is also required to expand the -export line
       with the information that there is another function mult
       with two arguments.

     
Compile:

     
 7> c(tut1).
 {ok,tut1}

-    
and try it out:

+    
Try out the new function mult:

     
 8> tut1:mult(3,4).
 12

-    
In the example above the numbers are integers and the arguments
-      in the functions in the code, N, X, Y are
+    
In this example the numbers are integers and the arguments
+      in the functions in the code N, X, and Y are
       called variables. Variables must start with a capital letter
-      (see the chapter
-      "Variables"
-      in the Erlang Reference Manual). Examples of variables could be
-      Number, ShoeSize, Age etc.

+      (see
+      Variables).
+      Examples of variables are
+      Number, ShoeSize, and Age.

   

 
   

     Atoms
-    
Atoms are another data type in Erlang. Atoms start with a small
-      letter ((see the chapter
-      "Atom"
-      in the Erlang Reference Manual)), for example: charles,
-      centimeter, inch. Atoms are simply names, nothing
-      else. They are not like variables which can have a value.

-    
Enter the next program (file: tut2.erl) which could be
-      useful for converting from inches to centimeters and vice versa:

+    
Atom is another data type in Erlang. Atoms start with a small
+      letter (see
+      Atom),
+      for example, charles,
+      centimeter, and inch. Atoms are simply names, nothing
+      else. They are not like variables, which can have a value.

+    
Enter the next program in a file named tut2.erl). It can be
+      useful for converting from inches to centimeters and conversely:

     
 -module(tut2).
 -export([convert/2]).
@@ -231,27 +240,30 @@ convert(M, inch) ->
 
 convert(N, centimeter) ->
     N * 2.54.
-    
Compile and test:

+    
Compile:

     
 9> c(tut2).
 {ok,tut2}
+

+    
Test:

+ 
 10> tut2:convert(3, inch).
 1.1811023622047243
 11> tut2:convert(7, centimeter).
 17.78

-    
Notice that I have introduced decimals (floating point numbers)
-      without any explanation, but I guess you can cope with that.

-    
See what happens if I enter something other than centimeter or
-      inch in the convert function:

+    
Notice the introduction of decimals (floating point numbers)
+      without any explanation. Hopefully you can cope with that.

+    
Let us see what happens if something other than centimeter or
+      inch is entered in the convert function:

     
 12> tut2:convert(3, miles).
 ** exception error: no function clause matching tut2:convert(3,miles) (tut2.erl, line 4)

     
The two parts of the convert function are called its
-      clauses. Here we see that "miles" is not part of either of
-      the clauses. The Erlang system can't match either of
-      the clauses so we get an error message function_clause.
-      The shell formats the error message nicely, but the error tuple 
-      is saved in the shell's history list and can be output by the shell 
+      clauses. As shown, miles is not part of either of
+      the clauses. The Erlang system cannot match either of
+      the clauses so an error message function_clause is returned.
+      The shell formats the error message nicely, but the error tuple
+      is saved in the shell's history list and can be output by the shell
       command v/1:

     
 13> v(12).
@@ -271,14 +283,15 @@ convert(N, centimeter) ->
       Consider:

     
 tut2:convert(3, inch).
-    
Does this mean that 3 is in inches? Or that 3 is in centimeters
-      and we want to convert it to inches? So Erlang has a way to group
-      things together to make things more understandable. We call these
-      tuples. Tuples are surrounded by "{" and "}".

-    
So we can write {inch,3} to denote 3 inches and
-      {centimeter,5} to denote 5 centimeters. Now let's write a
-      new program which converts centimeters to inches and vice versa.
-      (file tut3.erl).

+    
Does this mean that 3 is in inches? Or does it mean that 3 is
+      in centimeters
+      and is to be converted to inches? Erlang has a way to group
+      things together to make things more understandable. These are called
+      tuples and are surrounded by curly brackets, "{" and "}".

+    
So, {inch,3} denotes 3 inches and
+      {centimeter,5} denotes 5 centimeters. Now let us write a
+      new program that converts centimeters to inches and conversely.
+      Enter the following code in a file called tut3.erl):

     
 -module(tut3).
 -export([convert_length/1]).
@@ -295,47 +308,48 @@ convert_length({inch, Y}) ->
 {centimeter,12.7}
 16> tut3:convert_length(tut3:convert_length({inch, 5})).
 {inch,5.0}

-    
Note on line 16 we convert 5 inches to centimeters and back
-      again and reassuringly get back to the original value. I.e
+    
Notice on line 16 that 5 inches is converted to centimeters and back
+      again and reassuringly get back to the original value. That is,
       the argument to a function can be the result of another function.
-      Pause for a moment and consider how line 16 (above) works.
-      The argument we have given the function {inch,5} is first
-      matched against the first head clause of convert_length
-      i.e. convert_length({centimeter,X}) where it can be seen
+      Consider how line 16 (above) works.
+      The argument given to the function {inch,5} is first
+      matched against the first head clause of convert_length,
+      that is, convert_length({centimeter,X}). It can be seen
       that {centimeter,X} does not match {inch,5}
-      (the head is the bit before the "->"). This having failed, we try
-      the head of the next clause i.e. convert_length({inch,Y}),
-      this matches and Y get the value 5.

-    
We have shown tuples with two parts above, but tuples can have
-      as many parts as we want and contain any valid Erlang
+      (the head is the bit before the "->"). This having failed,
+      let us try
+      the head of the next clause that is, convert_length({inch,Y}).
+      This matches, and Y gets the value 5.

+    
Tuples can have more than two parts, in fact
+      as many parts as you want, and contain any valid Erlang
       term. For example, to represent the temperature of
-      various cities of the world we could write:

+      various cities of the world:

     
 {moscow, {c, -10}}
 {cape_town, {f, 70}}
 {paris, {f, 28}}
-    
Tuples have a fixed number of things in them. We call each thing
-      in a tuple an element. So in the tuple {moscow,{c,-10}},
-      element 1 is moscow and element 2 is {c,-10}. I
-      have chosen c meaning Centigrade (or Celsius) and f
-      meaning Fahrenheit.

+    
Tuples have a fixed number of items in them. Each item in a
+      tuple is called an element. In the tuple
+      {moscow,{c,-10}}, element 1 is moscow and element
+      2 is {c,-10}. Here c represents Celsius and
+      f Fahrenheit.

   

 
   

     Lists
-    
Whereas tuples group things together, we also want to be able to
-      represent lists of things. Lists in Erlang are surrounded by "["
-      and "]". For example, a list of the temperatures of various cities
-      in the world could be:

+    
Whereas tuples group things together, it is also needed to
+      represent lists of things. Lists in Erlang are surrounded by
+      square brackets, "[" and "]". For example, a list of the
+      temperatures of various cities in the world can be:

     
 [{moscow, {c, -10}}, {cape_town, {f, 70}}, {stockholm, {c, -4}},
  {paris, {f, 28}}, {london, {f, 36}}]
-    
Note that this list was so long that it didn't fit on one line.
-      This doesn't matter, Erlang allows line breaks at all "sensible
-      places" but not, for example, in the middle of atoms, integers
-      etc.

-    
A very useful way of looking at parts of lists, is by using "|".
-      This is best explained by an example using the shell.

+    
Notice that this list was so long that it did not fit on one line.
+      This does not matter, Erlang allows line breaks at all "sensible
+      places" but not, for example, in the middle of atoms, integers,
+       and others.

+    
A useful way of looking at parts of lists, is by using "|".
+      This is best explained by an example using the shell:

     
 17> [First |TheRest] = [1,2,3,4,5].
 [1,2,3,4,5]
@@ -343,9 +357,9 @@ convert_length({inch, Y}) ->
 1
 19> TheRest.
 [2,3,4,5]

-    
We use | to separate the first elements of the list from
-      the rest of the list. (First has got value 1 and
-      TheRest value [2,3,4,5].)

+    
To separate the first elements of the list from the rest of the
+      list, | is used. First has got value 1 and
+      TheRest has got the value [2,3,4,5].

     
Another example:

     
 20> [E1, E2 | R] = [1,2,3,4,5,6,7].
@@ -356,10 +370,10 @@ convert_length({inch, Y}) ->
 2
 23> R.
 [3,4,5,6,7]

-    
Here we see the use of | to get the first two elements from
-      the list. Of course if we try to get more elements from the list
-      than there are elements in the list we will get an error. Note
-      also the special case of the list with no elements [].

+    
Here you see the use of | to get the first two elements from
+      the list. If you try to get more elements from the list
+      than there are elements in the list, an error is returned. Notice
+      also the special case of the list with no elements, []:

     
 24> [A, B | C] = [1, 2].
 [1,2]
@@ -369,13 +383,13 @@ convert_length({inch, Y}) ->
 2
 27> C.
 []

-    
In all the examples above, I have been using new variable names,
-      not reusing the old ones: First, TheRest, E1,
-      E2, R, A, B, C. The reason
+    
In the previous examples, new variable names are used, instead of
+      reusing the old ones: First, TheRest, E1,
+      E2, R, A, B, and C. The reason
       for this is that a variable can only be given a value once in its
-      context (scope). I'll get back to this later, it isn't so
-      peculiar as it sounds!

-    
The following example shows how we find the length of a list:

+      context (scope). More about this later.

+    
The following example shows how to find the length of a list.
+     Enter the following code in a file named tut4.erl):

     
 -module(tut4).
 
@@ -385,7 +399,7 @@ list_length([]) ->
     0;    
 list_length([First | Rest]) ->
     1 + list_length(Rest).
-    
Compile (file tut4.erl) and test:

+    
Compile and test:

     
 28> c(tut4).
 {ok,tut4}
@@ -404,14 +418,14 @@ list_length([First | Rest]) ->
       Rest.

     
(Advanced readers only: This is not tail recursive, there is a
       better way to write this function.)

-    
In general we can say we use tuples where we would use "records"
-      or "structs" in other languages and we use lists when we want to
-      represent things which have varying sizes, (i.e. where we would
-      use linked lists in other languages).

-    
Erlang does not have a string data type, instead strings can be
-      represented by lists of ASCII characters. So the list
-      [97,98,99] is equivalent to "abc". The Erlang shell is
-      "clever" and guesses the what sort of list we mean and outputs it
+    
In general, tuples are used where "records"
+      or "structs" are used in other languages. Also, lists are used when
+      representing things with varying sizes, that is, where
+      linked lists are used in other languages.

+    
Erlang does not have a string data type. Instead, strings can be
+      represented by lists of Unicode characters. This implies for example that
+      the list [97,98,99] is equivalent to "abc". The Erlang shell is
+      "clever" and guesses what list you  mean and outputs it
       in what it thinks is the most appropriate form, for example:

     
 30> [97,98,99].
@@ -420,16 +434,17 @@ list_length([First | Rest]) ->
 
   

     Maps
-	
Maps are a set of key to value associations. These associations
-		are encapsulated with "#{" and "}". To create an association from
-		"key" to value 42, we write:

+    
Maps are a set of key to value associations. These associations
+      are encapsulated with "#{" and "}". To create an association
+      from "key" to value 42:

 
 > #{ "key" => 42 }.
 #{"key" => 42}
-    
We will jump straight into the deep end with an example using some
-		interesting features.

-	
The following example shows how we calculate alpha blending using
-		maps to reference color and alpha channels:

+    
Let us jump straight into the deep end with an example using some
+      interesting features.

+    
The following example shows how to calculate alpha blending
+      using maps to reference color and alpha channels. Enter the code
+      in a file named color.erl):

     
 -module(color).
 
@@ -468,7 +483,7 @@ green(#{green := SV, alpha := SA}, #{green := DV, alpha := DA}) ->
     SV*SA + DV*DA*(1.0 - SA).
 blue(#{blue := SV, alpha := SA}, #{blue := DV, alpha := DA}) ->
     SV*SA + DV*DA*(1.0 - SA).
-    
Compile (file color.erl) and test:

+    
Compile and test:

     
 > c(color).
 {ok,color}
@@ -484,50 +499,48 @@ blue(#{blue := SV, alpha := SA}, #{blue := DV, alpha := DA}) ->
     
This example warrants some explanation:

     
 -define(is_channel(V), (is_float(V) andalso V >= 0.0 andalso V =< 1.0)).
-    

-		First we define a macro is_channel to help with our guard tests.
-		This is only here for convenience and to reduce syntax cluttering.
-
-		You can read more about Macros
-		in the Erlang Reference Manual.
-	

+    
First a macro is_channel is defined to help with the
+      guard tests. This is only here for convenience and to reduce
+      syntax cluttering. For more information about macros, see
+      
+      The Preprocessor.
+    

     
 new(R,G,B,A) when ?is_channel(R), ?is_channel(G),
                   ?is_channel(B), ?is_channel(A) ->
     #{red => R, green => G, blue => B, alpha => A}.
-    

-		The function new/4 creates a new map term with and lets the keys
-		red, green, blue and alpha be associated
-		with an initial value. In this case we only allow for float
-		values between and including 0.0 and 1.0 as ensured by the ?is_channel/1 macro
-		for each argument. Only the => operator is allowed when creating a new map.
+    
The function new/4 creates a new map term and lets the keys
+      red, green, blue, and alpha be
+      associated with an initial value. In this case, only float
+      values between and including 0.0 and 1.0 are allowed, as ensured
+      by the ?is_channel/1 macro for each argument. Only the
+      => operator is allowed when creating a new map.
+    

+    
By calling blend/2 on any color term created by
+      new/4, the resulting color can be calculated as
+      determined by the two map terms.
+    

+    
The first thing blend/2 does is to calculate the
+      resulting alpha channel:
     

-	

-		By calling blend/2 on any color term created by new/4 we can calculate
-		the resulting color as determined by the two maps terms.
-	

-	

-		The first thing blend/2 does is to calculate the resulting alpha channel.
-	

     
 alpha(#{alpha := SA}, #{alpha := DA}) ->
     SA + DA*(1.0 - SA).
-    

-		We fetch the value associated with key alpha for both arguments using
-		the := operator. Any other keys
-		in the map are ignored, only the key alpha is required and checked for.
-	

-	
This is also the case for functions red/2, blue/2 and green/2.

+    
The value associated with key alpha is fetched for both
+      arguments using the := operator. The other keys in the
+      map are ignored, only the key alpha is required and
+      checked for.
+    

+    
This is also the case for functions red/2,
+      blue/2, and green/2.

     
 red(#{red := SV, alpha := SA}, #{red := DV, alpha := DA}) ->
     SV*SA + DV*DA*(1.0 - SA).
-    

-		The difference here is that we check for two keys in each map argument. The other keys
-		are ignored.
-	

-    

-		Finally we return the resulting color in blend/3.
-	

+    
The difference here is that a check is made for two keys in
+      each map argument. The other keys are ignored.
+    

+    
Finally, let us return the resulting color in blend/3:
+    

     
 blend(Src,Dst,Alpha) when Alpha > 0.0 ->
     Dst#{
@@ -536,20 +549,20 @@ blend(Src,Dst,Alpha) when Alpha > 0.0 ->
         blue  := blue(Src,Dst) / Alpha,
         alpha := Alpha
     };
-    

-		We update the Dst map with new channel values. The syntax for updating an existing key with a new value is done with := operator.
-	

+    
The Dst map is updated with new channel values. The
+      syntax for updating an existing key with a new value is with the
+      := operator.
+    

   

 
   

     Standard Modules and Manual Pages
-    
Erlang has a lot of standard modules to help you do things. For
-      example, the module io contains a lot of functions to help
-      you do formatted input/output. To look up information about
-      standard modules, the command erl -man can be used at
-      the operating shell or command prompt (i.e. at the same place as
-      that where you started erl). Try the operating system
-      shell command:

+    
Erlang has many standard modules to help you do things. For
+      example, the module io contains many functions that help
+      in doing formatted input/output. To look up information about
+      standard modules, the command erl -man can be used at the
+      operating shell or command prompt (the same place as you started
+      erl). Try the operating system shell command:

     
 % erl -man io
 ERLANG MODULE DEFINITION                                    io(3)
@@ -561,21 +574,21 @@ DESCRIPTION
      This module provides an  interface  to  standard  Erlang  IO
      servers. The output functions all return ok if they are suc-
      ...

-    
If this doesn't work on your system, the documentation is
-      included as HTML in the Erlang/OTP release, or you can read
+    
If this does not work on your system, the documentation is
+      included as HTML in the Erlang/OTP release. You can also read
       the documentation as HTML or download it as PDF from either of
       the sites www.erlang.se (commercial Erlang) or www.erlang.org
-      (open source), for example for release R9B:

+      (open source). For example, for Erlang/OTP release R9B:

     
 http://www.erlang.org/doc/r9b/doc/index.html
   

 
   

     Writing Output to a Terminal
-    
It's nice to be able to do formatted output in these example, so
+    
It is nice to be able to do formatted output in examples, so
       the next example shows a simple way to use the io:format
-      function. Of course, just like all other exported functions, you
-      can test the io:format function in the shell:

+      function. Like all other exported functions, you can test the
+      io:format function in the shell:

     
 31> io:format("hello world~n", []).
 hello world
@@ -589,28 +602,28 @@ ok
 34> io:format("this outputs two Erlang terms: ~w ~w~n", [hello, world]).
 this outputs two Erlang terms: hello world
 ok

-    
The function format/2 (i.e. format with two
+    
The function format/2 (that is, format with two
       arguments) takes two lists. The first one is nearly always a list
-      written between " ". This list is printed out as it stands,
+      written between " ". This list is printed out as it is,
       except that each ~w is replaced by a term taken in order from
       the second list. Each ~n is replaced by a new line.
       The io:format/2 function itself returns the atom ok
       if everything goes as planned. Like other functions in Erlang, it
       crashes if an error occurs. This is not a fault in Erlang, it is
       a deliberate policy. Erlang has sophisticated mechanisms to
-      handle errors which we will show later. As an exercise, try to
-      make io:format crash, it shouldn't be difficult. But
+      handle errors which are shown later. As an exercise, try to
+      make io:format crash, it should not be difficult. But
       notice that although io:format crashes, the Erlang shell
       itself does not crash.

   

 
   

     A Larger Example
-    
Now for a larger example to consolidate what we have learnt so
-      far. Assume we have a list of temperature readings from a number
-      of cities in the world. Some of them are in Celsius (Centigrade)
-      and some in Fahrenheit (as in the previous list). First let's
-      convert them all to Celsius, then let's print out the data neatly.

+    
Now for a larger example to consolidate what you have learnt so
+      far. Assume that you have a list of temperature readings from a number
+      of cities in the world. Some of them are in Celsius
+      and some in Fahrenheit (as in the previous list). First let us
+      convert them all to Celsius, then let us print the data neatly.

     
 %% This module is in file tut5.erl
 
@@ -642,50 +655,50 @@ stockholm       -4 c
 paris           -2.2222222222222223 c
 london          2.2222222222222223 c
 ok

-    
Before we look at how this program works, notice that we have
-      added a few comments to the code. A comment starts with a %
-      character and goes on to the end of the line. Note as well that
+    
Before looking at how this program works, notice that
+      a few comments are added to the code. A comment starts with a
+      %-character and goes on to the end of the line. Notice also that
       the -export([format_temps/1]). line only includes
-      the function format_temps/1, the other functions are
-      local functions, i.e. they are not visible from outside
+      the function format_temps/1. The other functions are
+      local functions, that is, they are not visible from outside
       the module tut5.

-    
Note as well that when testing the program from the shell, I had
-      to spread the input over two lines as the line was too long.

-    
When we call format_temps the first time, City
+    
Notice also that when testing the program from the shell,
+      the input is spread over two lines as the line was too long.

+    
When format_temps is called the first time, City
       gets the value {moscow,{c,-10}} and Rest is
-      the rest of the list. So we call the function
-      print_temp(convert_to_celsius({moscow,{c,-10}})).

-    
Here we see a function call as
+      the rest of the list. So the function
+      print_temp(convert_to_celsius({moscow,{c,-10}})) is called.

+    
Here is a function call as
       convert_to_celsius({moscow,{c,-10}}) as the argument to
-      the function print_temp. When we nest function
-      calls like this we execute (evaluate) them from the inside out.
-      I.e. we first evaluate convert_to_celsius({moscow,{c,-10}})
+      the function print_temp. When function calls are nested
+      like this, they execute (evaluate) from the inside out.
+      That is, first convert_to_celsius({moscow,{c,-10}}) is evaluated,
       which gives the value {moscow,{c,-10}} as the temperature
-      is already in Celsius and then we evaluate
-      print_temp({moscow,{c,-10}}). The function
-      convert_to_celsius works in a similar way to
+      is already in Celsius. Then print_temp({moscow,{c,-10}})
+      is evaluated.
+      The function convert_to_celsius works in a similar way to
       the convert_length function in the previous example.

     
print_temp simply calls io:format in a similar way
-      to what has been described above. Note that ~-15w says to print
+      to what has been described above. Notice that ~-15w says to print
       the "term" with a field length (width) of 15 and left justify it.
-      (io(3)).

-    
Now we call format_temps(Rest) with the rest of the list
+      (see the io(3)) manual page in STDLIB.

+    
Now format_temps(Rest) is called with the rest of the list
       as an argument. This way of doing things is similar to the loop
-      constructs in other languages. (Yes, this is recursion, but don't
+      constructs in other languages. (Yes, this is recursion, but do not
       let that worry you.) So the same format_temps function is
       called again, this time City gets the value
-      {cape_town,{f,70}} and we repeat the same procedure as
-      before. We go on doing this until the list becomes empty, i.e. [],
+      {cape_town,{f,70}} and the same procedure is repeated as
+      before. This is done until the list becomes empty, that is [],
       which causes the first clause format_temps([]) to match.
       This simply returns (results in) the atom ok, so
       the program ends.

   

 
   

-    Matching, Guards and Scope of Variables
-    
It could be useful to find the maximum and minimum temperature
+    Matching, Guards, and Scope of Variables
+    
It can be useful to find the maximum and minimum temperature
       in lists like this. Before extending the program to do this,
-      let's look at functions for finding the maximum value of
+      let us look at functions for finding the maximum value of
       the elements in a list:

     
 -module(tut6).
@@ -705,53 +718,57 @@ list_max([Head|Rest], Result_so_far)  ->
 {ok,tut6}
 38> tut6:list_max([1,2,3,4,5,7,4,3,2,1]).
 7
-

First note that we have two functions here with the same name - list_max. However each of these takes a different number +

First notice that two functions have the same name, + list_max. However, each of these takes a different number of arguments (parameters). In Erlang these are regarded as - completely different functions. Where we need to distinguish - between these functions we write name/arity, where - name is the name of the function and arity is + completely different functions. Where you need to distinguish + between these functions, you write Name/Arity, where + Name is the function name and Arity is the number of arguments, in this case list_max/1 and list_max/2.

-

This is an example where we walk through a list "carrying" a - value with us, in this case Result_so_far. +

In this example you walk through a list "carrying" a + value, in this case Result_so_far. list_max/1 simply assumes that the max value of the list is the head of the list and calls list_max/2 with the rest - of the list and the value of the head of the list, in the above - this would be list_max([2,3,4,5,7,4,3,2,1],1). If we tried + of the list and the value of the head of the list. In the above + this would be list_max([2,3,4,5,7,4,3,2,1],1). If you tried to use list_max/1 with an empty list or tried to use it - with something which isn't a list at all, we would cause an error. - Note that the Erlang philosophy is not to handle errors of this + with something that is not a list at all, you would cause an error. + Notice that the Erlang philosophy is not to handle errors of this type in the function they occur, but to do so elsewhere. More about this later.

-

In list_max/2 we walk down the list and use Head +

In list_max/2, you walk down the list and use Head instead of Result_so_far when Head > - Result_so_far. when is a special word we use before - the -> in the function to say that we should only use this part - of the function if the test which follows is true. We call tests - of this type a guard. If the guard isn't true (we say - the guard fails), we try the next part of the function. In this - case if Head isn't greater than Result_so_far then - it must be smaller or equal to is, so we don't need a guard on - the next part of the function.

-

Some useful operators in guards are, < less than, > - greater than, == equal, >= greater or equal, =< less or - equal, /= not equal. (See the chapter - "Guard Sequences" in the Erlang Reference Manual.)

-

To change the above program to one which works out the minimum - value of the element in a list, all we would need to do is to + Result_so_far. when is a special word used before + the -> in the function to say that you only use this part + of the function if the test that follows is true. A test + of this type is called guard. If the guard is false (that is, + the guard fails), the next part of the function is tried. In this + case, if Head is not greater than Result_so_far, then + it must be smaller or equal to it. This means that a guard on + the next part of the function is not needed.

+

Some useful operators in guards are: +

< less than + > greater than + == equal + >= greater or equal + =< less or equal + /= not equal +

(see Guard Sequences).

+

To change the above program to one that works out the minimum + value of the element in a list, you only need to write < instead of >. (But it would be wise to change - the name of the function to list_min :-).)

-

Remember that I mentioned earlier that a variable could only be - given a value once in its scope? In the above we see, for example, - that Result_so_far has been given several values. This is - OK since every time we call list_max/2 we create a new - scope and one can regard the Result_so_far as a completely + the name of the function to list_min.)

+

Earlier it was mentioned that a variable can only be + given a value once in its scope. In the above you see + that Result_so_far is given several values. This is + OK since every time you call list_max/2 you create a new + scope and one can regard Result_so_far as a different variable in each scope.

Another way of creating and giving a variable a value is by using - the match operator = . So if I write M = 5, a variable - called M will be created and given the value 5. If, in - the same scope I then write M = 6, I'll get an error. Try + the match operator = . So if you write M = 5, a variable + called M is created with the value 5. If, in + the same scope, you then write M = 6, an error is returned. Try this out in the shell:

 39> M = 5.
@@ -771,21 +788,21 @@ list_max([Head|Rest], Result_so_far)  ->
 paris
 45> Y.
 {f,28}
-

Here we see that X gets the value paris and +

Here X gets the value paris and Y{f,28}.

-

Of course if we try to do the same again with another city, we - get an error:

+

If you try to do the same again with another city, + an error is returned:

 46> {X, Y} = {london, {f, 36}}.
 ** exception error: no match of right hand side value {london,{f,36}}

Variables can also be used to improve the readability of - programs, for example, in the list_max/2 function above, - we could write:

+ programs. For example, in function list_max/2 above, + you can write:

list_max([Head|Rest], Result_so_far) when Head > Result_so_far -> New_result_far = Head, list_max(Rest, New_result_far); -

which is possibly a little clearer.

+

This is possibly a little clearer.

@@ -824,9 +841,9 @@ reverse([], Reversed_List) -> {ok,tut8} 53> tut8:reverse([1,2,3]). [3,2,1] -

Consider how Reversed_List is built. It starts as [], we - then successively take off the heads of the list to be reversed - and add them to the the Reversed_List, as shown in +

Consider how Reversed_List is built. It starts as [], + then successively the heads are taken off of the list to be reversed + and added to the the Reversed_List, as shown in the following:

reverse([1|2,3], []) => @@ -840,14 +857,15 @@ reverse([3|[]], [2,1]) => reverse([], [3,2,1]) => [3,2,1] -

The module lists contains a lot of functions for - manipulating lists, for example for reversing them, so before you - write a list manipulating function it is a good idea to check - that one isn't already written for you. (see - lists(3)).

-

Now let's get back to the cities and temperatures, but take a more - structured approach this time. First let's convert the whole list - to Celsius as follows and test the function:

+

The module lists contains many functions for + manipulating lists, for example, for reversing them. So before + writing a list-manipulating function it is a good idea to check + if one not already is written for you + (see the lists(3) + manual page in STDLIB).

+

Now let us get back to the cities and temperatures, but take a more + structured approach this time. First let us convert the whole list + to Celsius as follows:

-module(tut7). -export([format_temps/1]). @@ -864,6 +882,7 @@ convert_list_to_c([City | Rest]) -> convert_list_to_c([]) -> []. +

Test the function:

 54> c(tut7).
 {ok, tut7}.
@@ -874,26 +893,26 @@ convert_list_to_c([]) ->
  {stockholm,{c,-4}},
  {paris,{c,-2.2222222222222223}},
  {london,{c,2.2222222222222223}}]
-

Looking at this bit by bit:

+

Explanation:

format_temps(List_of_cities) -> convert_list_to_c(List_of_cities). -

Here we see that format_temps/1 calls +

Here format_temps/1 calls convert_list_to_c/1. convert_list_to_c/1 takes off the head of the List_of_cities, converts it to Celsius if needed. The | operator is used to add the (maybe) converted to the converted rest of the list:

[Converted_City | convert_list_to_c(Rest)]; -

or

+

or:

[City | convert_list_to_c(Rest)]; -

We go on doing this until we get to the end of the list (i.e. - the list is empty):

+

This is done until the end of the list is reached, that is, + the list is empty:

convert_list_to_c([]) -> []. -

Now we have converted the list, we add a function to print it:

+

Now when the list is converted, a function to print it is added:

-module(tut7). -export([format_temps/1]). @@ -928,12 +947,12 @@ stockholm -4 c paris -2.2222222222222223 c london 2.2222222222222223 c ok -

We now have to add a function to find the cities with - the maximum and minimum temperatures. The program below isn't - the most efficient way of doing this as we walk through the list +

Now a function has to be added to find the cities with + the maximum and minimum temperatures. The following program is not + the most efficient way of doing this as you walk through the list of cities four times. But it is better to first strive for clarity and correctness and to make programs efficient only if - really needed.

+ needed.

If and Case

The function find_max_and_min works out the maximum and - minimum temperature. We have introduced a new construct here - if. If works as follows:

+ minimum temperature. A new construct, if, is introduced here. + If works as follows:

if Condition 1 -> @@ -1016,14 +1035,15 @@ if Condition 4 -> Action 4 end -

Note there is no ";" before end! Conditions are the same - as guards, tests which succeed or fail. Erlang starts at the top - until it finds a condition which succeeds and then it evaluates +

Notice that there is no ";" before end. Conditions do + the same as guards, that is, tests that succeed or fail. Erlang + starts at the top + and tests until it finds a condition that succeeds. Then it evaluates (performs) the action following the condition and ignores all - other conditions and action before the end. If no - condition matches, there will be a run-time failure. A condition - which always is succeeds is the atom, true and this is - often used last in an if meaning do the action following + other conditions and actions before the end. If no + condition matches, a run-time failure occurs. A condition + that always succeeds is the atom true. This is + often used last in an if, meaning, do the action following the true if all other conditions have failed.

The following is a short program to show the workings of if.

@@ -1039,10 +1059,10 @@ test_if(A, B) -> B == 6 -> io:format("B == 6~n", []), b_equals_6; - A == 2, B == 3 -> %i.e. A equals 2 and B equals 3 + A == 2, B == 3 -> %That is A equals 2 and B equals 3 io:format("A == 2, B == 3~n", []), a_equals_2_b_equals_3; - A == 1 ; B == 7 -> %i.e. A equals 1 or B equals 7 + A == 1 ; B == 7 -> %That is A equals 1 or B equals 7 io:format("A == 1 ; B == 7~n", []), a_equals_1_or_b_equals_7 end. @@ -1068,19 +1088,19 @@ a_equals_1_or_b_equals_7 66> tut9:test_if(33, 33). ** exception error: no true branch found when evaluating an if expression in function tut9:test_if/2 (tut9.erl, line 5) -

Notice that tut9:test_if(33,33) did not cause any - condition to succeed so we got the run time error - if_clause, here nicely formatted by the shell. See the chapter - "Guard Sequences" in the Erlang Reference Manual for details - of the many guard tests available. case is another - construct in Erlang. Recall that we wrote the - convert_length function as:

+

Notice that tut9:test_if(33,33) does not cause any + condition to succeed. This leads to the run time error + if_clause, here nicely formatted by the shell. See + Guard Sequences + for details of the many guard tests available.

+

case is another construct in Erlang. Recall that the + convert_length function was written as:

convert_length({centimeter, X}) -> {inch, X / 2.54}; convert_length({inch, Y}) -> {centimeter, Y * 2.54}. -

We could also write the same program as:

+

The same program can also be written as:

-module(tut10). -export([convert_length/1]). @@ -1099,12 +1119,13 @@ convert_length(Length) -> {centimeter,15.24} 69> tut10:convert_length({centimeter, 2.5}). {inch,0.984251968503937} -

Notice that both case and if have return values, i.e. in the above example case returned +

Both case and if have return values, that is, + in the above example case returned either {inch,X/2.54} or {centimeter,Y*2.54}. The behaviour of case can also be modified by using guards. - An example should hopefully clarify this. The following example - tells us the length of a month, given the year. We need to know - the year of course, since February has 29 days in a leap year.

+ The following example clarifies this. It + tells us the length of a month, given the year. + The year must be known, since February has 29 days in a leap year.

-module(tut11). -export([month_length/2]). @@ -1150,57 +1171,58 @@ month_length(Year, Month) ->
- Built In Functions (BIFs) -

Built in functions (BIFs) are functions which for some reason are - built in to the Erlang virtual machine. BIFs often implement - functionality that is impossible to implement in Erlang or is too - inefficient to implement in Erlang. Some BIFs can be called - by use of the function name only, but they by default belong - to the erlang module. So for example, the call to the BIF trunc + Built-In Functions (BIFs) +

BIFs are functions that for some reason are + built-in to the Erlang virtual machine. BIFs often implement + functionality that is impossible or is too + inefficient to implement in Erlang. Some BIFs can be called + using the function name only but they are by default belonging + to the erlang module. For example, the call to the + BIF trunc below is equivalent to a call to erlang:trunc.

-

As you can see, we first find out if a year is leap or not. If a - year is divisible by 400, it is a leap year. To find this out we - first divide the year by 400 and use the built in function - trunc (more later) to cut off any decimals. We then - multiply by 400 again and see if we get back the same value. For - example, year 2004:

+

As shown, first it is checked if a year is leap. If a + year is divisible by 400, it is a leap year. To determine this, + first divide the year by 400 and use the BIF + trunc (more about this later) to cut off any decimals. Then + multiply by 400 again and see if the same value is returned again. + For example, year 2004:

2004 / 400 = 5.01 trunc(5.01) = 5 5 * 400 = 2000 -

and we can see that we got back 2000 which is not the same as - 2004, so 2004 isn't divisible by 400. Year 2000:

+

2000 is not the same as 2004, so 2004 is not divisible by 400. + Year 2000:

2000 / 400 = 5.0 trunc(5.0) = 5 5 * 400 = 2000 -

so we have a leap year. The next two tests, which check if the year is - divisible by 100 or 4, are done in the same way. The first - if returns leap or not_leap which ends up - in the variable Leap. We use this variable in the guard - for feb in the following case which tells us how +

That is, a leap year. The next two trunc-tests evaluate + if the year is divisible by 100 or 4 in the same way. The first + if returns leap or not_leap, which lands up + in the variable Leap. This variable is used in the guard + for feb in the following case that tells us how long the month is.

-

This example showed the use of trunc. An easier way would - be to use the Erlang operator rem, which gives the remainder - after division. For example:

+

This example showed the use of trunc. It is easier + to use the Erlang operator rem that gives the remainder + after division, for example:

 74> 2004 rem 400.
 4
-

so instead of writing:

+

So instead of writing:

trunc(Year / 400) * 400 == Year -> leap; -

we could write:

+

it can be written:

Year rem 400 == 0 -> leap; -

There are many other built in functions (BIF) such as - trunc. Only a few built in functions can be used in guards, +

There are many other BIFs such as + trunc. Only a few BIFs can be used in guards, and you cannot use functions you have defined yourself in guards. - (see the chapter - "Guard Sequences" in the Erlang Reference Manual) (Aside for - advanced readers: This is to ensure that guards don't have side - effects.) Let's play with a few of these functions in the shell:

+ (see + Guard Sequences) + (For advanced readers: This is to ensure that guards do not have side + effects.) Let us play with a few of these functions in the shell:

 75> trunc(5.6).
 5
@@ -1218,7 +1240,7 @@ false
 true
 82> is_tuple([paris, {c, 30}]).
 false
-

All the above can be used in guards. Now for some which can't be +

All of these can be used in guards. Now for some BIFs that cannot be used in guards:

 83> atom_to_list(hello).
@@ -1227,22 +1249,22 @@ false
goodbye 85> integer_to_list(22). "22" -

The 3 BIFs above do conversions which would be difficult (or +

These three BIFs do conversions that would be difficult (or impossible) to do in Erlang.

- Higher Order Functions (Funs) + Higher-Order Functions (Funs)

Erlang, like most modern functional programming languages, has - higher order functions. We start with an example using the shell:

+ higher-order functions. Here is an example using the shell:

 86> Xf = fun(X) -> X * 2 end.
 #Fun<erl_eval.5.123085357>
 87> Xf(5).
 10
-

What we have done here is to define a function which doubles - the value of number and assign this function to a variable. Thus - Xf(5) returned the value 10. Two useful functions when +

Here is defined a function that doubles + the value of a number and assigned this function to a variable. Thus + Xf(5) returns value 10. Two useful functions when working with lists are foreach and map, which are defined as follows:

@@ -1258,17 +1280,16 @@ map(Fun, []) -> [].

These two functions are provided in the standard module lists. foreach takes a list and applies a fun to - every element in the list, map creates a new list by + every element in the list. map creates a new list by applying a fun to every element in a list. Going back to - the shell, we start by using map and a fun to add 3 to + the shell, map is used and a fun to add 3 to every element of a list:

 88> Add_3 = fun(X) -> X + 3 end.
 #Fun<erl_eval.5.123085357>
 89> lists:map(Add_3, [1,2,3]).
 [4,5,6]
-

Now let's print out the temperatures in a list of cities (yet - again):

+

Let us (again) print the temperatures in a list of cities:

 90> Print_City = fun({City, {X, Temp}}) -> io:format("~-15w ~w ~w~n",
 [City, X, Temp]) end.
@@ -1281,7 +1302,7 @@ stockholm       c -4
 paris           f 28
 london          f 36
 ok
-

We will now define a fun which can be used to go through a list +

Let us now define a fun that can be used to go through a list of cities and temperatures and transform them all to Celsius.

-module(tut13). @@ -1303,21 +1324,21 @@ convert_list_to_c(List) -> {stockholm,{c,-4}}, {paris,{c,-2}}, {london,{c,2}}] -

The convert_to_c function is the same as before, but we - use it as a fun:

+

The convert_to_c function is the same as before, but here + it is used as a fun:

lists:map(fun convert_to_c/1, List) -

When we use a function defined elsewhere as a fun we can refer - to it as Function/Arity (remember that Arity = - number of arguments). So in the map call we write - lists:map(fun convert_to_c/1, List). As you can see +

When a function defined elsewhere is used as a fun, it can be referred + to as Function/Arity (remember that Arity = + number of arguments). So in the map-call + lists:map(fun convert_to_c/1, List) is written. As shown, convert_list_to_c becomes much shorter and easier to understand.

The standard module lists also contains a function sort(Fun, List) where Fun is a fun with two - arguments. This fun should return true if the the first + arguments. This fun returns true if the first argument is less than the second argument, or else false. - We add sorting to the convert_list_to_c:

+ Sorting is added to the convert_list_to_c:

{paris,{c,-2}}, {london,{c,2}}, {cape_town,{c,21}}] -

In sort we use the fun:

+

In sort the fun is used:

Temp1 < Temp2 end,]]> -

Here we introduce the concept of an anonymous variable - "_". This is simply shorthand for a variable which is going to - get a value, but we will ignore the value. This can be used - anywhere suitable, not just in fun's. +

Here the concept of an anonymous variable + "_" is introduced. This is simply shorthand for a variable that + gets a value, but the value is ignored. This can be used + anywhere suitable, not just in funs. returns true if Temp1 is less than Temp2.

-- cgit v1.2.3