diff options
Diffstat (limited to 'system/doc/reference_manual')
| -rw-r--r-- | system/doc/reference_manual/character_set.xml | 18 | ||||
| -rw-r--r-- | system/doc/reference_manual/code_loading.xml | 117 | ||||
| -rw-r--r-- | system/doc/reference_manual/data_types.xml | 161 | ||||
| -rw-r--r-- | system/doc/reference_manual/distributed.xml | 120 | ||||
| -rw-r--r-- | system/doc/reference_manual/errors.xml | 67 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 732 | ||||
| -rw-r--r-- | system/doc/reference_manual/functions.xml | 79 | ||||
| -rw-r--r-- | system/doc/reference_manual/introduction.xml | 53 | ||||
| -rw-r--r-- | system/doc/reference_manual/macros.xml | 75 | ||||
| -rw-r--r-- | system/doc/reference_manual/modules.xml | 170 | ||||
| -rw-r--r-- | system/doc/reference_manual/patterns.xml | 2 | ||||
| -rw-r--r-- | system/doc/reference_manual/ports.xml | 114 | ||||
| -rw-r--r-- | system/doc/reference_manual/processes.xml | 90 | ||||
| -rw-r--r-- | system/doc/reference_manual/records.xml | 68 | ||||
| -rw-r--r-- | system/doc/reference_manual/typespec.xml | 242 |
15 files changed, 1178 insertions, 930 deletions
diff --git a/system/doc/reference_manual/character_set.xml b/system/doc/reference_manual/character_set.xml index b09b484582..d6989373bf 100644 --- a/system/doc/reference_manual/character_set.xml +++ b/system/doc/reference_manual/character_set.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2014</year><year>2014</year> + <year>2014</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,7 +31,7 @@ <section> <title>Character Set</title> - <p>In Erlang 4.8/OTP R5A the syntax of Erlang tokens was extended to + <p>Since Erlang 4.8/OTP R5A, the syntax of Erlang tokens is extended to allow the use of the full ISO-8859-1 (Latin-1) character set. This is noticeable in the following ways:</p> <list type="bulleted"> @@ -98,7 +98,7 @@ <cell align="center" valign="middle">ø - ÿ</cell> <cell align="left" valign="middle">Lowercase letters</cell> </row> - <tcaption>Character Classes.</tcaption> + <tcaption>Character Classes</tcaption> </table> <p>In Erlang/OTP R16B the syntax of Erlang tokens was extended to handle Unicode. The support is limited to @@ -111,13 +111,13 @@ </section> <section> <title>Source File Encoding</title> - <p>The Erlang source file <marker - id="encoding">encoding</marker> is selected by a + <marker id="encoding"></marker> + <p>The Erlang source file <c>encoding</c> is selected by a comment in one of the first two lines of the source file. The first string that matches the regular expression <c>coding\s*[:=]\s*([-a-zA-Z0-9])+</c> selects the encoding. If - the matching string is not a valid encoding it is ignored. The - valid encodings are <c>Latin-1</c> and <c>UTF-8</c> where the + the matching string is an invalid encoding, it is ignored. The + valid encodings are <c>Latin-1</c> and <c>UTF-8</c>, where the case of the characters can be chosen freely.</p> <p>The following example selects UTF-8 as default encoding:</p> <pre> @@ -127,7 +127,7 @@ %% For this file we have chosen encoding = Latin-1</pre> <pre> %% -*- coding: latin-1 -*-</pre> - <p>The default encoding for Erlang source files was changed from - Latin-1 to UTF-8 in Erlang OTP 17.0.</p> + <p>The default encoding for Erlang source files is changed from + Latin-1 to UTF-8 since Erlang/OTP 17.0.</p> </section> </chapter> diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml index b5b5704df5..48ec32d6df 100644 --- a/system/doc/reference_manual/code_loading.xml +++ b/system/doc/reference_manual/code_loading.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2014</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,35 +29,39 @@ <file>code_loading.xml</file> </header> <p>How code is compiled and loaded is not a language issue, but - is system dependent. This chapter describes compilation and - code loading in Erlang/OTP with pointers to relevant parts of + is system-dependent. This section describes compilation and + code loading in Erlang/OTP with references to relevant parts of the documentation.</p> <section> <title>Compilation</title> <p>Erlang programs must be <em>compiled</em> to object code. - The compiler can generate a new file which contains the object - code. The current abstract machine which runs the object code is + The compiler can generate a new file that contains the object + code. The current abstract machine, which runs the object code, is called BEAM, therefore the object files get the suffix <c>.beam</c>. The compiler can also generate a binary which can be loaded directly.</p> - <p>The compiler is located in the Kernel module <c>compile</c>, see - <c>compile(3)</c>.</p> + <p>The compiler is located in the module <c>compile</c> (see the + <seealso marker="compiler:compile">compile(3)</seealso> manual page in + Compiler).</p> <pre> compile:file(Module) compile:file(Module, Options)</pre> <p>The Erlang shell understands the command <c>c(Module)</c> which both compiles and loads <c>Module</c>.</p> - <p>There is also a module <c>make</c> which provides a set of - functions similar to the UNIX type Make functions, see - <c>make(3)</c>.</p> - <p>The compiler can also be accessed from the OS prompt, see - <c>erl(1)</c>.</p> + <p>There is also a module <c>make</c>, which provides a set of + functions similar to the UNIX type Make functions, see the + <seealso marker="tools:make">make(3)</seealso> + manual page in Tools.</p> + <p>The compiler can also be accessed from the OS prompt, see the + <seealso marker="erts:erl">erl(1)</seealso> manual page in ERTS.</p> <pre> % erl -compile <input>Module1</input>...<input>ModuleN</input> % erl -make</pre> <p>The <c>erlc</c> program provides an even better way to compile - modules from the shell, see <c>erlc(1)</c>. It understands a + modules from the shell, see the + <seealso marker="erts:erlc">erlc(1)</seealso> manual page in ERTS. + It understands a number of flags that can be used to define macros, add search paths for include files, and more.</p> <pre> @@ -68,13 +72,17 @@ compile:file(Module, Options)</pre> <marker id="loading"></marker> <title>Code Loading</title> <p>The object code must be <em>loaded</em> into the Erlang runtime - system. This is handled by the <em>code server</em>, see - <c>code(3)</c>.</p> - <p>The code server loads code according to a code loading strategy + system. This is handled by the <em>code server</em>, see the + <seealso marker="kernel:code">code(3)</seealso> + manual page in Kernel.</p> + <p>The code server loads code according to a code loading strategy, which is either <em>interactive</em> (default) or - <em>embedded</em>. In interactive mode, code are searched for in + <em>embedded</em>. In interactive mode, code is searched for in a <em>code path</em> and loaded when first referenced. In - embedded mode, code is loaded at start-up according to a <em>boot script</em>. This is described in <em>System Principles</em>.</p> + embedded mode, code is loaded at start-up according to a + <em>boot script</em>. This is described in + <seealso marker="doc/system_principles:system_principles#code_loading"> + System Principles </seealso>.</p> </section> <section> @@ -86,16 +94,17 @@ compile:file(Module, Options)</pre> the system for the first time, the code becomes 'current'. If then a new instance of the module is loaded, the code of the previous instance becomes 'old' and the new instance becomes 'current'.</p> - <p>Both old and current code is valid, and may be evaluated + <p>Both old and current code is valid, and can be evaluated concurrently. Fully qualified function calls always refer to - current code. Old code may still be evaluated because of processes + current code. Old code can still be evaluated because of processes lingering in the old code.</p> - <p>If a third instance of the module is loaded, the code server will - remove (purge) the old code and any processes lingering in it will - be terminated. Then the third instance becomes 'current' and + <p>If a third instance of the module is loaded, the code server + removes (purges) the old code and any processes lingering in it is + terminated. Then the third instance becomes 'current' and the previously current code becomes 'old'.</p> <p>To change from old code to current code, a process must make a - fully qualified function call. Example:</p> + fully qualified function call.</p> + <p><em>Example:</em></p> <pre> -module(m). -export([loop/0]). @@ -109,60 +118,62 @@ loop() -> loop() end.</pre> <p>To make the process change code, send the message - <c>code_switch</c> to it. The process then will make a fully - qualified call to <c>m:loop()</c> and change to current code. - Note that <c>m:loop/0</c> must be exported.</p> - <p>For code replacement of funs to work, the syntax - <c>fun Module:FunctionName/Arity</c> should be used.</p> + <c>code_switch</c> to it. The process then makes a fully + qualified call to <c>m:loop()</c> and changes to current code. + Notice that <c>m:loop/0</c> must be exported.</p> + <p>For code replacement of funs to work, use the syntax + <c>fun Module:FunctionName/Arity</c>.</p> </section> <section> <marker id="on_load"></marker> - <title>Running a function when a module is loaded</title> + <title>Running a Function When a Module is Loaded</title> <warning> - <p>The <c>on_load</c> feature should be considered experimental - as there are a number of known weak points in current semantics - which therefore might also change in future releases:</p> + <p>The <c>on_load</c> feature is to be considered experimental + as there are a number of known weak points in current semantics, + which therefore might change in future Erlang/OTP releases:</p> <list> - <item><p>Doing external call in on_load to the module itself + <item><p>Doing external call in <c>on_load</c> to the module itself leads to deadlock.</p></item> <item><p>At module upgrade, other processes calling the module - get suspended waiting for on_load to finish. This can be very bad + get suspended waiting for <c>on_load</c> to finish. This can be very bad for applications with demands on realtime characteristics.</p></item> - <item><p>At module upgrade, no rollback is done if the on_load function fails. - The system will be left in a bad limbo state without any working + <item><p>At module upgrade, no rollback is done if the + <c>on_load</c> function fails. + The system is left in a bad limbo state without any working and reachable instance of the module.</p></item> </list> - <p>The problems with module upgrade described above could be fixed in future - releases by changing the behaviour to not make the module reachable until - after the on_load function has successfully returned.</p> + <p>The problems with module upgrade described above can be fixed in future + Erlang/OTP releases by changing the behaviour to not make the module reachable until + after the <c>on_load</c> function has successfully returned.</p> </warning> - <p>The <c>-on_load()</c> directive names a function that should - be run automatically when a module a loaded. Its syntax is:</p> + <p>The <c>-on_load()</c> directive names a function that is to + be run automatically when a module is loaded.</p> + <p>Its syntax is as follows:</p> <pre> -on_load(Name/0).</pre> - <p>It is not necessary to export the function. It will be called in a - freshly spawned process (which will be terminated as soon as the function + <p>It is not necessary to export the function. It is called in a + freshly spawned process (which terminates as soon as the function returns). The function must return <c>ok</c> if the module is to - be remained loaded and become callable, or any other value if the module - is to be unloaded. Generating an exception will also cause the + remain loaded and become callable, or any other value if the module + is to be unloaded. Generating an exception also causes the module to be unloaded. If the return value is not an atom, - a warning error report will be sent to the error logger.</p> + a warning error report is sent to the error logger.</p> <p>A process that calls any function in a module whose <c>on_load</c> - function has not yet returned will be suspended until the <c>on_load</c> + function has not yet returned, is suspended until the <c>on_load</c> function has returned.</p> - <p>In embedded mode, all modules will be loaded first and then - will all on_load functions be called. The system will be - terminated unless all of the on_load functions return + <p>In embedded mode, first all modules are loaded. + Then all <c>on_load</c> functions are called. The system is + terminated unless all of the <c>on_load</c> functions return <c>ok</c></p>. - <p>Example:</p> + <p><em>Example:</em></p> <pre> -module(m). @@ -174,7 +185,7 @@ load_my_nifs() -> erlang:load_nif(NifPath, Info).</pre> <p>If the call to <c>erlang:load_nif/2</c> fails, the module - will be unloaded and there will be warning report sent to + is unloaded and a warning report is sent to the error loader.</p> </section> diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml index ad92143179..6226fa2f31 100644 --- a/system/doc/reference_manual/data_types.xml +++ b/system/doc/reference_manual/data_types.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,12 +28,12 @@ <rev></rev> <file>data_types.xml</file> </header> + <p>Erlang provides a number of data types, which are listed in + this section.</p> <section> <title>Terms</title> - <p>Erlang provides a number of data types which are listed in this - chapter. A piece of data of any data type is called a - <em>term</em>.</p> + <p>A piece of data of any data type is called a <em>term</em>.</p> </section> <section> @@ -48,13 +48,13 @@ <em><c>char</c></em>.</item> <item><em><c>base</c></em><c>#</c><em><c>value</c></em> <br></br> - Integer with the base <em><c>base</c></em>, which must be an + Integer with the base <em><c>base</c></em>, that must be an integer in the range 2..36. <br></br> In Erlang 5.2/OTP R9B and earlier versions, the allowed range is 2..16.</item> </list> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>42.</input> 42 @@ -76,11 +76,11 @@ <section> <title>Atom</title> - <p>An atom is a literal, a constant with name. An atom should be + <p>An atom is a literal, a constant with name. An atom is to be enclosed in single quotes (') if it does not begin with a lower-case letter or if it contains other characters than alphanumeric characters, underscore (_), or @.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> hello phone_number @@ -91,11 +91,11 @@ phone_number <section> <title>Bit Strings and Binaries</title> <p>A bit string is used to store an area of untyped memory.</p> - <p>Bit Strings are expressed using the + <p>Bit strings are expressed using the <seealso marker="expressions#bit_syntax">bit syntax</seealso>.</p> - <p>Bit Strings which consists of a number of bits which is evenly - divisible by eight are called Binaries</p> - <p>Examples:</p> + <p>Bit strings that consist of a number of bits that are evenly + divisible by eight, are called <em>binaries</em></p> + <p><em>Examples:</em></p> <pre> 1> <input><<10,20>>.</input> <<10,20>> @@ -103,12 +103,14 @@ phone_number <<"ABC">> 1> <input><<1:1,0:1>>.</input> <<2:2>></pre> - <p>More examples can be found in Programming Examples.</p> + <p>For more examples, + see <seealso marker="doc/programming_examples:bit_syntax"> + Programming Examples</seealso>.</p> </section> <section> <title>Reference</title> - <p>A reference is a term which is unique in an Erlang runtime + <p>A reference is a term that is unique in an Erlang runtime system, created by calling <c>make_ref/0</c>.</p> </section> @@ -117,34 +119,42 @@ phone_number <p>A fun is a functional object. Funs make it possible to create an anonymous function and pass the function itself -- not its name -- as argument to other functions.</p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> 1> <input>Fun1 = fun (X) -> X+1 end.</input> #Fun<erl_eval.6.39074546> 2> <input>Fun1(2).</input> 3</pre> - <p>Read more about funs in <seealso marker="expressions#funs">Fun Expressions</seealso>. More examples can be found in Programming - Examples.</p> + <p>Read more about funs in <seealso marker="expressions#funs"> + Fun Expressions</seealso>. For more examples, see + <seealso marker="doc/programming_examples:funs"> + Programming Examples</seealso>.</p> </section> <section> <title>Port Identifier</title> - <p>A port identifier identifies an Erlang port. <c>open_port/2</c>, - which is used to create ports, will return a value of this type.</p> + <p>A port identifier identifies an Erlang port.</p> + <p><c>open_port/2</c>, which is used to create ports, returns + a value of this data type.</p> <p>Read more about ports in <seealso marker="ports">Ports and Port Drivers</seealso>.</p> </section> <section> <title>Pid</title> - <p>A process identifier, pid, identifies a process. - <c>spawn/1,2,3,4</c>, <c>spawn_link/1,2,3,4</c> and - <c>spawn_opt/4</c>, which are used to create processes, return - values of this type. Example:</p> + <p>A process identifier, pid, identifies a process.</p> + <p>The following BIFs, which are used to create processes, return + values of this data type:</p> + <list type="bulleted"> + <item><c>spawn/1,2,3,4</c></item> + <item><c>spawn_link/1,2,3,4</c></item> + <item><c>spawn_opt/4</c></item> + </list> + <p><em>Example:</em></p> <pre> 1> <input>spawn(m, f, []).</input> <0.51.0></pre> - <p>The BIF <c>self()</c> returns the pid of the calling process. - Example:</p> + <p>In the following example, the BIF <c>self()</c> returns + the pid of the calling process:</p> <pre> -module(m). -export([loop/0]). @@ -167,14 +177,14 @@ who_are_you</pre> <section> <title>Tuple</title> - <p>Compound data type with a fixed number of terms:</p> + <p>A tuple is a compound data type with a fixed number of terms:</p> <pre> {Term1,...,TermN}</pre> <p>Each term <c>Term</c> in the tuple is called an <em>element</em>. The number of elements is said to be the <em>size</em> of the tuple.</p> <p>There exists a number of BIFs to manipulate tuples.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>P = {adam,24,{july,29}}.</input> {adam,24,{july,29}} @@ -192,7 +202,8 @@ adam <section> <title>Map</title> - <p>Compound data type with a variable number of key-value associations:</p> + <p>A map is a compound data type with a variable number of + key-value associations:</p> <pre> #{Key1=>Value1,...,KeyN=>ValueN}</pre> <p>Each key-value association in the map is called an @@ -200,7 +211,7 @@ adam called <em>elements</em>. The number of association pairs is said to be the <em>size</em> of the map.</p> <p>There exists a number of BIFs to manipulate maps.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>M1 = #{name=>adam,age=>24,date=>{july,29}}.</input> #{age => 24,date => {july,29},name => adam} @@ -215,16 +226,18 @@ adam 6> <input>map_size(#{}).</input> 0</pre> <p>A collection of maps processing functions can be found in - the STDLIB module <seealso marker="stdlib:maps"><c>maps</c></seealso>.</p> - <p>Read more about <seealso marker="expressions#map_expressions">Maps</seealso>.</p> + <seealso marker="stdlib:maps"><c>maps</c></seealso> manual page + in STDLIB.</p> + <p>Read more about maps in <seealso marker="expressions#map_expressions"> + Map Expressions</seealso>.</p> <note> - <p>Maps are considered experimental during OTP 17.</p> + <p>Maps are considered to be experimental during Erlang/OTP R17.</p> </note> </section> <section> <title>List</title> - <p>Compound data type with a variable number of terms.</p> + <p>A list is a compound data type with a variable number of terms.</p> <pre> [Term1,...,TermN]</pre> <p>Each term <c>Term</c> in the list is called an @@ -232,20 +245,21 @@ adam the <em>length</em> of the list.</p> <p>Formally, a list is either the empty list <c>[]</c> or consists of a <em>head</em> (first element) and a <em>tail</em> - (remainder of the list) which is also a list. The latter can + (remainder of the list). + The <em>tail</em> is also a list. The latter can be expressed as <c>[H|T]</c>. The notation - <c>[Term1,...,TermN]</c> above is actually shorthand for + <c>[Term1,...,TermN]</c> above is equivalent with the list <c>[Term1|[...|[TermN|[]]]]</c>.</p> - <p>Example: <br></br> -<c>[]</c> is a list, thus <br></br> + <p><em>Example:</em></p> +<p><c>[]</c> is a list, thus <br></br> <c>[c|[]]</c> is a list, thus <br></br> <c>[b|[c|[]]]</c> is a list, thus <br></br> -<c>[a|[b|[c|[]]]]</c> is a list, or in short <c>[a,b,c]</c>.</p> - <p></p> +<c>[a|[b|[c|[]]]]</c> is a list, or in short <c>[a,b,c]</c></p> + <p>A list where the tail is a list is sometimes called a <em>proper list</em>. It is allowed to have a list where the tail is not a - list, for example <c>[a|b]</c>. However, this type of list is of + list, for example, <c>[a|b]</c>. However, this type of list is of little practical use.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>L1 = [a,2,{c,4}].</input> [a,2,{c,4}] @@ -262,18 +276,19 @@ a 7> <input>length([]).</input> 0</pre> <p>A collection of list processing functions can be found in - the STDLIB module <c>lists</c>.</p> + the <seealso marker="stdlib:lists">lists</seealso> manual + page in STDLIB.</p> </section> <section> <title>String</title> <p>Strings are enclosed in double quotes ("), but is not a - data type in Erlang. Instead a string <c>"hello"</c> is - shorthand for the list <c>[$h,$e,$l,$l,$o]</c>, that is + data type in Erlang. Instead, a string <c>"hello"</c> is + shorthand for the list <c>[$h,$e,$l,$l,$o]</c>, that is, <c>[104,101,108,108,111]</c>.</p> <p>Two adjacent string literals are concatenated into one. This is - done at compile-time and does not incur any runtime overhead. - Example:</p> + done in the compilation, thus, does not incur any runtime overhead.</p> + <p><em>Example:</em></p> <pre> "string" "42"</pre> <p>is equivalent to</p> @@ -285,12 +300,13 @@ a <title>Record</title> <p>A record is a data structure for storing a fixed number of elements. It has named fields and is similar to a struct in C. - However, record is not a true data type. Instead record + However, a record is not a true data type. Instead, record expressions are translated to tuple expressions during compilation. Therefore, record expressions are not understood by - the shell unless special actions are taken. See <c>shell(3)</c> - for details.</p> - <p>Examples:</p> + the shell unless special actions are taken. For details, see the + <seealso marker="stdlib:shell">shell(3)</seealso> manual + page in STDLIB).</p> + <p><em>Examples:</em></p> <pre> -module(person). -export([new/2]). @@ -304,14 +320,15 @@ new(Name, Age) -> {person,ernie,44}</pre> <p>Read more about records in <seealso marker="records">Records</seealso>. More examples can be - found in Programming Examples.</p> + found in <seealso marker="doc/programming_examples:records"> + Programming Examples</seealso>.</p> </section> <section> <title>Boolean</title> <p>There is no Boolean data type in Erlang. Instead the atoms <c>true</c> and <c>false</c> are used to denote Boolean values.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>2 =< 3</input>. true @@ -330,76 +347,80 @@ true</pre> </row> <row> <cell align="left" valign="middle">\b</cell> - <cell align="left" valign="middle">backspace</cell> + <cell align="left" valign="middle">Backspace</cell> </row> <row> <cell align="left" valign="middle">\d</cell> - <cell align="left" valign="middle">delete</cell> + <cell align="left" valign="middle">Delete</cell> </row> <row> <cell align="left" valign="middle">\e</cell> - <cell align="left" valign="middle">escape</cell> + <cell align="left" valign="middle">Escape</cell> </row> <row> <cell align="left" valign="middle">\f</cell> - <cell align="left" valign="middle">form feed</cell> + <cell align="left" valign="middle">Form feed</cell> </row> <row> <cell align="left" valign="middle">\n</cell> - <cell align="left" valign="middle">newline</cell> + <cell align="left" valign="middle">Newline</cell> </row> <row> <cell align="left" valign="middle">\r</cell> - <cell align="left" valign="middle">carriage return</cell> + <cell align="left" valign="middle">Carriage return</cell> </row> <row> <cell align="left" valign="middle">\s</cell> - <cell align="left" valign="middle">space</cell> + <cell align="left" valign="middle">Space</cell> </row> <row> <cell align="left" valign="middle">\t</cell> - <cell align="left" valign="middle">tab</cell> + <cell align="left" valign="middle">Tab</cell> </row> <row> <cell align="left" valign="middle">\v</cell> - <cell align="left" valign="middle">vertical tab</cell> + <cell align="left" valign="middle">Vertical tab</cell> </row> <row> <cell align="left" valign="middle">\XYZ, \YZ, \Z</cell> - <cell align="left" valign="middle">character with octal representation XYZ, YZ or Z</cell> + <cell align="left" valign="middle">Character with octal + representation XYZ, YZ or Z</cell> </row> <row> <cell align="left" valign="middle">\xXY</cell> - <cell align="left" valign="middle">character with hexadecimal representation XY</cell> + <cell align="left" valign="middle">Character with hexadecimal + representation XY</cell> </row> <row> <cell align="left" valign="middle">\x{X...}</cell> - <cell align="left" valign="middle">character with hexadecimal representation; X... is one or more hexadecimal characters</cell> + <cell align="left" valign="middle">Character with hexadecimal + representation; X... is one or more hexadecimal characters</cell> </row> <row> <cell align="left" valign="middle">\^a...\^z <br></br> \^A...\^Z</cell> - <cell align="left" valign="middle">control A to control Z</cell> + <cell align="left" valign="middle">Control A to control Z</cell> </row> <row> <cell align="left" valign="middle">\'</cell> - <cell align="left" valign="middle">single quote</cell> + <cell align="left" valign="middle">Single quote</cell> </row> <row> <cell align="left" valign="middle">\"</cell> - <cell align="left" valign="middle">double quote</cell> + <cell align="left" valign="middle">Double quote</cell> </row> <row> <cell align="left" valign="middle">\\</cell> - <cell align="left" valign="middle">backslash</cell> + <cell align="left" valign="middle">Backslash</cell> </row> - <tcaption>Recognized Escape Sequences.</tcaption> + <tcaption>Recognized Escape Sequences</tcaption> </table> </section> <section> <title>Type Conversions</title> - <p>There are a number of BIFs for type conversions. Examples:</p> + <p>There are a number of BIFs for type conversions.</p> + <p><em>Examples:</em></p> <pre> 1> <input>atom_to_list(hello).</input> "hello" diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml index 88f98bc106..fb83e356f9 100644 --- a/system/doc/reference_manual/distributed.xml +++ b/system/doc/reference_manual/distributed.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,22 +36,24 @@ runtime system is called a <em>node</em>. Message passing between processes at different nodes, as well as links and monitors, are transparent when pids are used. Registered names, however, are - local to each node. This means the node must be specified as well - when sending messages etc. using registered names.</p> + local to each node. This means that the node must be specified as well + when sending messages, and so on, using registered names.</p> <p>The distribution mechanism is implemented using TCP/IP sockets. - How to implement an alternative carrier is described in <em>ERTS User's Guide</em>.</p> + How to implement an alternative carrier is described in the + <seealso marker="erts:alt_dist">ERTS User's Guide</seealso>.</p> </section> <section> <title>Nodes</title> - <p>A <em>node</em> is an executing Erlang runtime system which has - been given a name, using the command line flag <c>-name</c> + <p>A <em>node</em> is an executing Erlang runtime system that has + been given a name, using the command-line flag <c>-name</c> (long names) or <c>-sname</c> (short names).</p> - <p>The format of the node name is an atom <c>name@host</c> where - <c>name</c> is the name given by the user and <c>host</c> is + <p>The format of the node name is an atom <c>name@host</c>. + <c>name</c> is the name given by the user. <c>host</c> is the full host name if long names are used, or the first part of the host name if short names are used. <c>node()</c> returns - the name of the node. Example:</p> + the name of the node.</p> + <p><em>Example:</em></p> <pre> % <input>erl -name dilbert</input> ([email protected])1> <input>node().</input> @@ -69,16 +71,16 @@ dilbert@uab</pre> <section> <title>Node Connections</title> <p>The nodes in a distributed Erlang system are loosely connected. - The first time the name of another node is used, for example if + The first time the name of another node is used, for example, if <c>spawn(Node,M,F,A)</c> or <c>net_adm:ping(Node)</c> is called, - a connection attempt to that node will be made.</p> + a connection attempt to that node is made.</p> <p>Connections are by default transitive. If a node A connects to - node B, and node B has a connection to node C, then node A will - also try to connect to node C. This feature can be turned off by - using the command line flag <c>-connect_all false</c>, see - <c>erl(1)</c>.</p> + node B, and node B has a connection to node C, then node A + also tries to connect to node C. This feature can be turned off by + using the command-line flag <c>-connect_all false</c>, see the + <seealso marker="erts:erl">erl(1)</seealso> manual page in ERTS.</p> <p>If a node goes down, all connections to that node are removed. - Calling <c>erlang:disconnect_node(Node)</c> will force disconnection + Calling <c>erlang:disconnect_node(Node)</c> forces disconnection of a node.</p> <p>The list of (visible) nodes currently connected to is returned by <c>nodes()</c>.</p> @@ -89,23 +91,24 @@ dilbert@uab</pre> <p>The Erlang Port Mapper Daemon <em>epmd</em> is automatically started at every host where an Erlang node is started. It is responsible for mapping the symbolic node names to machine - addresses. See <c>epmd(1)</c>.</p> + addresses. See the + <seealso marker="erts:epmd">epmd(1)</seealso> manual page in ERTS.</p> </section> <section> <title>Hidden Nodes</title> <p>In a distributed Erlang system, it is sometimes useful to connect to a node without also connecting to all other nodes. - An example could be some kind of O&M functionality used to - inspect the status of a system without disturbing it. For this - purpose, a <em>hidden node</em> may be used.</p> - <p>A hidden node is a node started with the command line flag + An example is some kind of O&M functionality used to + inspect the status of a system, without disturbing it. For this + purpose, a <em>hidden node</em> can be used.</p> + <p>A hidden node is a node started with the command-line flag <c>-hidden</c>. Connections between hidden nodes and other nodes are not transitive, they must be set up explicitly. Also, hidden nodes does not show up in the list of nodes returned by <c>nodes()</c>. Instead, <c>nodes(hidden)</c> or <c>nodes(connected)</c> must be used. This means, for example, - that the hidden node will not be added to the set of nodes that + that the hidden node is not added to the set of nodes that <c>global</c> is keeping track of.</p> <p>This feature was added in Erlang 5.0/OTP R7.</p> </section> @@ -114,9 +117,11 @@ dilbert@uab</pre> <title>C Nodes</title> <p>A <em>C node</em> is a C program written to act as a hidden node in a distributed Erlang system. The library <em>Erl_Interface</em> - contains functions for this purpose. Refer to the documentation - for Erl_Interface and <em>Interoperability Tutorial</em> for more - information about C nodes.</p> + contains functions for this purpose. For more information about + C nodes, see the <seealso marker="erl_interface:ei_users_guide"> + Erl_Interface</seealso> application and + <seealso marker="doc/tutorial:introduction#interoperability tutorial"> + Interoperability Tutorial.</seealso>.</p> </section> <section> @@ -125,7 +130,7 @@ dilbert@uab</pre> with each other. In a network of different Erlang nodes, it is built into the system at the lowest possible level. Each node has its own <em>magic cookie</em>, which is an Erlang atom.</p> - <p>When a nodes tries to connect to another node, the magic cookies + <p>When a node tries to connect to another node, the magic cookies are compared. If they do not match, the connected node rejects the connection.</p> <p>At start-up, a node has a random atom assigned as its magic @@ -141,8 +146,8 @@ dilbert@uab</pre> the local node assume that all other nodes have the same cookie <c>Cookie</c>.</p> <p>Thus, groups of users with identical cookie files get Erlang - nodes which can communicate freely and without interference from - the magic cookie system. Users who want run nodes on separate + nodes that can communicate freely and without interference from + the magic cookie system. Users who want to run nodes on separate file systems must make certain that their cookie files are identical on the different file systems.</p> <p>For a node <c>Node1</c> with magic cookie <c>Cookie</c> to be @@ -154,19 +159,25 @@ dilbert@uab</pre> <p>The default when a connection is established between two nodes, is to immediately connect all other visible nodes as well. This way, there is always a fully connected network. If there are - nodes with different cookies, this method might be inappropriate - and the command line flag <c>-connect_all false</c> must be set, - see <seealso marker="erts:erl">erl(1)</seealso>.</p> + nodes with different cookies, this method can be inappropriate + and the command-line flag <c>-connect_all false</c> must be set, + see the <seealso marker="erts:erl">erl(1)</seealso> + manual page in ERTS.</p> <p>The magic cookie of the local node is retrieved by calling <c>erlang:get_cookie()</c>.</p> </section> <section> <title>Distribution BIFs</title> - <p>Some useful BIFs for distributed programming, see - <c>erlang(3)</c> for more information:</p> + <p>Some useful BIFs for distributed programming + (for more information, see the <seealso marker="erts:erlang"> + erlang(3)</seealso> manual page in ERTS:</p> <table> <row> + <cell align="left" valign="middle"><em>BIF</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>erlang:disconnect_node(Node)</c></cell> <cell align="left" valign="middle">Forces the disconnection of a node.</cell> </row> @@ -180,7 +191,9 @@ dilbert@uab</pre> </row> <row> <cell align="left" valign="middle"><c>monitor_node(Node, true|false)</c></cell> - <cell align="left" valign="middle">Monitor the status of <c>Node</c>. A message<c>{nodedown, Node}</c> is received if the connection to it is lost.</cell> + <cell align="left" valign="middle">Monitors the status of + <c>Node</c>. A message<c>{nodedown, Node}</c> is received + if the connection to it is lost.</cell> </row> <row> <cell align="left" valign="middle"><c>node()</c></cell> @@ -196,11 +209,16 @@ dilbert@uab</pre> </row> <row> <cell align="left" valign="middle"><c>nodes(Arg)</c></cell> - <cell align="left" valign="middle">Depending on <c>Arg</c>, this function can return a list not only of visible nodes, but also hidden nodes and previously known nodes, etc.</cell> + <cell align="left" valign="middle">Depending on <c>Arg</c>, + this function can return a list not only of visible nodes, + but also hidden nodes and previously known nodes, and so on.</cell> </row> <row> <cell align="left" valign="middle"><c>erlang:set_cookie(Node, Cookie)</c></cell> - <cell align="left" valign="middle">Sets the magic cookie used when connecting to <c>Node</c>. If <c>Node</c> is the current node, <c>Cookie</c> will be used when connecting to all new nodes.</cell> + <cell align="left" valign="middle">Sets the magic cookie used + when connecting to <c>Node</c>. If <c>Node</c> is the + current node, <c>Cookie</c> is used when connecting to + all new nodes.</cell> </row> <row> <cell align="left" valign="middle"><c>spawn[_link|_opt](Node, Fun)</c></cell> @@ -210,18 +228,24 @@ dilbert@uab</pre> <cell align="left" valign="middle"><c>spawn[_link|opt](Node, Module, FunctionName, Args)</c></cell> <cell align="left" valign="middle">Creates a process at a remote node.</cell> </row> - <tcaption>Distribution BIFs.</tcaption> + <tcaption>Distribution BIFs</tcaption> </table> </section> <section> - <title>Distribution Command Line Flags</title> - <p>Examples of command line flags used for distributed programming, - see <c>erl(1)</c> for more information:</p> + <title>Distribution Command-Line Flags</title> + <p>Examples of command-line flags used for distributed programming + (for more information, see the <seealso marker="erts:erl">erl(1) + </seealso> manual page in ERTS:</p> <table> <row> + <cell align="left" valign="middle"><em>Command-Line Flag</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>-connect_all false</c></cell> - <cell align="left" valign="middle">Only explicit connection set-ups will be used.</cell> + <cell align="left" valign="middle">Only explicit connection + set-ups are used.</cell> </row> <row> <cell align="left" valign="middle"><c>-hidden</c></cell> @@ -239,16 +263,20 @@ dilbert@uab</pre> <cell align="left" valign="middle"><c>-sname Name</c></cell> <cell align="left" valign="middle">Makes a runtime system into a node, using short node names.</cell> </row> - <tcaption>Distribution Command Line Flags.</tcaption> + <tcaption>Distribution Command-Line Flags</tcaption> </table> </section> <section> <title>Distribution Modules</title> <p>Examples of modules useful for distributed programming:</p> - <p>In Kernel:</p> + <p>In the Kernel application:</p> <table> <row> + <cell align="left" valign="middle"><em>Module</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>global</c></cell> <cell align="left" valign="middle">A global name registration facility.</cell> </row> @@ -266,9 +294,13 @@ dilbert@uab</pre> </row> <tcaption>Kernel Modules Useful For Distribution.</tcaption> </table> - <p>In STDLIB:</p> + <p>In the STDLIB application:</p> <table> <row> + <cell align="left" valign="middle"><em>Module</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>slave</c></cell> <cell align="left" valign="middle">Start and control of slave nodes.</cell> </row> diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml index dde6e68f4a..66ecf6aa94 100644 --- a/system/doc/reference_manual/errors.xml +++ b/system/doc/reference_manual/errors.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -38,12 +38,12 @@ <item>Run-time errors</item> <item>Generated errors</item> </list> - <p>A compile-time error, for example a syntax error, should not + <p>A compile-time error, for example a syntax error, does not cause much trouble as it is caught by the compiler.</p> <p>A logical error is when a program does not behave as intended, - but does not crash. An example could be that nothing happens when + but does not crash. An example is that nothing happens when a button in a graphical user interface is clicked.</p> - <p>A run-time error is when a crash occurs. An example could be + <p>A run-time error is when a crash occurs. An example is when an operator is applied to arguments of the wrong type. The Erlang programming language has built-in features for handling of run-time errors.</p> @@ -54,23 +54,23 @@ of class <c>error</c>. </p> <p>A generated error is when the code itself calls - <c>exit/1</c> or <c>throw/1</c>. Note that emulated run-time + <c>exit/1</c> or <c>throw/1</c>. Notice that emulated run-time errors are not denoted as generated errors here. </p> <p>Generated errors are exceptions of classes <c>exit</c> and <c>throw</c>. </p> <p>When a run-time error or generated error occurs in Erlang, - execution for the process which evaluated + execution for the process that evaluated the erroneous expression is stopped. This is referred to as a <em>failure</em>, that execution or evaluation <em>fails</em>, or that the process <em>fails</em>, - <em>terminates</em> or <em>exits</em>. Note that a process may + <em>terminates</em>, or <em>exits</em>. Notice that a process can terminate/exit for other reasons than a failure.</p> - <p>A process that terminates will emit an <em>exit signal</em> with + <p>A process that terminates emits an <em>exit signal</em> with an <em>exit reason</em> that says something about which error - has occurred. Normally, some information about the error will - be printed to the terminal.</p> + has occurred. Normally, some information about the error is + printed to the terminal.</p> </section> <section> @@ -78,10 +78,12 @@ <p>Exceptions are run-time errors or generated errors and are of three different classes, with different origins. The <seealso marker="expressions#try">try</seealso> expression - (appeared in Erlang 5.4/OTP-R10B) + (new in Erlang 5.4/OTP R10B) can distinguish between the different classes, whereas the <seealso marker="expressions#catch">catch</seealso> - expression can not. They are described in the Expressions chapter.</p> + expression cannot. They are described in + <seealso marker="expressions">Expressions + </seealso>.</p> <table> <row> <cell align="left" valign="middle"><em>Class</em></cell> @@ -89,7 +91,9 @@ </row> <row> <cell align="left" valign="middle"><c>error</c></cell> - <cell align="left" valign="middle">Run-time error for example <c>1+a</c>, or the process called <c>erlang:error/1,2</c> (appeared in Erlang 5.4/OTP-R10B)</cell> + <cell align="left" valign="middle">Run-time error, + for example, <c>1+a</c>, or the process called + <c>erlang:error/1,2</c> (new in Erlang 5.4/OTP R10B)</cell> </row> <row> <cell align="left" valign="middle"><c>exit</c></cell> @@ -102,11 +106,11 @@ <tcaption>Exception Classes.</tcaption> </table> <p>An exception consists of its class, an exit reason - (the <seealso marker="#exit_reasons">Exit Reason</seealso>), - and a stack trace (that aids in finding the code location of + (see <seealso marker="#exit_reasons">Exit Reason</seealso>), + and a stack trace (which aids in finding the code location of the exception).</p> <p>The stack trace can be retrieved using - <c>erlang:get_stacktrace/0</c> (new in Erlang 5.4/OTP-R10B) + <c>erlang:get_stacktrace/0</c> (new in Erlang 5.4/OTP R10B) from within a <c>try</c> expression, and is returned for exceptions of class <c>error</c> from a <c>catch</c> expression.</p> <p>An exception of class <c>error</c> is also known as a run-time @@ -114,38 +118,38 @@ </section> <section> - <title>Handling of Run-Time Errors in Erlang</title> + <title>Handling of Run-time Errors in Erlang</title> <section> <title>Error Handling Within Processes</title> <p>It is possible to prevent run-time errors and other exceptions from causing the process to terminate by using <c>catch</c> or - <c>try</c>, see the Expressions chapter about - <seealso marker="expressions#catch">Catch</seealso> - and <seealso marker="expressions#try">Try</seealso>.</p> + <c>try</c>, see <seealso marker="expressions"> + Expressions</seealso> about + <seealso marker="expressions#catch">catch</seealso> + and <seealso marker="expressions#try">try</seealso>.</p> </section> <section> <title>Error Handling Between Processes</title> <p>Processes can monitor other processes and detect process terminations, see - the <seealso marker="processes#errors">Processes</seealso> - chapter.</p> + <seealso marker="processes#errors">Processes</seealso>.</p> </section> </section> <section> <marker id="exit_reasons"></marker> <title>Exit Reasons</title> - <p>When a run-time error occurs, - that is an exception of class <c>error</c>, - the exit reason is a tuple <c>{Reason,Stack}</c>. + <p>When a run-time error occurs, + that is an exception of class <c>error</c>. + The exit reason is a tuple <c>{Reason,Stack}</c>, where <c>Reason</c> is a term indicating the type of error:</p> <table> <row> <cell align="left" valign="middle"><em>Reason</em></cell> - <cell align="left" valign="middle"><em>Type of error</em></cell> + <cell align="left" valign="middle"><em>Type of Error</em></cell> </row> <row> <cell align="left" valign="middle"><c>badarg</c></cell> @@ -181,7 +185,7 @@ </row> <row> <cell align="left" valign="middle"><c>{badfun,F}</c></cell> - <cell align="left" valign="middle">There is something wrong with a fun <c>F</c>.</cell> + <cell align="left" valign="middle">Something is wrong with a fun <c>F</c>.</cell> </row> <row> <cell align="left" valign="middle"><c>{badarity,F}</c></cell> @@ -201,14 +205,17 @@ </row> <row> <cell align="left" valign="middle"><c>system_limit</c></cell> - <cell align="left" valign="middle">A system limit has been reached. See Efficiency Guide for information about system limits.</cell> + <cell align="left" valign="middle">A system limit has been reached. + See <seealso marker="doc/efficiency_guide:advanced"> + Efficiency Guide</seealso> for information about system limits. + </cell> </row> - <tcaption>Exit Reasons.</tcaption> + <tcaption>Exit Reasons</tcaption> </table> <p><c>Stack</c> is the stack of function calls being evaluated when the error occurred, given as a list of tuples <c>{Module,Name,Arity}</c> with the most recent function call - first. The most recent function call tuple may in some + first. The most recent function call tuple can in some cases be <c>{Module,Name,[Arg]}</c>.</p> </section> </chapter> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 62a344ad58..fd3cfabd3d 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,13 +28,17 @@ <rev></rev> <file>expressions.xml</file> </header> - <p>In this chapter, all valid Erlang expressions are listed. + <p>In this section, all valid Erlang expressions are listed. When writing Erlang programs, it is also allowed to use macro- and record expressions. However, these expressions are expanded during compilation and are in that sense not true Erlang expressions. Macro- and record expressions are covered in - separate chapters: <seealso marker="macros">Macros</seealso> and - <seealso marker="records">Records</seealso>.</p> + separate sections: + </p> + <list type="bulleted"> + <item><p><seealso marker="macros">Preprocessor</seealso></p></item> + <item><p><seealso marker="records">Records</seealso></p></item> + </list> <section> <title>Expression Evaluation</title> @@ -48,15 +52,15 @@ Expr1 + Expr2</code> performed.</p> <p>Many of the operators can only be applied to arguments of a certain type. For example, arithmetic operators can only be - applied to numbers. An argument of the wrong type will cause - a <c>badarg</c> run-time error.</p> + applied to numbers. An argument of the wrong type causes + a <c>badarg</c> runtime error.</p> </section> <section> <marker id="term"></marker> <title>Terms</title> <p>The simplest form of expression is a term, that is an integer, - float, atom, string, list, map or tuple. + float, atom, string, list, map, or tuple. The return value is the term itself.</p> </section> @@ -65,9 +69,10 @@ Expr1 + Expr2</code> <p>A variable is an expression. If a variable is bound to a value, the return value is this value. Unbound variables are only allowed in patterns.</p> - <p>Variables start with an uppercase letter or underscore (_) - and may contain alphanumeric characters, underscore and @. - Examples:</p> + <p>Variables start with an uppercase letter or underscore (_). + Variables can contain alphanumeric characters, underscore and <c>@</c>. + </p> + <p><em>Examples:</em></p> <pre> X Name1 @@ -77,18 +82,20 @@ _ _Height</pre> <p>Variables are bound to values using <seealso marker="patterns">pattern matching</seealso>. Erlang - uses <em>single assignment</em>, a variable can only be bound + uses <em>single assignment</em>, that is, a variable can only be bound once.</p> <p>The <em>anonymous variable</em> is denoted by underscore (_) and can be used when a variable is required but its value can be - ignored. Example:</p> + ignored.</p> + <p><em>Example:</em></p> <pre> [H|_] = [1,2,3]</pre> - <p>Variables starting with underscore (_), for example + <p>Variables starting with underscore (_), for example, <c>_Height</c>, are normal variables, not anonymous. They are - however ignored by the compiler in the sense that they will not - generate any warnings for unused variables. Example: The following - code</p> + however ignored by the compiler in the sense that they do not + generate any warnings for unused variables.</p> + <p><em>Example:</em></p> + <p>The following code:</p> <pre> member(_, []) -> [].</pre> @@ -96,36 +103,37 @@ member(_, []) -> <pre> member(Elem, []) -> [].</pre> - <p>This will however cause a warning for an unused variable + <p>This causes a warning for an unused variable, <c>Elem</c>, if the code is compiled with the flag <c>warn_unused_vars</c> set. Instead, the code can be rewritten to:</p> <pre> member(_Elem, []) -> [].</pre> - <p>Note that since variables starting with an underscore are - not anonymous, this will match:</p> + <p>Notice that since variables starting with an underscore are + not anonymous, this matches:</p> <pre> {_,_} = {1,2}</pre> - <p>But this will fail:</p> + <p>But this fails:</p> <pre> {_N,_N} = {1,2}</pre> <p>The scope for a variable is its function clause. Variables bound in a branch of an <c>if</c>, <c>case</c>, or <c>receive</c> expression must be bound in all branches - to have a value outside the expression, otherwise they - will be regarded as 'unsafe' outside the expression.</p> + to have a value outside the expression. Otherwise they + are regarded as 'unsafe' outside the expression.</p> <p>For the <c>try</c> expression introduced in - Erlang 5.4/OTP-R10B, variable scoping is limited so that + Erlang 5.4/OTP R10B, variable scoping is limited so that variables bound in the expression are always 'unsafe' outside - the expression. This will be improved.</p> + the expression. This is to be improved.</p> </section> <section> <marker id="pattern"></marker> <title>Patterns</title> - <p>A pattern has the same structure as a term but may contain - unbound variables. Example:</p> + <p>A pattern has the same structure as a term but can contain + unbound variables.</p> + <p><em>Example:</em></p> <pre> Name1 [H|T] @@ -136,13 +144,13 @@ Name1 <section> <title>Match Operator = in Patterns</title> <p>If <c>Pattern1</c> and <c>Pattern2</c> are valid patterns, - then the following is also a valid pattern:</p> + the following is also a valid pattern:</p> <pre> Pattern1 = Pattern2</pre> <p>When matched against a term, both <c>Pattern1</c> and - <c>Pattern2</c> will be matched against the term. The idea - behind this feature is to avoid reconstruction of terms. - Example:</p> + <c>Pattern2</c> are matched against the term. The idea + behind this feature is to avoid reconstruction of terms.</p> + <p><em>Example:</em></p> <pre> f({connect,From,To,Number,Options}, To) -> Signal = {connect,From,To,Number,Options}, @@ -163,16 +171,20 @@ f(Signal, To) -> <pre> f("prefix" ++ Str) -> ...</pre> <p>This is syntactic sugar for the equivalent, but harder to - read</p> + read:</p> <pre> f([$p,$r,$e,$f,$i,$x | Str]) -> ...</pre> </section> <section> <title>Expressions in Patterns</title> - <p>An arithmetic expression can be used within a pattern, if - it uses only numeric or bitwise operators, and if its value - can be evaluated to a constant at compile-time. Example:</p> + <p>An arithmetic expression can be used within a pattern if + it meets both of the following two conditions:</p> + <list type="bulleted"> + <item>It uses only numeric or bitwise operators.</item> + <item>Its value can be evaluated to a constant when complied.</item> + </list> + <p><em>Example:</em></p> <pre> case {Value, Result} of {?THRESHOLD+1, ok} -> ...</pre> @@ -182,21 +194,21 @@ case {Value, Result} of <section> <title>Match</title> + <p>The following matches <c>Expr1</c>, a pattern, against + <c>Expr2</c>:</p> <pre> Expr1 = Expr2</pre> - <p>Matches <c>Expr1</c>, a pattern, against <c>Expr2</c>. - If the matching succeeds, any unbound variable in the pattern + <p>If the matching succeeds, any unbound variable in the pattern becomes bound and the value of <c>Expr2</c> is returned.</p> - <p>If the matching fails, a <c>badmatch</c> run-time error will - occur.</p> - <p>Examples:</p> + <p>If the matching fails, a <c>badmatch</c> run-time error occurs.</p> + <p><em>Examples:</em></p> <pre> 1> <input>{A, B} = {answer, 42}.</input> {answer,42} 2> <input>A.</input> answer 3> <input>{C, D} = [1, 2].</input> -** exception error: no match of right hand side value [1,2]</pre> +** exception error: no match of right-hand side value [1,2]</pre> </section> <section> @@ -210,27 +222,28 @@ ExprM:ExprF(Expr1,...,ExprN)</pre> <c>ExprF</c> must be an atom or an expression that evaluates to an atom. The function is said to be called by using the <em>fully qualified function name</em>. This is often referred - to as a <em>remote</em> or <em>external function call</em>. - Example:</p> + to as a <em>remote</em> or <em>external function call</em>.</p> + <p><em>Example:</em></p> <code type="none"> lists:keysearch(Name, 1, List)</code> <p>In the second form of function calls, <c>ExprF(Expr1,...,ExprN)</c>, <c>ExprF</c> must be an atom or evaluate to a fun.</p> - <p>If <c>ExprF</c> is an atom the function is said to be called by + <p>If <c>ExprF</c> is an atom, the function is said to be called by using the <em>implicitly qualified function name</em>. If the function <c>ExprF</c> is locally defined, it is called. - Alternatively if <c>ExprF</c> is explicitly imported from module - <c>M</c>, <c>M:ExprF(Expr1,...,ExprN)</c> is called. If + Alternatively, if <c>ExprF</c> is explicitly imported from the + <c>M</c> module, <c>M:ExprF(Expr1,...,ExprN)</c> is called. If <c>ExprF</c> is neither declared locally nor explicitly imported, <c>ExprF</c> must be the name of an automatically - imported BIF. Examples:</p> + imported BIF. </p> + <p><em>Examples:</em></p> <code type="none"> handle(Msg, State) spawn(m, init, [])</code> - <p>Examples where ExprF is a fun:</p> + <p><em>Examples</em> where <c>ExprF</c> is a fun:</p> <code type="none"> Fun1 = fun(X) -> X+1 end Fun1(3) @@ -239,16 +252,15 @@ Fun1(3) fun lists:append/2([1,2], [3,4]) => [1,2,3,4]</code> - <p>Note that when calling a local function, there is a difference - between using the implicitly or fully qualified function name, as - the latter always refers to the latest version of the module. See - <seealso marker="code_loading">Compilation and Code Loading</seealso>.</p> - - <p>See also the chapter about - <seealso marker="functions#eval">Function Evaluation</seealso>.</p> + <p>Notice that when calling a local function, there is a difference + between using the implicitly or fully qualified function name. + The latter always refers to the latest version of the module. + See <seealso marker="code_loading">Compilation and Code Loading + </seealso> and <seealso marker="functions#eval"> + Function Evaluation</seealso>.</p> <section> - <title>Local Function Names Clashing With Auto-imported BIFs</title> + <title>Local Function Names Clashing With Auto-Imported BIFs</title> <p>If a local function has the same name as an auto-imported BIF, the semantics is that implicitly qualified function calls are directed to the locally defined function, not to the BIF. To avoid @@ -260,9 +272,9 @@ fun lists:append/2([1,2], [3,4]) <warning><p>Before OTP R14A (ERTS version 5.8), an implicitly qualified function call to a function having the same name as an auto-imported BIF always resulted in the BIF being called. In - newer versions of the compiler the local function is instead - called. The change is there to avoid that future additions to the - set of auto-imported BIFs does not silently change the behavior + newer versions of the compiler, the local function is called instead. + This is to avoid that future additions to the + set of auto-imported BIFs do not silently change the behavior of old code.</p> <p>However, to avoid that old (pre R14) code changed its @@ -272,8 +284,8 @@ fun lists:append/2([1,2], [3,4]) 5.8) and have an implicitly qualified call to that function in your code, you either need to explicitly remove the auto-import using a compiler directive, or replace the call with a fully - qualified function call, otherwise you will get a compilation - error. See example below:</p> </warning> + qualified function call. Otherwise you get a compilation + error. See the following example:</p> </warning> <code type="none"> -export([length/1,f/1]). @@ -290,9 +302,10 @@ f(X) when erlang:length(X) > 3 -> %% Calls erlang:length/1, long.</code> <p>The same logic applies to explicitly imported functions from - other modules as to locally defined functions. To both import a + other modules, as to locally defined functions. + It is not allowed to both import a function from another module and have the function declared in the - module at the same time is not allowed.</p> + module at the same time:</p> <code type="none"> -export([f/1]). @@ -310,10 +323,10 @@ f(X) -> length(X). %% mod:length/1 is called</code> - <p>For auto-imported BIFs added to Erlang in release R14A and thereafter, + <p>For auto-imported BIFs added in Erlang/OTP R14A and thereafter, overriding the name with a local function or explicit import is always allowed. However, if the <c>-compile({no_auto_import,[F/A])</c> - directive is not used, the compiler will issue a warning whenever + directive is not used, the compiler issues a warning whenever the function is called in the module using the implicitly qualified function name.</p> </section> @@ -330,15 +343,16 @@ if BodyN end</pre> <p>The branches of an <c>if</c>-expression are scanned sequentially - until a guard sequence <c>GuardSeq</c> which evaluates to true is + until a guard sequence <c>GuardSeq</c> that evaluates to true is found. Then the corresponding <c>Body</c> (sequence of expressions separated by ',') is evaluated.</p> <p>The return value of <c>Body</c> is the return value of the <c>if</c> expression.</p> - <p>If no guard sequence is true, an <c>if_clause</c> run-time error - will occur. If necessary, the guard expression <c>true</c> can be + <p>If no guard sequence is evaluated as true, + an <c>if_clause</c> run-time error + occurs. If necessary, the guard expression <c>true</c> can be used in the last branch, as that guard sequence is always true.</p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> is_greater_than(X, Y) -> if @@ -367,8 +381,8 @@ end</pre> <p>The return value of <c>Body</c> is the return value of the <c>case</c> expression.</p> <p>If there is no matching pattern with a true guard sequence, - a <c>case_clause</c> run-time error will occur.</p> - <p>Example:</p> + a <c>case_clause</c> run-time error occurs.</p> + <p><em>Example:</em></p> <pre> is_valid_signal(Signal) -> case Signal of @@ -389,15 +403,15 @@ Expr1 ! Expr2</pre> <p>Sends the value of <c>Expr2</c> as a message to the process specified by <c>Expr1</c>. The value of <c>Expr2</c> is also the return value of the expression.</p> - <p><c>Expr1</c> must evaluate to a pid, a registered name (atom) or - a tuple <c>{Name,Node}</c>, where <c>Name</c> is an atom and - <c>Node</c> a node name, also an atom.</p> + <p><c>Expr1</c> must evaluate to a pid, a registered name (atom), or + a tuple <c>{Name,Node}</c>. <c>Name</c> is an atom and + <c>Node</c> is a node name, also an atom.</p> <list type="bulleted"> <item>If <c>Expr1</c> evaluates to a name, but this name is not - registered, a <c>badarg</c> run-time error will occur.</item> + registered, a <c>badarg</c> run-time error occurs.</item> <item>Sending a message to a pid never fails, even if the pid identifies a non-existing process.</item> - <item>Distributed message sending, that is if <c>Expr1</c> + <item>Distributed message sending, that is, if <c>Expr1</c> evaluates to a tuple <c>{Name,Node}</c> (or a pid located at another node), also never fails.</item> </list> @@ -420,14 +434,14 @@ end</pre> the second, and so on. If a match succeeds and the optional guard sequence <c>GuardSeq</c> is true, the corresponding <c>Body</c> is evaluated. The matching message is consumed, that - is removed from the mailbox, while any other messages in + is, removed from the mailbox, while any other messages in the mailbox remain unchanged.</p> <p>The return value of <c>Body</c> is the return value of the <c>receive</c> expression.</p> - <p><c>receive</c> never fails. Execution is suspended, possibly - indefinitely, until a message arrives that does match one of + <p><c>receive</c> never fails. The execution is suspended, possibly + indefinitely, until a message arrives that matches one of the patterns and with a true guard sequence. </p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> wait_for_onhook() -> receive @@ -438,7 +452,7 @@ wait_for_onhook() -> B ! {busy, self()}, wait_for_onhook() end.</pre> - <p>It is possible to augment the <c>receive</c> expression with a + <p>The <c>receive</c> expression can be augmented with a timeout:</p> <pre> receive @@ -451,14 +465,14 @@ after ExprT -> BodyT end</pre> - <p><c>ExprT</c> should evaluate to an integer. The highest allowed - value is 16#ffffffff, that is, the value must fit in 32 bits. + <p><c>ExprT</c> is to evaluate to an integer. The highest allowed + value is 16#FFFFFFFF, that is, the value must fit in 32 bits. <c>receive..after</c> works exactly as <c>receive</c>, except that if no matching message has arrived within <c>ExprT</c> - milliseconds, then <c>BodyT</c> is evaluated instead and its - return value becomes the return value of the <c>receive..after</c> - expression.</p> - <p>Example:</p> + milliseconds, then <c>BodyT</c> is evaluated instead. The + return value of <c>BodyT</c> then becomes the return value + of the <c>receive..after</c> expression.</p> + <p><em>Example:</em></p> <pre> wait_for_onhook() -> receive @@ -481,10 +495,10 @@ after ExprT -> BodyT end</pre> - <p>This construction will not consume any messages, only suspend - execution in the process for <c>ExprT</c> milliseconds and can be + <p>This construction does not consume any messages, only suspends + execution in the process for <c>ExprT</c> milliseconds. This can be used to implement simple timers.</p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> timer() -> spawn(m, timer, [self()]). @@ -498,12 +512,12 @@ timer(Pid) -> <p>There are two special cases for the timeout value <c>ExprT</c>:</p> <taglist> <tag><c>infinity</c></tag> - <item>The process should wait indefinitely for a matching message - -- this is the same as not using a timeout. Can be - useful for timeout values that are calculated at run-time.</item> + <item>The process is to wait indefinitely for a matching message; + this is the same as not using a timeout. This can be + useful for timeout values that are calculated at runtime.</item> <tag>0</tag> <item>If there is no matching message in the mailbox, the timeout - will occur immediately.</item> + occurs immediately.</item> </taglist> </section> @@ -518,39 +532,39 @@ Expr1 <input>op</input> Expr2</pre> </row> <row> <cell align="left" valign="middle">==</cell> - <cell align="left" valign="middle">equal to</cell> + <cell align="left" valign="middle">Equal to</cell> </row> <row> <cell align="left" valign="middle">/=</cell> - <cell align="left" valign="middle">not equal to</cell> + <cell align="left" valign="middle">Not equal to</cell> </row> <row> <cell align="left" valign="middle">=<</cell> - <cell align="left" valign="middle">less than or equal to</cell> + <cell align="left" valign="middle">Less than or equal to</cell> </row> <row> <cell align="left" valign="middle"><</cell> - <cell align="left" valign="middle">less than</cell> + <cell align="left" valign="middle">Less than</cell> </row> <row> <cell align="left" valign="middle">>=</cell> - <cell align="left" valign="middle">greater than or equal to</cell> + <cell align="left" valign="middle">Greater than or equal to</cell> </row> <row> <cell align="left" valign="middle">></cell> - <cell align="left" valign="middle">greater than</cell> + <cell align="left" valign="middle">Greater than</cell> </row> <row> <cell align="left" valign="middle">=:=</cell> - <cell align="left" valign="middle">exactly equal to</cell> + <cell align="left" valign="middle">Exactly equal to</cell> </row> <row> <cell align="left" valign="middle">=/=</cell> - <cell align="left" valign="middle">exactly not equal to</cell> + <cell align="left" valign="middle">Exactly not equal to</cell> </row> <tcaption>Term Comparison Operators.</tcaption> </table> - <p>The arguments may be of different data types. The following + <p>The arguments can be of different data types. The following order is defined:</p> <pre> number < atom < reference < fun < port < pid < tuple < list < bit string</pre> @@ -558,17 +572,18 @@ number < atom < reference < fun < port < pid < tuple < list size, two tuples with the same size are compared element by element.</p> <p>When comparing an integer to a float, the term with the lesser - precision will be converted into the other term's type, unless the - operator is one of =:= or =/=. A float is more precise than + precision is converted into the type of the other term, unless the + operator is one of <c>=:=</c> or <c>=/=</c>. A float is more precise than an integer until all significant figures of the float are to the left of the decimal point. This happens when the float is larger/smaller than +/-9007199254740992.0. The conversion strategy is changed depending on the size of the float because otherwise comparison of large floats and integers would lose their transitivity.</p> - <p>Returns the Boolean value of the expression, <c>true</c> or - <c>false</c>.</p> - <p>Examples:</p> + <p>Term comparison operators return the Boolean value of the + expression, <c>true</c> or <c>false</c>.</p> + + <p><em>Examples:</em></p> <pre> 1> <input>1==1.0.</input> true @@ -585,19 +600,19 @@ false</pre> Expr1 <input>op</input> Expr2</pre> <table> <row> - <cell align="left" valign="middle"><em>op</em></cell> + <cell align="left" valign="middle"><em>Operator</em></cell> <cell align="left" valign="middle"><em>Description</em></cell> - <cell align="left" valign="middle"><em>Argument type</em></cell> + <cell align="left" valign="middle"><em>Argument Type</em></cell> </row> <row> <cell align="left" valign="middle">+</cell> - <cell align="left" valign="middle">unary +</cell> - <cell align="left" valign="middle">number</cell> + <cell align="left" valign="middle">Unary +</cell> + <cell align="left" valign="middle">Number</cell> </row> <row> <cell align="left" valign="middle">-</cell> - <cell align="left" valign="middle">unary -</cell> - <cell align="left" valign="middle">number</cell> + <cell align="left" valign="middle">Unary -</cell> + <cell align="left" valign="middle">Number</cell> </row> <row> <cell align="left" valign="middle">+</cell> @@ -607,62 +622,62 @@ Expr1 <input>op</input> Expr2</pre> <row> <cell align="left" valign="middle">-</cell> <cell align="left" valign="middle"> </cell> - <cell align="left" valign="middle">number</cell> + <cell align="left" valign="middle">Number</cell> </row> <row> <cell align="left" valign="middle">*</cell> <cell align="left" valign="middle"> </cell> - <cell align="left" valign="middle">number</cell> + <cell align="left" valign="middle">Number</cell> </row> <row> <cell align="left" valign="middle">/</cell> - <cell align="left" valign="middle">floating point division</cell> - <cell align="left" valign="middle">number</cell> + <cell align="left" valign="middle">Floating point division</cell> + <cell align="left" valign="middle">Number</cell> </row> <row> <cell align="left" valign="middle">bnot</cell> - <cell align="left" valign="middle">unary bitwise not</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Unary bitwise NOT</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">div</cell> - <cell align="left" valign="middle">integer division</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Integer division</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">rem</cell> - <cell align="left" valign="middle">integer remainder of X/Y</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Integer remainder of X/Y</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">band</cell> - <cell align="left" valign="middle">bitwise and</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Bitwise AND</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">bor</cell> - <cell align="left" valign="middle">bitwise or</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Bitwise OR</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">bxor</cell> - <cell align="left" valign="middle">arithmetic bitwise xor</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Arithmetic bitwise XOR</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">bsl</cell> - <cell align="left" valign="middle">arithmetic bitshift left</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Arithmetic bitshift left</cell> + <cell align="left" valign="middle">Integer</cell> </row> <row> <cell align="left" valign="middle">bsr</cell> - <cell align="left" valign="middle">bitshift right</cell> - <cell align="left" valign="middle">integer</cell> + <cell align="left" valign="middle">Bitshift right</cell> + <cell align="left" valign="middle">Integer</cell> </row> <tcaption>Arithmetic Operators.</tcaption> </table> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>+1.</input> 1 @@ -697,28 +712,28 @@ Expr1 <input>op</input> Expr2</pre> Expr1 <input>op</input> Expr2</pre> <table> <row> - <cell align="left" valign="middle"><em>op</em></cell> + <cell align="left" valign="middle"><em>Operator</em></cell> <cell align="left" valign="middle"><em>Description</em></cell> </row> <row> <cell align="left" valign="middle">not</cell> - <cell align="left" valign="middle">unary logical not</cell> + <cell align="left" valign="middle">Unary logical NOT</cell> </row> <row> <cell align="left" valign="middle">and</cell> - <cell align="left" valign="middle">logical and</cell> + <cell align="left" valign="middle">Logical AND</cell> </row> <row> <cell align="left" valign="middle">or</cell> - <cell align="left" valign="middle">logical or</cell> + <cell align="left" valign="middle">Logical OR</cell> </row> <row> <cell align="left" valign="middle">xor</cell> - <cell align="left" valign="middle">logical xor</cell> + <cell align="left" valign="middle">Logical XOR</cell> </row> <tcaption>Logical Operators.</tcaption> </table> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>not true.</input> false @@ -737,28 +752,37 @@ true <pre> Expr1 orelse Expr2 Expr1 andalso Expr2</pre> - <p>Expressions where <c>Expr2</c> is evaluated only if - necessary. That is, <c>Expr2</c> is evaluated only if <c>Expr1</c> - evaluates to <c>false</c> in an <c>orelse</c> expression, or only - if <c>Expr1</c> evaluates to <c>true</c> in an <c>andalso</c> - expression. Returns either the value of <c>Expr1</c> (that is, + <p><c>Expr2</c> is evaluated only if + necessary. That is, <c>Expr2</c> is evaluated only if:</p> + <list type="bulleted"> + <item><p><c>Expr1</c> evaluates to <c>false</c> in an + <c>orelse</c> expression.</p> + </item> + </list> + <p>or</p> + <list type="bulleted"> + <item><p><c>Expr1</c> evaluates to <c>true</c> in an + <c>andalso</c> expression.</p> + </item> + </list> + <p>Returns either the value of <c>Expr1</c> (that is, <c>true</c> or <c>false</c>) or the value of <c>Expr2</c> - (if <c>Expr2</c> was evaluated).</p> + (if <c>Expr2</c> is evaluated).</p> - <p>Example 1:</p> + <p><em>Example 1:</em></p> <pre> case A >= -1.0 andalso math:sqrt(A+1) > B of</pre> - <p>This will work even if <c>A</c> is less than <c>-1.0</c>, + <p>This works even if <c>A</c> is less than <c>-1.0</c>, since in that case, <c>math:sqrt/1</c> is never evaluated.</p> - <p>Example 2:</p> + <p><em>Example 2:</em></p> <pre> OnlyOne = is_atom(L) orelse (is_list(L) andalso length(L) == 1),</pre> - <p>From R13A, <c>Expr2</c> is no longer required to evaluate to a - boolean value. As a consequence, <c>andalso</c> and <c>orelse</c> + <p>From Erlang/OTP R13A, <c>Expr2</c> is no longer required to evaluate to a + Boolean value. As a consequence, <c>andalso</c> and <c>orelse</c> are now tail-recursive. For instance, the following function is - tail-recursive in R13A and later:</p> + tail-recursive in Erlang/OTP R13A and later:</p> <pre> all(Pred, [Hd|Tail]) -> @@ -774,11 +798,11 @@ Expr1 ++ Expr2 Expr1 -- Expr2</pre> <p>The list concatenation operator <c>++</c> appends its second argument to its first and returns the resulting list.</p> - <p>The list subtraction operator <c>--</c> produces a list which - is a copy of the first argument, subjected to the following - procedure: for each element in the second argument, the first + <p>The list subtraction operator <c>--</c> produces a list that + is a copy of the first argument. The procedure is a follows: + for each element in the second argument, the first occurrence of this element (if any) is removed.</p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> 1> <input>[1,2,3]++[4,5].</input> [1,2,3,4,5] @@ -786,8 +810,8 @@ Expr1 -- Expr2</pre> [3,1,2]</pre> <warning><p>The complexity of <c>A -- B</c> is - proportional to <c>length(A)*length(B)</c>, meaning that it - will be very slow if both <c>A</c> and <c>B</c> are + proportional to <c>length(A)*length(B)</c>. That is, it + becomes very slow if both <c>A</c> and <c>B</c> are long lists.</p></warning> </section> @@ -802,7 +826,7 @@ Expr1 -- Expr2</pre> </p> <code>#{ K => V }</code> <p> - New maps may include multiple associations at construction by listing every + New maps can include multiple associations at construction by listing every association: </p> <code>#{ K1 => V1, .., Kn => Vn }</code> @@ -816,11 +840,11 @@ Expr1 -- Expr2</pre> </p> <p> Keys and values are separated by the <c>=></c> arrow and associations are - separated by <c>,</c>. + separated by a comma <c>,</c>. </p> <p> - Examples: + <em>Examples:</em> </p> <code> M0 = #{}, % empty map @@ -829,14 +853,14 @@ M2 = #{1 => 2, b => b}, % multiple associations with literals M3 = #{k => {A,B}}, % single association with variables M4 = #{{"w", 1} => f()}. % compound key associated with an evaluated expression</code> <p> - where, <c>A</c> and <c>B</c> are any expressions and <c>M0</c> through <c>M4</c> + Here, <c>A</c> and <c>B</c> are any expressions and <c>M0</c> through <c>M4</c> are the resulting map terms. </p> <p> - If two matching keys are declared, the latter key will take precedence. + If two matching keys are declared, the latter key takes precedence. </p> <p> - Example: + <em>Example:</em> </p> <pre> @@ -846,54 +870,57 @@ M4 = #{{"w", 1} => f()}. % compound key associated with an evaluated expression #{1 => b, 1.0 => a} </pre> <p> - The order in which the expressions constructing the keys and their - associated values are evaluated is not defined. The syntactic order of + The order in which the expressions constructing the keys (and their + associated values) are evaluated is not defined. The syntactic order of the key-value pairs in the construction is of no relevance, except in - the above mentioned case of two matching keys. + the recently mentioned case of two matching keys. </p> </section> <section> <title>Updating Maps</title> <p> - Updating a map has similar syntax as constructing it. + Updating a map has a similar syntax as constructing it. </p> <p> - An expression defining the map to be updated is put in front of the expression - defining the keys to be updated and their respective values. + An expression defining the map to be updated, is put in front of the expression + defining the keys to be updated and their respective values: </p> <code>M#{ K => V }</code> <p> - where <c>M</c> is a term of type map and <c>K</c> and <c>V</c> are any expression. + Here <c>M</c> is a term of type map and <c>K</c> and <c>V</c> are any expression. </p> <p> If key <c>K</c> does not match any existing key in the map, a new association - will be created from key <c>K</c> to value <c>V</c>. If key <c>K</c> matches - an existing key in map <c>M</c> its associated value will be replaced by the - new value <c>V</c>. In both cases the evaluated map expression will return a new map. + is created from key <c>K</c> to value <c>V</c>. + </p> + <p> If key <c>K</c> matches an existing key in map <c>M</c>, + its associated value + is replaced by the new value <c>V</c>. In both cases, the evaluated map expression + returns a new map. </p> <p> - If <c>M</c> is not of type map an exception of type <c>badmap</c> is thrown. + If <c>M</c> is not of type map, an exception of type <c>badmap</c> is thrown. </p> <p> - To only update an existing value, the following syntax is used, + To only update an existing value, the following syntax is used: </p> <code>M#{ K := V } </code> <p> - where <c>M</c> is an term of type map, <c>V</c> is an expression and <c>K</c> - is an expression which evaluates to an existing key in <c>M</c>. + Here <c>M</c> is a term of type map, <c>V</c> is an expression and <c>K</c> + is an expression that evaluates to an existing key in <c>M</c>. </p> <p> - If key <c>K</c> does not match any existing keys in map <c>M</c> an exception - of type <c>badarg</c> will be triggered at runtime. If a matching key <c>K</c> - is present in map <c>M</c> its associated value will be replaced by the new - value <c>V</c> and the evaluated map expression returns a new map. + If key <c>K</c> does not match any existing keys in map <c>M</c>, an exception + of type <c>badarg</c> is triggered at runtime. If a matching key <c>K</c> + is present in map <c>M</c>, its associated value is replaced by the new + value <c>V</c>, and the evaluated map expression returns a new map. </p> <p> - If <c>M</c> is not of type map an exception of type <c>badmap</c> is thrown. + If <c>M</c> is not of type map, an exception of type <c>badmap</c> is thrown. </p> <p> - Examples: + <em>Examples:</em> </p> <code> M0 = #{}, @@ -902,10 +929,10 @@ M2 = M1#{a => 1, b => 2}, M3 = M2#{"function" => fun() -> f() end}, M4 = M3#{a := 2, b := 3}. % 'a' and 'b' was added in `M1` and `M2`.</code> <p> - where <c>M0</c> is any map. It follows that <c>M1 .. M4</c> are maps as well. + Here <c>M0</c> is any map. It follows that <c>M1 .. M4</c> are maps as well. </p> <p> - More Examples: + More <em>Examples:</em> </p> <pre> 1> <input>M = #{1 => a}.</input> @@ -921,83 +948,84 @@ M4 = M3#{a := 2, b := 3}. % 'a' and 'b' was added in `M1` and `M2`.</code> As in construction, the order in which the key and value expressions are evaluated is not defined. The syntactic order of the key-value pairs in the update is of no - relevance, except in the case where two keys match, in which - case the latter value is used. + relevance, except in the case where two keys match. + In that case, the latter value is used. </p> </section> <section> <title>Maps in Patterns</title> <p> - Matching of key-value associations from maps is done in the following way: + Matching of key-value associations from maps is done as follows: </p> <code>#{ K := V } = M</code> <p> - where <c>M</c> is any map. The key <c>K</c> has to be an expression with bound - variables or a literals, and <c>V</c> can be any pattern with either bound or + Here <c>M</c> is any map. The key <c>K</c> must be an expression with bound + variables or literals. <c>V</c> can be any pattern with either bound or unbound variables. </p> <p> - If the variable <c>V</c> is unbound, it will be bound to the value associated - with the key <c>K</c>, which has to exist in the map <c>M</c>. If the variable - <c>V</c> is bound, it has to match the value associated with <c>K</c> in <c>M</c>. + If the variable <c>V</c> is unbound, it becomes bound to the value associated + with the key <c>K</c>, which must exist in the map <c>M</c>. If the variable + <c>V</c> is bound, it must match the value associated with <c>K</c> in <c>M</c>. </p> - <p> Example: </p> -<code> + <p><em>Example:</em></p> +<pre> 1> <input>M = #{"tuple" => {1,2}}.</input> #{"tuple" => {1,2}} 2> <input>#{"tuple" := {1,B}} = M.</input> #{"tuple" => {1,2}} 3> <input>B.</input> -2.</code> +2.</pre> <p> - This will bind variable <c>B</c> to integer <c>2</c>. + This binds variable <c>B</c> to integer <c>2</c>. </p> <p> - Similarly, multiple values from the map may be matched: + Similarly, multiple values from the map can be matched: </p> <code>#{ K1 := V1, .., Kn := Vn } = M</code> <p> - where keys <c>K1 .. Kn</c> are any expressions with literals or bound variables. If all - keys exist in map <c>M</c> all variables in <c>V1 .. Vn</c> will be matched to the + Here keys <c>K1 .. Kn</c> are any expressions with literals or bound variables. If all + keys exist in map <c>M</c>, all variables in <c>V1 .. Vn</c> is matched to the associated values of their respective keys. </p> <p> - If the matching conditions are not met, the match will fail, either with + If the matching conditions are not met, the match fails, either with: </p> <list> - <item> - a <c>badmatch</c> exception, if used in the context of the matching operator - as in the example, + <item><p>A <c>badmatch</c> exception.</p> + <p>This is if it is used in the context of the matching operator + as in the example.</p> </item> - <item> - or resulting in the next clause being tested in function heads and - case expressions. + <item><p>Or resulting in the next clause being tested in function heads and + case expressions.</p> </item> </list> <p> Matching in maps only allows for <c>:=</c> as delimiters of associations. + </p> + <p> The order in which keys are declared in matching has no relevance. </p> <p> - Duplicate keys are allowed in matching and will match each pattern associated - to the keys. + Duplicate keys are allowed in matching and match each pattern associated + to the keys: </p> <code>#{ K := V1, K := V2 } = M</code> <p> - Matching an expression against an empty map literal will match its type but - no variables will be bound: + Matching an expression against an empty map literal, matches its type but + no variables are bound: </p> <code>#{} = Expr</code> <p> - This expression will match if the expression <c>Expr</c> is of type map, otherwise - it will fail with an exception <c>badmatch</c>. + This expression matches if the expression <c>Expr</c> is of type map, otherwise + it fails with an exception <c>badmatch</c>. </p> <section> - <title>Matching syntax: Example with literals in function heads</title> + <title>Matching Syntax</title> <p> - Matching of literals as keys are allowed in function heads. + Matching of literals as keys are allowed in function heads: </p> <code> %% only start if not_started @@ -1014,17 +1042,19 @@ handle_call(change, From, #{ state := start } = S) -> <section> <title>Maps in Guards</title> <p> - Maps are allowed in guards as long as all sub-expressions are valid guard expressions. + Maps are allowed in guards as long as all subexpressions are valid guard expressions. </p> <p> - Two guard BIFs handles maps: + Two guard BIFs handle maps: </p> <list> <item> <seealso marker="erts:erlang#is_map/1">is_map/1</seealso> + in the <c>erlang</c> module </item> <item> <seealso marker="erts:erlang#map_size/1">map_size/1</seealso> + in the <c>erlang</c> module </item> </list> </section> @@ -1044,29 +1074,34 @@ Ei = Value | Value/TypeSpecifierList | Value:Size/TypeSpecifierList</pre> <p>Used in a bit string construction, <c>Value</c> is an expression - which should evaluate to an integer, float or bit string. If the - expression is something else than a single literal or variable, it - should be enclosed in parenthesis.</p> + that is to evaluate to an integer, float, or bit string. If the + expression is not a single literal or variable, it + is to be enclosed in parenthesis.</p> <p>Used in a bit string matching, <c>Value</c> must be a variable, - or an integer, float or string.</p> + or an integer, float, or string.</p> - <p>Note that, for example, using a string literal as in + <p>Notice that, for example, using a string literal as in <c><![CDATA[<<"abc">>]]></c> is syntactic sugar for <c><![CDATA[<<$a,$b,$c>>]]></c>.</p> <p>Used in a bit string construction, <c>Size</c> is an expression - which should evaluate to an integer.</p> + that is to evaluate to an integer.</p> - <p>Used in a bit string matching, <c>Size</c> must be an integer or a + <p>Used in a bit string matching, <c>Size</c> must be an integer, or a variable bound to an integer.</p> <p>The value of <c>Size</c> specifies the size of the segment in units (see below). The default value depends on the type (see - below). For <c>integer</c> it is 8, for - <c>float</c> it is 64, for <c>binary</c> and <c>bitstring</c> it is - the whole binary or bit string. In matching, this default value is only - valid for the very last element. All other bit string or binary + below):</p> + <list type="bulleted"> + <item>For <c>integer</c> it is 8.</item> + <item>For <c>float</c> it is 64.</item> + <item>For <c>binary</c> and <c>bitstring</c> it is + the whole binary or bit string.</item> + </list> + <p>In matching, this default value is only + valid for the last element. All other bit string or binary elements in the matching must have a size specification.</p> <p>For the <c>utf8</c>, <c>utf16</c>, and <c>utf32</c> types, @@ -1090,7 +1125,7 @@ Ei = Value | The default is <c>unsigned</c>.</item> <tag><c>Endianness</c>= <c>big</c> | <c>little</c> | <c>native</c></tag> - <item>Native-endian means that the endianness will be resolved at load + <item>Native-endian means that the endianness is resolved at load time to be either big-endian or little-endian, depending on what is native for the CPU that the Erlang machine is run on. Endianness only matters when the Type is either <c>integer</c>, @@ -1099,7 +1134,7 @@ Ei = Value | <tag><c>Unit</c>= <c>unit:IntegerLiteral</c></tag> <item>The allowed range is 1..256. Defaults to 1 for <c>integer</c>, - <c>float</c> and <c>bitstring</c>, and to 8 for <c>binary</c>. + <c>float</c>, and <c>bitstring</c>, and to 8 for <c>binary</c>. No unit specifier must be given for the types <c>utf8</c>, <c>utf16</c>, and <c>utf32</c>. </item> @@ -1110,8 +1145,8 @@ Ei = Value | <note><p>When constructing binaries, if the size <c>N</c> of an integer segment is too small to contain the given integer, the most significant - bits of the integer will be silently discarded and only the <c>N</c> least - significant bits will be put into the binary.</p></note> + bits of the integer are silently discarded and only the <c>N</c> least + significant bits are put into the binary.</p></note> <p>The types <c>utf8</c>, <c>utf16</c>, and <c>utf32</c> specifies encoding/decoding of the <em>Unicode Transformation Format</em>s UTF-8, UTF-16, @@ -1120,39 +1155,39 @@ Ei = Value | <p>When constructing a segment of a <c>utf</c> type, <c>Value</c> must be an integer in the range 0..16#D7FF or 16#E000....16#10FFFF. Construction - will fail with a <c>badarg</c> exception if <c>Value</c> is + fails with a <c>badarg</c> exception if <c>Value</c> is outside the allowed ranges. The size of the resulting binary - segment depends on the type and/or <c>Value</c>. For <c>utf8</c>, - <c>Value</c> will be encoded in 1 through 4 bytes. For - <c>utf16</c>, <c>Value</c> will be encoded in 2 or 4 - bytes. Finally, for <c>utf32</c>, <c>Value</c> will always be - encoded in 4 bytes.</p> + segment depends on the type or <c>Value</c>, or both:</p> + <list type="bulleted"> + <item>For <c>utf8</c>, <c>Value</c> is encoded in 1-4 bytes.</item> + <item>For <c>utf16</c>, <c>Value</c> is encoded in 2 or 4 bytes.</item> + <item>For <c>utf32</c>, <c>Value</c> is always be encoded in 4 bytes.</item> + </list> - <p>When constructing, a literal string may be given followed + <p>When constructing, a literal string can be given followed by one of the UTF types, for example: <c><![CDATA[<<"abc"/utf8>>]]></c> - which is syntatic sugar for + which is syntactic sugar for <c><![CDATA[<<$a/utf8,$b/utf8,$c/utf8>>]]></c>.</p> - <p>A successful match of a segment of a <c>utf</c> type results + <p>A successful match of a segment of a <c>utf</c> type, results in an integer in the range 0..16#D7FF or 16#E000..16#10FFFF. - The match will fail if returned value - would fall outside those ranges.</p> + The match fails if the returned value falls outside those ranges.</p> - <p>A segment of type <c>utf8</c> will match 1 to 4 bytes in the binary, + <p>A segment of type <c>utf8</c> matches 1-4 bytes in the binary, if the binary at the match position contains a valid UTF-8 sequence. (See RFC-3629 or the Unicode standard.)</p> - <p>A segment of type <c>utf16</c> may match 2 or 4 bytes in the binary. - The match will fail if the binary at the match position does not contain + <p>A segment of type <c>utf16</c> can match 2 or 4 bytes in the binary. + The match fails if the binary at the match position does not contain a legal UTF-16 encoding of a Unicode code point. (See RFC-2781 or the Unicode standard.)</p> - <p>A segment of type <c>utf32</c> may match 4 bytes in the binary in the - same way as an <c>integer</c> segment matching 32 bits. - The match will fail if the resulting integer is outside the legal ranges + <p>A segment of type <c>utf32</c> can match 4 bytes in the binary in the + same way as an <c>integer</c> segment matches 32 bits. + The match fails if the resulting integer is outside the legal ranges mentioned above.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>Bin1 = <<1,17,42>>.</input> <<1,17,42>> @@ -1181,11 +1216,13 @@ Ei = Value | 13> <input><<1024/utf8>>.</input> <<208,128>> </pre> - <p>Note that bit string patterns cannot be nested.</p> - <p>Note also that "<c><![CDATA[B=<<1>>]]></c>" is interpreted as + <p>Notice that bit string patterns cannot be nested.</p> + <p>Notice also that "<c><![CDATA[B=<<1>>]]></c>" is interpreted as "<c><![CDATA[B =<<1>>]]></c>" which is a syntax error. The correct way is to write a space after '=': "<c><![CDATA[B= <<1>>]]></c>.</p> - <p>More examples can be found in <em>Programming Examples</em>.</p> + <p>More examples are provided in + <seealso marker="doc/programming_examples:bit_syntax"> + Programming Examples</seealso>.</p> </section> <section> @@ -1200,16 +1237,16 @@ fun BodyK end</pre> <p>A fun expression begins with the keyword <c>fun</c> and ends - with the keyword <c>end</c>. Between them should be a function + with the keyword <c>end</c>. Between them is to be a function declaration, similar to a <seealso marker="functions#syntax">regular function declaration</seealso>, - except that the function name is optional and should be a variable if + except that the function name is optional and is to be a variable, if any.</p> <p>Variables in a fun head shadow the function name and both shadow - variables in the function clause surrounding the fun expression, and - variables bound in a fun body are local to the fun body.</p> + variables in the function clause surrounding the fun expression. + Variables bound in a fun body are local to the fun body.</p> <p>The return value of the expression is the resulting fun.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>Fun1 = fun (X) -> X+1 end.</input> #Fun<erl_eval.6.39074546> @@ -1232,15 +1269,17 @@ fun Module:Name/Arity</pre> syntactic sugar for:</p> <pre> fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end</pre> - <p>In <c>Module:Name/Arity</c>, <c>Module</c> and <c>Name</c> are atoms - and <c>Arity</c> is an integer. Starting from the R15 release, - <c>Module</c>, <c>Name</c>, and <c>Arity</c> may also be variables. - A fun defined in this way will refer to the function <c>Name</c> + <p>In <c>Module:Name/Arity</c>, <c>Module</c>, and <c>Name</c> are atoms + and <c>Arity</c> is an integer. Starting from Erlang/OTP R15, + <c>Module</c>, <c>Name</c>, and <c>Arity</c> can also be variables. + A fun defined in this way refers to the function <c>Name</c> with arity <c>Arity</c> in the <em>latest</em> version of module - <c>Module</c>. A fun defined in this way will not be dependent on - the code for module in which it is defined. + <c>Module</c>. A fun defined in this way is not dependent on + the code for the module in which it is defined. </p> - <p>More examples can be found in <em>Programming Examples</em>.</p> + <p>More examples are provided in + <seealso marker="doc/programming_examples:funs"> + Programming Examples</seealso>.</p> </section> <section> @@ -1250,23 +1289,26 @@ fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end</pre> catch Expr</code> <p>Returns the value of <c>Expr</c> unless an exception occurs during the evaluation. In that case, the exception is - caught. For exceptions of class <c>error</c>, - that is run-time errors: <c>{'EXIT',{Reason,Stack}}</c> - is returned. For exceptions of class <c>exit</c>, that is - the code called <c>exit(Term)</c>: <c>{'EXIT',Term}</c> is returned. - For exceptions of class <c>throw</c>, that is - the code called <c>throw(Term)</c>: <c>Term</c> is returned.</p> + caught.</p> + <p>For exceptions of class <c>error</c>, that is, + run-time errors, + <c>{'EXIT',{Reason,Stack}}</c> is returned.</p> + <p>For exceptions of class <c>exit</c>, that is, + the code called <c>exit(Term)</c>, + <c>{'EXIT',Term}</c> is returned.</p> + <p>For exceptions of class <c>throw</c>, that is + the code called <c>throw(Term)</c>, + <c>Term</c> is returned.</p> <p><c>Reason</c> depends on the type of error that occurred, and <c>Stack</c> is the stack of recent function calls, see - <seealso marker="errors#exit_reasons">Errors and Error Handling</seealso>.</p> - <p>Examples:</p> - <p></p> + <seealso marker="errors#exit_reasons">Exit Reasons</seealso>.</p> + <p><em>Examples:</em></p> <pre> 1> <input>catch 1+2.</input> 3 2> <input>catch 1+a.</input> {'EXIT',{badarith,[...]}}</pre> - <p>Note that <c>catch</c> has low precedence and catch + <p>Notice that <c>catch</c> has low precedence and catch subexpressions often needs to be enclosed in a block expression or in parenthesis:</p> <pre> @@ -1275,13 +1317,14 @@ catch Expr</code> 4> <input>A = (catch 1+2).</input> 3</pre> <p>The BIF <c>throw(Any)</c> can be used for non-local return from - a function. It must be evaluated within a <c>catch</c>, which will - return the value <c>Any</c>. Example:</p> + a function. It must be evaluated within a <c>catch</c>, which + returns the value <c>Any</c>.</p> + <p><em>Example:</em></p> <pre> 5> <input>catch throw(hello).</input> hello</pre> <p>If <c>throw/1</c> is not evaluated within a catch, a - <c>nocatch</c> run-time error will occur.</p> + <c>nocatch</c> run-time error occurs.</p> </section> <section> @@ -1297,14 +1340,17 @@ catch end</code> <p>This is an enhancement of <seealso marker="#catch">catch</seealso> that appeared in - Erlang 5.4/OTP-R10B. It gives the possibility do distinguish - between different exception classes, and to choose to handle only - the desired ones, passing the others on to an enclosing - <c>try</c> or <c>catch</c> or to default error handling.</p> - <p>Note that although the keyword <c>catch</c> is used in + Erlang 5.4/OTP R10B. It gives the possibility to:</p> + <list type="bulleted"> + <item>Distinguish between different exception classes.</item> + <item>Choose to handle only the desired ones.</item> + <item>Passing the others on to an enclosing + <c>try</c> or <c>catch</c>, or to default error handling.</item> + </list> + <p>Notice that although the keyword <c>catch</c> is used in the <c>try</c> expression, there is not a <c>catch</c> expression within the <c>try</c> expression.</p> - <p>Returns the value of <c>Exprs</c> (a sequence of expressions + <p>It returns the value of <c>Exprs</c> (a sequence of expressions <c>Expr1, ..., ExprN</c>) unless an exception occurs during the evaluation. In that case the exception is caught and the patterns <c>ExceptionPattern</c> with the right exception @@ -1318,7 +1364,7 @@ end</code> <c>Class</c> with a true guard sequence, the exception is passed on as if <c>Exprs</c> had not been enclosed in a <c>try</c> expression.</p> - <p>If an exception occurs during evaluation of <c>ExceptionBody</c> + <p>If an exception occurs during evaluation of <c>ExceptionBody</c>, it is not caught.</p> <p>The <c>try</c> expression can have an <c>of</c> section: @@ -1341,7 +1387,7 @@ end</code> the patterns <c>Pattern</c> are sequentially matched against the result in the same way as for a <seealso marker="#case">case</seealso> expression, except that if - the matching fails, a <c>try_clause</c> run-time error will occur.</p> + the matching fails, a <c>try_clause</c> run-time error occurs.</p> <p>An exception occurring during the evaluation of <c>Body</c> is not caught.</p> <p>The <c>try</c> expression can also be augmented with an @@ -1364,7 +1410,7 @@ after AfterBody end</code> <p><c>AfterBody</c> is evaluated after either <c>Body</c> or - <c>ExceptionBody</c> no matter which one. The evaluated value of + <c>ExceptionBody</c>, no matter which one. The evaluated value of <c>AfterBody</c> is lost; the return value of the <c>try</c> expression is the same with an <c>after</c> section as without.</p> <p>Even if an exception occurs during evaluation of <c>Body</c> or @@ -1373,13 +1419,13 @@ end</code> evaluated, so the exception from the <c>try</c> expression is the same with an <c>after</c> section as without.</p> <p>If an exception occurs during evaluation of <c>AfterBody</c> - itself it is not caught, so if <c>AfterBody</c> is evaluated after - an exception in <c>Exprs</c>, <c>Body</c> or <c>ExceptionBody</c>, + itself, it is not caught. So if <c>AfterBody</c> is evaluated after + an exception in <c>Exprs</c>, <c>Body</c>, or <c>ExceptionBody</c>, that exception is lost and masked by the exception in <c>AfterBody</c>.</p> - <p>The <c>of</c>, <c>catch</c> and <c>after</c> sections are all + <p>The <c>of</c>, <c>catch</c>, and <c>after</c> sections are all optional, as long as there is at least a <c>catch</c> or an - <c>after</c> section, so the following are valid <c>try</c> + <c>after</c> section. So the following are valid <c>try</c> expressions:</p> <code type="none"> try Exprs of @@ -1398,9 +1444,9 @@ after end try Exprs after AfterBody end</code> - <p>Example of using <c>after</c>, this code will close the file + <p>Next is an example of using <c>after</c>. This closes the file, even in the event of exceptions in <c>file:read/2</c> or in - <c>binary_to_term/1</c>, and exceptions will be the same as + <c>binary_to_term/1</c>. The exceptions are the same as without the <c>try</c>...<c>after</c>...<c>end</c> expression:</p> <code type="none"> termize_file(Name) -> @@ -1411,7 +1457,7 @@ termize_file(Name) -> after file:close(F) end.</code> - <p>Example: Using <c>try</c> to emulate <c>catch Expr</c>.</p> + <p>Next is an example of using <c>try</c> to emulate <c>catch Expr</c>:</p> <code type="none"> try Expr catch @@ -1427,7 +1473,7 @@ end</code> (Expr)</pre> <p>Parenthesized expressions are useful to override <seealso marker="#prec">operator precedences</seealso>, - for example in arithmetic expressions:</p> + for example, in arithmetic expressions:</p> <pre> 1> <input>1 + 2 * 3.</input> 7 @@ -1451,7 +1497,7 @@ end</pre> <section> <marker id="lcs"></marker> <title>List Comprehensions</title> - <p>List comprehensions are a feature of many modern functional + <p>List comprehensions is a feature of many modern functional programming languages. Subject to certain rules, they provide a succinct notation for generating elements in a list.</p> <p>List comprehensions are analogous to set comprehensions in @@ -1461,32 +1507,34 @@ end</pre> <p>List comprehensions are written with the following syntax:</p> <pre> [Expr || Qualifier1,...,QualifierN]</pre> - <p><c>Expr</c> is an arbitrary expression, and each + <p>Here, <c>Expr</c> is an arbitrary expression, and each <c>Qualifier</c> is either a generator or a filter.</p> <list type="bulleted"> <item>A <em>generator</em> is written as: <br></br> <c><![CDATA[Pattern <- ListExpr]]></c>. <br></br> -<c>ListExpr</c> must be an expression which evaluates to a +<c>ListExpr</c> must be an expression, which evaluates to a list of terms.</item> <item>A <em>bit string generator</em> is written as: <br></br> <c><![CDATA[BitstringPattern <= BitStringExpr]]></c>. <br></br> -<c>BitStringExpr</c> must be an expression which evaluates to a +<c>BitStringExpr</c> must be an expression, which evaluates to a bitstring.</item> - <item>A <em>filter</em> is an expression which evaluates to + <item>A <em>filter</em> is an expression, which evaluates to <c>true</c> or <c>false</c>.</item> </list> - <p>The variables in the generator patterns shadow variables in the function - clause surrounding the list comprehensions.</p> <p>A list comprehension + <p>The variables in the generator patterns, shadow variables in the function + clause, surrounding the list comprehensions.</p> <p>A list comprehension returns a list, where the elements are the result of evaluating <c>Expr</c> for each combination of generator list elements and bit string generator - elements for which all filters are true.</p> <p></p> <p>Example:</p> + elements, for which all filters are true.</p> + <p><em>Example:</em></p> <pre> 1> <input>[X*2 || X <- [1,2,3]].</input> [2,4,6]</pre> - <p>More examples can be found in <em>Programming Examples</em>.</p> - + <p>More examples are provoded in + <seealso marker="doc/programming_examples:list_comprehensions"> + Programming Examples.</seealso></p> </section> @@ -1500,34 +1548,35 @@ end</pre> the following syntax:</p> <pre> << BitString || Qualifier1,...,QualifierN >></pre> - <p><c>BitString</c> is a bit string expression, and each + <p>Here, <c>BitString</c> is a bit string expression and each <c>Qualifier</c> is either a generator, a bit string generator or a filter.</p> <list type="bulleted"> <item>A <em>generator</em> is written as: <br></br> <c><![CDATA[Pattern <- ListExpr]]></c>. <br></br> - <c>ListExpr</c> must be an expression which evaluates to a + <c>ListExpr</c> must be an expression that evaluates to a list of terms.</item> <item>A <em>bit string generator</em> is written as: <br></br> <c><![CDATA[BitstringPattern <= BitStringExpr]]></c>. <br></br> -<c>BitStringExpr</c> must be an expression which evaluates to a +<c>BitStringExpr</c> must be an expression that evaluates to a bitstring.</item> - <item>A <em>filter</em> is an expression which evaluates to + <item>A <em>filter</em> is an expression that evaluates to <c>true</c> or <c>false</c>.</item> </list> - <p>The variables in the generator patterns shadow variables in - the function clause surrounding the bit string comprehensions.</p> + <p>The variables in the generator patterns, shadow variables in + the function clause, surrounding the bit string comprehensions.</p> <p>A bit string comprehension returns a bit string, which is created by concatenating the results of evaluating <c>BitString</c> - for each combination of bit string generator elements for which all + for each combination of bit string generator elements, for which all filters are true.</p> - <p></p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> -1> <input><< << (X*2) >> || +1> <input><< << (X*2) >> || <<X>> <= << 1,2,3 >> >>.</input> <<2,4,6>></pre> - <p>More examples can be found in <em>Programming Examples</em>.</p> + <p>More examples are provided in + <seealso marker="doc/programming_examples:bit_syntax"> + Programming Examples.</seealso></p> </section> <section> @@ -1536,27 +1585,27 @@ end</pre> <p>A <em>guard sequence</em> is a sequence of guards, separated by semicolon (;). The guard sequence is true if at least one of - the guards is true. (The remaining guards, if any, will not be - evaluated.)<br></br> -<c>Guard1;...;GuardK</c></p> + the guards is true. (The remaining guards, if any, are not + evaluated.)</p> + <p><c>Guard1;...;GuardK</c></p> <p>A <em>guard</em> is a sequence of guard expressions, separated by comma (,). The guard is true if all guard expressions - evaluate to <c>true</c>.<br></br> -<c>GuardExpr1,...,GuardExprN</c></p> + evaluate to <c>true</c>.</p> + <p><c>GuardExpr1,...,GuardExprN</c></p> <p>The set of valid <em>guard expressions</em> (sometimes called guard tests) is a subset of the set of valid Erlang expressions. The reason for restricting the set of valid expressions is that evaluation of a guard expression must be guaranteed to be free - of side effects. Valid guard expressions are:</p> + of side effects. Valid guard expressions are the following:</p> <list type="bulleted"> - <item>the atom <c>true</c>,</item> - <item>other constants (terms and bound variables), all regarded - as false,</item> - <item>calls to the BIFs specified below,</item> - <item>term comparisons,</item> - <item>arithmetic expressions,</item> - <item>boolean expressions, and</item> - <item>short-circuit expressions (<c>andalso</c>/<c>orelse</c>).</item> + <item>The atom <c>true</c></item> + <item>Other constants (terms and bound variables), all regarded + as false</item> + <item>Calls to the BIFs specified in table <c>Type Test BIFs</c></item> + <item>Term comparisons</item> + <item>Arithmetic expressions</item> + <item>Boolean expressions</item> + <item>Short-circuit expressions (<c>andalso</c>/<c>orelse</c>)</item> </list> <table> <row> @@ -1610,13 +1659,13 @@ end</pre> <row> <cell align="left" valign="middle"><c>is_tuple/1</c></cell> </row> - <tcaption>Type Test BIFs.</tcaption> + <tcaption>Type Test BIFs</tcaption> </table> - <p>Note that most type test BIFs have older equivalents, without + <p>Notice that most type test BIFs have older equivalents, without the <c>is_</c> prefix. These old BIFs are retained for backwards - compatibility only and should not be used in new code. They are + compatibility only and are not to be used in new code. They are also only allowed at top level. For example, they are not allowed - in boolean expressions in guards.</p> + in Boolean expressions in guards.</p> <table> <row> <cell align="left" valign="middle"><c>abs(Number)</c></cell> @@ -1666,14 +1715,14 @@ end</pre> <row> <cell align="left" valign="middle"><c>tuple_size(Tuple)</c></cell> </row> - <tcaption>Other BIFs Allowed in Guard Expressions.</tcaption> + <tcaption>Other BIFs Allowed in Guard Expressions</tcaption> </table> - <p>If an arithmetic expression, a boolean expression, a + <p>If an arithmetic expression, a Boolean expression, a short-circuit expression, or a call to a guard BIF fails (because of invalid arguments), the entire guard fails. If the guard was part of a guard sequence, the next guard in the sequence (that is, - the guard following the next semicolon) will be evaluated.</p> + the guard following the next semicolon) is evaluated.</p> </section> @@ -1726,12 +1775,13 @@ end</pre> <cell align="left" valign="middle">catch</cell> <cell align="left" valign="middle"> </cell> </row> - <tcaption>Operator Precedence.</tcaption> + <tcaption>Operator Precedence</tcaption> </table> <p>When evaluating an expression, the operator with the highest priority is evaluated first. Operators with the same priority - are evaluated according to their associativity. Example: - The left associative arithmetic operators are evaluated left to + are evaluated according to their associativity.</p> + <p><em>Example:</em></p> + <p>The left associative arithmetic operators are evaluated left to right:</p> <pre> <input>6 + 5 * 4 - 3 / 2</input> evaluates to diff --git a/system/doc/reference_manual/functions.xml b/system/doc/reference_manual/functions.xml index 9498ef1402..8cf4da1b8b 100644 --- a/system/doc/reference_manual/functions.xml +++ b/system/doc/reference_manual/functions.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -38,7 +38,7 @@ clause body, separated by <c>-></c>.</p> <p>A clause <em>head</em> consists of the function name, an argument list, and an optional guard sequence - beginning with the keyword <c>when</c>.</p> + beginning with the keyword <c>when</c>:</p> <pre> Name(Pattern11,...,Pattern1N) [when GuardSeq1] -> Body1; @@ -48,9 +48,9 @@ Name(PatternK1,...,PatternKN) [when GuardSeqK] -> <p>The function name is an atom. Each argument is a pattern.</p> <p>The number of arguments <c>N</c> is the <em>arity</em> of the function. A function is uniquely defined by the module name, - function name and arity. That is, two functions with the same + function name, and arity. That is, two functions with the same name and in the same module, but with different arities are two - completely different functions.</p> + different functions.</p> <p>A function named <c>f</c> in the module <c>m</c> and with arity <c>N</c> is often denoted as <c>m:f/N</c>.</p> <p>A clause <em>body</em> consists of a sequence of expressions @@ -60,8 +60,8 @@ Expr1, ..., ExprN</pre> <p>Valid Erlang expressions and guard sequences are described in - <seealso marker="expressions">Erlang Expressions</seealso>.</p> - <p>Example:</p> + <seealso marker="expressions">Expressions</seealso>.</p> + <p><em>Example:</em></p> <pre> fact(N) when N>0 -> % first clause head N * fact(N-1); % first clause body @@ -75,23 +75,23 @@ fact(0) -> % second clause head <title>Function Evaluation</title> <p>When a function <c>m:f/N</c> is called, first the code for the function is located. If the function cannot be found, an - <c>undef</c> run-time error will occur. Note that the function + <c>undef</c> runtime error occurs. Notice that the function must be exported to be visible outside the module it is defined in.</p> <p>If the function is found, the function clauses are scanned - sequentially until a clause is found that fulfills the following - two conditions:</p> + sequentially until a clause is found that fulfills both of + the following two conditions:</p> <list type="ordered"> - <item>the patterns in the clause head can be successfully - matched against the given arguments, and</item> - <item>the guard sequence, if any, is true.</item> + <item>The patterns in the clause head can be successfully + matched against the given arguments.</item> + <item>The guard sequence, if any, is true.</item> </list> <p>If such a clause cannot be found, a <c>function_clause</c> - run-time error will occur.</p> + runtime error occurs.</p> <p>If such a clause is found, the corresponding clause body is evaluated. That is, the expressions in the body are evaluated sequentially and the value of the last expression is returned.</p> - <p>Example: Consider the function <c>fact</c>:</p> + <p>Consider the function <c>fact</c>:</p> <pre> -module(m). -export([fact/1]). @@ -100,17 +100,17 @@ fact(N) when N>0 -> N * fact(N-1); fact(0) -> 1.</pre> - <p>Assume we want to calculate factorial for 1:</p> + <p>Assume that you want to calculate the factorial for 1:</p> <pre> 1> <input>m:fact(1).</input></pre> <p>Evaluation starts at the first clause. The pattern <c>N</c> is - matched against the argument 1. The matching succeeds and - the guard (<c>N>0</c>) is true, thus <c>N</c> is bound to 1 and + matched against argument 1. The matching succeeds and + the guard (<c>N>0</c>) is true, thus <c>N</c> is bound to 1, and the corresponding body is evaluated:</p> <pre> <input>N * fact(N-1)</input> => (N is bound to 1) <input>1 * fact(0)</input></pre> - <p>Now <c>fact(0)</c> is called and the function clauses are + <p>Now, <c>fact(0)</c> is called, and the function clauses are scanned sequentially again. First, the pattern <c>N</c> is matched against 0. The matching succeeds, but the guard (<c>N>0</c>) is false. Second, the pattern 0 is matched against @@ -121,48 +121,51 @@ fact(0) -> <input>1</input></pre> <p>Evaluation has succeed and <c>m:fact(1)</c> returns 1.</p> <p>If <c>m:fact/1</c> is called with a negative number as - argument, no clause head will match. A <c>function_clause</c> - run-time error will occur.</p> + argument, no clause head matches. A <c>function_clause</c> + runtime error occurs.</p> </section> <section> <title>Tail recursion</title> <p>If the last expression of a function body is a function call, - a <em>tail recursive</em> call is done so that no system - resources for example call stack are consumed. This means - that an infinite loop can be done if it uses tail recursive + a <em>tail recursive</em> call is done. + This is to ensure that no system + resources, for example, call stack, are consumed. This means + that an infinite loop can be done if it uses tail-recursive calls.</p> - <p>Example:</p> + <p><em>Example:</em></p> <pre> loop(N) -> io:format("~w~n", [N]), loop(N+1).</pre> - <p>As a counter-example see the factorial example above - that is not tail recursive since a multiplication is done + <p>The earlier factorial example can act as a counter-example. + It is not tail-recursive, since a multiplication is done on the result of the recursive call to <c>fact(N-1)</c>.</p> </section> <section> - <title>Built-In Functions, BIFs</title> - <p><em>Built-in functions</em>, BIFs, are implemented in C code in - the runtime system and do things that are difficult or impossible - to implement in Erlang. Most of the built-in functions belong - to the module <c>erlang</c> but there are also built-in functions + <title>Built-In Functions (BIFs)</title> + <p>BIFs are implemented in C code in + the runtime system. BIFs do things that are difficult or impossible + to implement in Erlang. Most of the BIFs belong + to the module <c>erlang</c> but there are also BIFs belonging to a few other modules, for example <c>lists</c> and <c>ets</c>.</p> - <p>The most commonly used BIFs belonging to <c>erlang</c> are - <em>auto-imported</em>, they do not need to be prefixed with - the module name. Which BIFs are auto-imported is specified in - <c>erlang(3)</c>. For example, standard type conversion BIFs like + <p>The most commonly used BIFs belonging to <c>erlang(3)</c> are + <em>auto-imported</em>. They do not need to be prefixed with + the module name. Which BIFs that are auto-imported is specified in the + <seealso marker="erts:erlang">erlang(3)</seealso> module in ERTS. + For example, standard-type conversion BIFs like <c>atom_to_list</c> and BIFs allowed in guards can be called - without specifying the module name. Examples:</p> + without specifying the module name.</p> + <p><em>Examples:</em></p> <pre> 1> <input>tuple_size({a,b,c}).</input> 3 2> <input>atom_to_list('Erlang').</input> "Erlang"</pre> - <p>Note that normally it is the set of auto-imported built-in - functions that is referred to when talking about 'BIFs'.</p> + <p>Notice that it is normally the set of auto-imported BIFs + that are referred to when talking about 'BIFs'.</p> </section> </chapter> diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml index 36bec17825..ee8b82e60f 100644 --- a/system/doc/reference_manual/introduction.xml +++ b/system/doc/reference_manual/introduction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2014</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,20 +28,38 @@ <rev></rev> <file>introduction.xml</file> </header> + <marker id="erlang ref manual"></marker> + + <p>This section is the Erlang reference manual. It describes the + Erlang programming language. </p> <section> <title>Purpose</title> - <p>This reference manual describes the Erlang programming - language. The focus is on the language itself, not - the implementation. The language constructs are described in - text and with examples rather than formally specified, with - the intention to make the manual more readable. - The manual is not intended as a tutorial.</p> - <p>Information about this implementation of Erlang can be found, for - example, in <em>System Principles</em> (starting and stopping, - boot scripts, code loading, error logging, creating target - systems), <em>Efficiency Guide</em> (memory consumption, system - limits) and <em>ERTS User's Guide</em> (crash dumps, drivers).</p> + <p>The focus of the Erlang reference manual is on the language itself, + not the implementation of it. The language constructs are described in + text and with examples rather than formally specified. This is + to make the manual more readable. + The Erlang reference manual is not intended as a tutorial.</p> + <p>Information about implementation of Erlang can, for example, be found, + in the following:</p> + <list type="bulleted"> + <item><p><seealso marker="doc/system_principles:system_principles"> + System Principles</seealso></p> + <p>Starting and stopping, boot scripts, code loading, + <seealso marker="doc/system_principles:error_logging"> + error logging</seealso>, + <seealso marker="doc/system_principles:create_target"> + creating target systems</seealso></p> + </item> + <item><p><seealso marker="doc/efficiency_guide:advanced"> + Efficiency Guide</seealso></p> + <p>Memory consumption, system limits</p> + </item> + <item><p>ERTS User's Guide</p> + <p><seealso marker="erts:crash_dump">Crash dumps</seealso>, + <seealso marker="erts:driver">drivers</seealso></p> + </item> + </list> </section> <section> @@ -53,13 +71,13 @@ <section> <title>Document Conventions</title> - <p>In the document, the following terminology is used:</p> + <p>In this section, the following terminology is used:</p> <list type="bulleted"> <item>A <em>sequence</em> is one or more items. For example, a clause body consists of a sequence of expressions. This means that there must be at least one expression.</item> <item>A <em>list</em> is any number of items. For example, - an argument list can consist of zero, one or more arguments.</item> + an argument list can consist of zero, one, or more arguments.</item> </list> <p>If a feature has been added recently, in Erlang 5.0/OTP R7 or later, this is mentioned in the text.</p> @@ -68,15 +86,16 @@ <section> <title>Complete List of BIFs</title> <p>For a complete list of BIFs, their arguments and return values, - refer to <c>erlang(3)</c>.</p> + see <seealso marker="erts:erlang#process_flag/2">erlang(3)</seealso> + manual page in ERTS.</p> </section> <section> <title>Reserved Words</title> <p>The following are reserved words in Erlang:</p> - <p>after and andalso band begin bnot bor bsl bsr bxor case catch + <p><c>after and andalso band begin bnot bor bsl bsr bxor case catch cond div end fun if let not of or orelse receive rem try - when xor</p> + when xor</c></p> </section> </chapter> diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 9fd0b0f287..01994aae5e 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -21,7 +21,7 @@ </legalnotice> - <title>The Preprocessor</title> + <title>Preprocessor</title> <prepared></prepared> <docno></docno> <date></date> @@ -31,17 +31,17 @@ <section> <title>File Inclusion</title> - <p>A file can be included in the following way:</p> + <p>A file can be included as follows:</p> <pre> -include(File). -include_lib(File).</pre> - <p><c>File</c>, a string, should point out a file. The contents of - this file are included as-is, at the position of the directive.</p> + <p><c>File</c>, a string, is to point out a file. The contents of + this file are included as is, at the position of the directive.</p> <p>Include files are typically used for record and macro definitions that are shared by several modules. It is - recommended that the file name extension <c>.hrl</c> be used - for include files.</p> - <p><c>File</c> may start with a path component <c>$VAR</c>, for + recommended to use the file name extension <c>.hrl</c> for + include files.</p> + <p><c>File</c> can start with a path component <c>$VAR</c>, for some string <c>VAR</c>. If that is the case, the value of the environment variable <c>VAR</c> as returned by <c>os:getenv(VAR)</c> is substituted for <c>$VAR</c>. If @@ -49,21 +49,29 @@ as is.</p> <p>If the filename <c>File</c> is absolute (possibly after variable substitution), the include file with that name is - included. Otherwise, the specified file is searched for in - the current working directory, in the same directory as - the module being compiled, and in the directories given by - the <c>include</c> option, in that order. - See <c>erlc(1)</c> and <c>compile(3)</c> for details.</p> - <p>Examples:</p> + included. Otherwise, the specified file is searched for + in the following directories, and in this order:</p> + <list type="ordered"> + <item>The current working directory</item> + <item>The directory where the module is being compiled</item> + <item>The directories given by the <c>include</c> option</item> + </list> + <p>For details, see the + <seealso marker="erts:erlc">erlc(1)</seealso> manual page + in ERTS and + <seealso marker="compiler:compile">compile(3)</seealso> + manual page in Compiler.</p> + <p><em>Examples:</em></p> <pre> -include("my_records.hrl"). -include("incdir/my_records.hrl"). -include("/home/user/proj/my_records.hrl"). -include("$PROJ_ROOT/my_records.hrl").</pre> - <p><c>include_lib</c> is similar to <c>include</c>, but should not + <p><c>include_lib</c> is similar to <c>include</c>, but is not to point out an absolute file. Instead, the first path component (possibly after variable substitution) is assumed to be - the name of an application. Example:</p> + the name of an application.</p> + <p><em>Example:</em></p> <pre> -include_lib("kernel/include/file.hrl").</pre> <p>The code server uses <c>code:lib_dir(kernel)</c> to find @@ -74,7 +82,7 @@ <section> <title>Defining and Using Macros</title> - <p>A macro is defined the following way:</p> + <p>A macro is defined as follows:</p> <code type="none"> -define(Const, Replacement). -define(Func(Var1,...,VarN), Replacement).</code> @@ -83,33 +91,34 @@ come before any usage of the macro.</p> <p>If a macro is used in several modules, it is recommended that the macro definition is placed in an include file.</p> - <p>A macro is used the following way:</p> + <p>A macro is used as follows:</p> <code type="none"> ?Const ?Func(Arg1,...,ArgN)</code> <p>Macros are expanded during compilation. A simple macro - <c>?Const</c> will be replaced with <c>Replacement</c>. - Example:</p> + <c>?Const</c> is replaced with <c>Replacement</c>.</p> + <p><em>Example:</em></p> <code type="none"> -define(TIMEOUT, 200). ... call(Request) -> server:call(refserver, Request, ?TIMEOUT).</code> - <p>This will be expanded to:</p> + <p>This is expanded to:</p> <code type="none"> call(Request) -> server:call(refserver, Request, 200).</code> - <p>A macro <c>?Func(Arg1,...,ArgN)</c> will be replaced with + <p>A macro <c>?Func(Arg1,...,ArgN)</c> is replaced with <c>Replacement</c>, where all occurrences of a variable <c>Var</c> from the macro definition are replaced with the corresponding - argument <c>Arg</c>. Example:</p> + argument <c>Arg</c>.</p> + <p><em>Example:</em></p> <code type="none"> -define(MACRO1(X, Y), {a, X, b, Y}). ... bar(X) -> ?MACRO1(a, b), ?MACRO1(X, 123)</code> - <p>This will be expanded to:</p> + <p>This is expanded to:</p> <code type="none"> bar(X) -> {a,a,b,b}, @@ -154,7 +163,7 @@ bar(X) -> -define(F0(), c). -define(F1(A), A). -define(C, m:f).</code> - <p>the following will not work:</p> + <p>the following does not work:</p> <code type="none"> f0() -> ?F0. % No, an empty list of arguments expected. @@ -165,7 +174,7 @@ f1(A) -> <code> f() -> ?C().</code> - <p>will expand to</p> + <p>is expanded to</p> <code> f() -> m:f().</code> @@ -185,7 +194,7 @@ f() -> defined.</item> <tag><c>-else.</c></tag> <item>Only allowed after an <c>ifdef</c> or <c>ifndef</c> - directive. If that condition was false, the lines following + directive. If that condition is false, the lines following <c>else</c> are evaluated instead.</item> <tag><c>-endif.</c></tag> <item>Specifies the end of an <c>ifdef</c> or <c>ifndef</c> @@ -194,7 +203,7 @@ f() -> <note> <p>The macro directives cannot be used inside functions.</p> </note> - <p>Example:</p> + <p><em>Example:</em></p> <code type="none"> -module(m). ... @@ -206,7 +215,7 @@ f() -> -endif. ...</code> - <p>When trace output is desired, <c>debug</c> should be defined + <p>When trace output is desired, <c>debug</c> is to be defined when the module <c>m</c> is compiled:</p> <pre> % <input>erlc -Ddebug m.erl</input> @@ -215,18 +224,18 @@ or 1> <input>c(m, {d, debug}).</input> {ok,m}</pre> - <p><c>?LOG(Arg)</c> will then expand to a call to <c>io:format/2</c> + <p><c>?LOG(Arg)</c> is then expanded to a call to <c>io:format/2</c> and provide the user with some simple trace output.</p> </section> <section> <title>Stringifying Macro Arguments</title> <p>The construction <c>??Arg</c>, where <c>Arg</c> is a macro - argument, will be expanded to a string containing the tokens of + argument, is expanded to a string containing the tokens of the argument. This is similar to the <c>#arg</c> stringifying construction in C.</p> <p>The feature was added in Erlang 5.0/OTP R7.</p> - <p>Example:</p> + <p><em>Example:</em></p> <code type="none"> -define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])). @@ -236,7 +245,7 @@ or <code type="none"> io:format("Call ~s: ~w~n",["myfunction ( 1 , 2 )",myfunction(1,2)]), io:format("Call ~s: ~w~n",["you : function ( 2 , 1 )",you:function(2,1)]).</code> - <p>That is, a trace output with both the function called and + <p>That is, a trace output, with both the function called and the resulting value.</p> </section> </chapter> diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml index f0ec7ef165..39c739a146 100644 --- a/system/doc/reference_manual/modules.xml +++ b/system/doc/reference_manual/modules.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2014</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -33,7 +33,8 @@ <title>Module Syntax</title> <p>Erlang code is divided into <em>modules</em>. A module consists of a sequence of attributes and function declarations, each - terminated by period (.). Example:</p> + terminated by period (.).</p> + <p><em>Example:</em></p> <pre> -module(m). % module attribute -export([fact/1]). % module attribute @@ -42,50 +43,52 @@ fact(N) when N>0 -> % beginning of function declaration N * fact(N-1); % | fact(0) -> % | 1. % end of function declaration</pre> - <p>See the <seealso marker="functions">Functions</seealso> chapter - for a description of function declarations.</p> + <p>For a description of function declarations, see + <seealso marker="functions">Function Declaration Syntax</seealso>.</p> </section> <section> <title>Module Attributes</title> <p>A <em>module attribute</em> defines a certain property of a - module. A module attribute consists of a tag and a value.</p> + module.</p> + <p>A module attribute consists of a tag and a value:</p> <pre> -Tag(Value).</pre> <p><c>Tag</c> must be an atom, while <c>Value</c> must be a literal term. As a convenience in user-defined attributes, if the literal term <c>Value</c> has the syntax <c>Name/Arity</c> (where <c>Name</c> is an atom and <c>Arity</c> a positive integer), - the term <c>Name/Arity</c> will be translated to <c>{Name,Arity}</c>.</p> + the term <c>Name/Arity</c> is translated to <c>{Name,Arity}</c>.</p> <p>Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by calling - <c>Module:module_info(attributes)</c> or by using - <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso>.</p> + <c>Module:module_info(attributes)</c>, or by using the module + <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso> + in STDLIB.</p> - <p>There are several module attributes with predefined meanings, - some of which have arity two, but user-defined module + <p>Several module attributes have predefined meanings. + Some of them have arity two, but user-defined module attributes must have arity one.</p> <section> <title>Pre-Defined Module Attributes</title> - <p>Pre-defined module attributes should be placed before any + <p>Pre-defined module attributes is to be placed before any function declaration.</p> <taglist> <tag><c>-module(Module).</c></tag> <item> <p>Module declaration, defining the name of the module. - The name <c>Module</c>, an atom, should be the same as - the file name minus the extension <c>erl</c>. Otherwise - <seealso marker="code_loading#loading">code loading</seealso> will + The name <c>Module</c>, an atom, is to be same as + the file name minus the extension <c>.erl</c>. Otherwise + <seealso marker="code_loading#loading">code loading</seealso> does not work as intended.</p> - <p>This attribute should be specified first and is the only - attribute which is mandatory.</p> + <p>This attribute is to be specified first and is the only + mandatory attribute.</p> </item> <tag><c>-export(Functions).</c></tag> <item> - <p>Exported functions. Specifies which of the functions - defined within the module that are visible outside + <p>Exported functions. Specifies which of the functions, + defined within the module, that are visible from outside the module.</p> <p><c>Functions</c> is a list <c>[Name1/Arity1, ..., NameN/ArityN]</c>, where each @@ -93,32 +96,37 @@ fact(0) -> % | </item> <tag><c>-import(Module,Functions).</c></tag> <item> - <p>Imported functions. Imported functions can be called - the same way as local functions, that is without any module + <p>Imported functions. Can be called + the same way as local functions, that is, without any module prefix.</p> <p><c>Module</c>, an atom, specifies which module to import functions from. <c>Functions</c> is a list similar as for - <c>export</c> above.</p> + <c>export</c>.</p> </item> <tag><c>-compile(Options).</c></tag> <item> - <p>Compiler options. <c>Options</c>, which is a single option - or a list of options, will be added to the option list when - compiling the module. See <c>compile(3)</c>.</p> + <p>Compiler options. <c>Options</c> is a single option + or a list of options. + This attribute is added to the option list when + compiling the module. See the <seealso marker="compiler:compile"> + compile(3)</seealso> manual page in Compiler.</p> </item> <tag><c>-vsn(Vsn).</c></tag> <item> <p>Module version. <c>Vsn</c> is any literal term and can be - retrieved using <c>beam_lib:version/1</c>, see - <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso>.</p> + retrieved using <c>beam_lib:version/1</c>, see the + <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso> + manual page in STDLIB.</p> <p>If this attribute is not specified, the version defaults to the MD5 checksum of the module.</p> </item> <tag><c>-on_load(Function).</c></tag> <item> - <p>Names a function that should be run automatically when a - module a loaded. See <seealso marker="code_loading#on_load"> - code loading</seealso> for more information.</p> + <p>This attribute names a function that is to be run + automatically when a + module is loaded. For more information, see + <seealso marker="code_loading#on_load"> + Running a Function When a Module is Loaded</seealso>.</p> </item> </taglist> </section> @@ -130,9 +138,14 @@ fact(0) -> % | <pre> -behaviour(Behaviour).</pre> <p>The atom <c>Behaviour</c> gives the name of the behaviour, - which can be a user defined behaviour or one of the OTP - standard behaviours <c>gen_server</c>, <c>gen_fsm</c>, - <c>gen_event</c> or <c>supervisor</c>.</p> + which can be a user-defined behaviour or one of the following OTP + standard behaviours:</p> + <list type="bulleted"> + <item><c>gen_server</c></item> + <item><c>gen_fsm</c></item> + <item><c>gen_event</c></item> + <item><c>supervisor</c></item> + </list> <p>The spelling <c>behavior</c> is also accepted.</p> <p>The callback functions of the module can be specified either directly by the exported function <c>behaviour_info/1</c>:</p> @@ -142,7 +155,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> function:</p> <pre> -callback Name(Arguments) -> Result.</pre> - <p>where <c>Arguments</c> is a list of zero or more arguments. + <p>Here, <c>Arguments</c> is a list of zero or more arguments. The <c>-callback</c> attribute is to be preferred since the extra type information can be used by tools to produce documentation or find discrepancies.</p> @@ -153,7 +166,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> <section> <title>Record Definitions</title> - <p>The same syntax as for module attributes is used by + <p>The same syntax as for module attributes is used for record definitions:</p> <pre> -record(Record,Fields).</pre> @@ -163,7 +176,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> </section> <section> - <title>The Preprocessor</title> + <title>Preprocessor</title> <p>The same syntax as for module attributes is used by the preprocessor, which supports file inclusion, macros, and conditional compilation:</p> @@ -171,7 +184,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> -include("SomeFile.hrl"). -define(Macro,Replacement).</pre> - <p>Read more in <seealso marker="macros">The Preprocessor</seealso>.</p> + <p>Read more in <seealso marker="macros">Preprocessor</seealso>.</p> </section> <section> @@ -180,108 +193,113 @@ behaviour_info(callbacks) -> Callbacks.</pre> changing the pre-defined macros <c>?FILE</c> and <c>?LINE</c>:</p> <pre> -file(File, Line).</pre> - <p>This attribute is used by tools such as Yecc to inform the - compiler that the source program was generated by another tool - and indicates the correspondence of source files to lines of - the original user-written file from which the source program - was produced.</p> + <p>This attribute is used by tools, such as Yecc, to inform the + compiler that the source program is generated by another tool. + It also indicates the correspondence of source files to lines of + the original user-written file, from which the source program + is produced.</p> </section> <section> <title>Types and function specifications</title> <p>A similar syntax as for module attributes is used for - specifying types and function specifications. + specifying types and function specifications: </p> <pre> -type my_type() :: atom() | integer(). --spec my_function(integer()) -> integer(). - </pre> +-spec my_function(integer()) -> integer().</pre> <p>Read more in <seealso marker="typespec">Types and Function specifications</seealso>. </p> <p> The description is based on <url href="http://www.erlang.org/eeps/eep-0008.html">EEP8 - - Types and function specifications</url> - which will not be further updated. + Types and function specifications</url>, + which is not to be further updated. </p> </section> </section> <section> <title>Comments</title> - <p>Comments may be placed anywhere in a module except within strings - and quoted atoms. The comment begins with the character "%", + <p>Comments can be placed anywhere in a module except within strings + and quoted atoms. A comment begins with the character "%", continues up to, but does not include the next end-of-line, and - has no effect. Note that the terminating end-of-line has + has no effect. Notice that the terminating end-of-line has the effect of white space.</p> </section> <section> - <title>The module_info/0 and module_info/1 functions</title> + <title>module_info/0 and module_info/1 functions</title> <p>The compiler automatically inserts the two special, exported - functions into each module: <c>Module:module_info/0</c> and - <c>Module:module_info/1</c>. These functions can be called to - retrieve information about the module.</p> + functions into each module:</p> + <list type="bulleted"> + <item><c>Module:module_info/0</c></item> + <item><c>Module:module_info/1</c></item> + </list> + <p>These functions can be called to retrieve information + about the module.</p> <section> <title>module_info/0</title> - <p>The <c>module_info/0</c> function in each module returns + <p>The <c>module_info/0</c> function in each module, returns a list of <c>{Key,Value}</c> tuples with information about the module. Currently, the list contain tuples with the following - <c>Key</c>s: <c>attributes</c>, <c>compile</c>, - <c>exports</c>, and <c>imports</c>. The order and number of tuples + <c>Key</c>s: <c>module</c>, <c>attributes</c>, <c>compile</c>, + <c>exports</c> and <c>md5</c>. The order and number of tuples may change without prior notice.</p> - - <warning><p>The <c>{imports,Value}</c> tuple may be removed in a future - release because <c>Value</c> is always an empty list. - Do not write code that depends on it being present.</p></warning> </section> <section> <title>module_info/1</title> - <p>The call <c>module_info(Key)</c>, where key is an atom, + <p>The call <c>module_info(Key)</c>, where <c>Key</c> is an atom, returns a single piece of information about the module.</p> <p>The following values are allowed for <c>Key</c>:</p> <taglist> + <tag><c>module</c></tag> + <item> + <p>Returns an atom representing the module name.</p> + </item> + <tag><c>attributes</c></tag> <item> - <p>Return a list of <c>{AttributeName,ValueList}</c> tuples, + <p>Returns a list of <c>{AttributeName,ValueList}</c> tuples, where <c>AttributeName</c> is the name of an attribute, - and <c>ValueList</c> is a list of values. Note: a given - attribute may occur more than once in the list with different + and <c>ValueList</c> is a list of values. Notice that a given + attribute can occur more than once in the list with different values if the attribute occurs more than once in the module.</p> - <p>The list of attributes will be empty if - the module has been stripped with - <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p> + <p>The list of attributes becomes empty if + the module is stripped with the + <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso> + module (in STDLIB).</p> </item> <tag><c>compile</c></tag> <item> - <p>Return a list of tuples containing information about - how the module was compiled. This list will be empty if - the module has been stripped with - <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso>.</p> + <p>Returns a list of tuples with information about + how the module was compiled. This list is empty if + the module has been stripped with the + <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso> + module (in STDLIB).</p> </item> - <tag><c>imports</c></tag> + <tag><c>md5</c></tag> <item> - <p>Always return an empty list. The <c>imports</c> key may not - be supported in future release.</p> + <p>Returns a binary representing the MD5 checksum of the module.</p> </item> <tag><c>exports</c></tag> <item> - <p>Return a list of <c>{Name,Arity}</c> tuples with + <p>Returns a list of <c>{Name,Arity}</c> tuples with all exported functions in the module.</p> </item> <tag><c>functions</c></tag> <item> - <p>Return a list of <c>{Name,Arity}</c> tuples with + <p>Returns a list of <c>{Name,Arity}</c> tuples with all functions in the module.</p> </item> </taglist> diff --git a/system/doc/reference_manual/patterns.xml b/system/doc/reference_manual/patterns.xml index 1611002fa1..2163583636 100644 --- a/system/doc/reference_manual/patterns.xml +++ b/system/doc/reference_manual/patterns.xml @@ -40,7 +40,7 @@ <seealso marker="expressions#term">term</seealso>. If the matching succeeds, any unbound variables in the pattern become bound. If the matching fails, a run-time error occurs.</p> - <p>Examples:</p> + <p><em>Examples:</em></p> <pre> 1> <input>X.</input> ** 1: variable 'X' is unbound ** diff --git a/system/doc/reference_manual/ports.xml b/system/doc/reference_manual/ports.xml index 621af10624..e5dc99641b 100644 --- a/system/doc/reference_manual/ports.xml +++ b/system/doc/reference_manual/ports.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,9 +28,12 @@ <rev></rev> <file>ports.xml</file> </header> - <p>Examples of how to use ports and port drivers can be found in - <em>Interoperability Tutorial</em>. The BIFs mentioned are as usual - documented in <c>erlang(3)</c>.</p> + <p>Examples of how to use ports and port drivers are provided in + <seealso marker="doc/tutorial:introduction#interoperability tutorial"> + Interoperability Tutorial</seealso>. + For information about the BIFs mentioned, see the + <seealso marker="erts:erlang">erlang(3)</seealso> manual + page in ERTS.</p> <section> <title>Ports</title> @@ -39,29 +42,34 @@ provide a byte-oriented interface to an external program. When a port has been created, Erlang can communicate with it by sending and receiving lists of bytes, including binaries.</p> - <p>The Erlang process which creates a port is said to be + <p>The Erlang process creating a port is said to be the <em>port owner</em>, or the <em>connected process</em> of - the port. All communication to and from the port should go via - the port owner. If the port owner terminates, so will the port + the port. All communication to and from the port must go through + the port owner. If the port owner terminates, so does the port (and the external program, if it is written correctly).</p> <p>The external program resides in another OS process. By default, - it should read from standard input (file descriptor 0) and write + it reads from standard input (file descriptor 0) and writes to standard output (file descriptor 1). The external program - should terminate when the port is closed.</p> + is to terminate when the port is closed.</p> </section> <section> <title>Port Drivers</title> - <p>It is also possible to write a driver in C according to certain + <p>It is possible to write a driver in C according to certain principles and dynamically link it to the Erlang runtime system. The linked-in driver looks like a port from the Erlang programmer's point of view and is called a <em>port driver</em>.</p> <warning> - <p>An erroneous port driver will cause the entire Erlang runtime + <p>An erroneous port driver causes the entire Erlang runtime system to leak memory, hang or crash.</p> </warning> - <p>Port drivers are documented in <c>erl_driver(4)</c>, - <c>driver_entry(1)</c> and <c>erl_ddll(3)</c>.</p> + <p>For information about port drivers, see the + <seealso marker="erts:erl_driver">erl_driver(4)</seealso> + manual page in ERTS, + <seealso marker="erts:driver_entry">driver_entry(1)</seealso> + manual page in ERTS, and + <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso> + manual page in Kernel.</p> </section> <section> @@ -70,53 +78,74 @@ <table> <row> <cell align="left" valign="middle"><c>open_port(PortName, PortSettings</c></cell> - <cell align="left" valign="middle">Returns a port identifier <c>Port</c>as the result of opening a new Erlang port. Messages can be sent to and received from a port identifier, just like a pid. Port identifiers can also be linked to or registered under a name using <c>link/1</c>and <c>register/2</c>.</cell> + <cell align="left" valign="middle">Returns a port identifier + <c>Port</c> as the result of opening a new Erlang port. + Messages can be sent to, and received from, a port identifier, + just like a pid. Port identifiers can also be linked to + using <c>link/1</c>, or registered under a name using + <c>register/2</c>.</cell> </row> - <tcaption>Port Creation BIF.</tcaption> + <tcaption>Port Creation BIF</tcaption> </table> <p><c>PortName</c> is usually a tuple <c>{spawn,Command}</c>, where the string <c>Command</c> is the name of the external program. - The external program runs outside the Erlang workspace unless a - port driver with the name <c>Command</c> is found. If found, that - driver is started.</p> + The external program runs outside the Erlang workspace, unless a + port driver with the name <c>Command</c> is found. If <c>Command</c> + is found, that driver is started.</p> <p><c>PortSettings</c> is a list of settings (options) for the port. - The list typically contains at least a tuple <c>{packet,N}</c> + The list typically contains at least a tuple <c>{packet,N}</c>, which specifies that data sent between the port and the external program are preceded by an N-byte length indicator. Valid values - for N are 1, 2 or 4. If binaries should be used instead of lists + for N are 1, 2, or 4. If binaries are to be used instead of lists of bytes, the option <c>binary</c> must be included.</p> <p>The port owner <c>Pid</c> can communicate with the port <c>Port</c> by sending and receiving messages. (In fact, any process can send the messages to the port, but the port owner must be identified in the message).</p> - <p>As of OTP-R16 messages sent to ports are delivered truly + <p>As of Erlang/OTP R16, messages sent to ports are delivered truly asynchronously. The underlying implementation previously delivered messages to ports synchronously. Message passing has - however always been documented as an asynchronous operation, so - this should not be an issue for an Erlang program communicating - with ports, unless false assumptions about ports has been made.</p> - <p>Below, <c>Data</c> must be an I/O list. An I/O list is a binary - or a (possibly deep) list of binaries or integers in the range - 0..255.</p> + however always been documented as an asynchronous operation. Hence, + this is not to be an issue for an Erlang program communicating + with ports, unless false assumptions about ports have been made.</p> + <p>In the following tables of examples, <c>Data</c> must be an I/O list. + An I/O list is a binary or a (possibly deep) list of binaries + or integers in the range 0..255:</p> <table> <row> + <cell align="left" valign="middle"><em>Message</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>{Pid,{command,Data}}</c></cell> - <cell align="left" valign="middle">Sends <c>Data</c>to the port.</cell> + <cell align="left" valign="middle">Sends <c>Data</c> to the port.</cell> </row> <row> <cell align="left" valign="middle"><c>{Pid,close}</c></cell> - <cell align="left" valign="middle">Closes the port. Unless the port is already closed, the port replies with <c>{Port,closed}</c>when all buffers have been flushed and the port really closes.</cell> + <cell align="left" valign="middle">Closes the port. Unless the + port is already closed, the port replies with + <c>{Port,closed}</c> when all buffers have been flushed + and the port really closes.</cell> </row> <row> <cell align="left" valign="middle"><c>{Pid,{connect,NewPid}}</c></cell> - <cell align="left" valign="middle">Sets the port owner of <c>Port</c>to <c>NewPid</c>. Unless the port is already closed, the port replies with<c>{Port,connected}</c>to the old port owner. Note that the old port owner is still linked to the port, but the new port owner is not.</cell> + <cell align="left" valign="middle">Sets the port owner of + <c>Port</c>to <c>NewPid</c>. Unless the port is already closed, + the port replies with<c>{Port,connected}</c> to the old + port owner. Note that the old port owner is still linked + to the port, but the new port owner is not.</cell> </row> - <tcaption>Messages Sent To a Port.</tcaption> + <tcaption>Messages Sent To a Port</tcaption> </table> + <p></p> <table> <row> + <cell align="left" valign="middle"><em>Message</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>{Port,{data,Data}}</c></cell> - <cell align="left" valign="middle"><c>Data</c>is received from the external program.</cell> + <cell align="left" valign="middle"><c>Data</c> is received from the external program.</cell> </row> <row> <cell align="left" valign="middle"><c>{Port,closed}</c></cell> @@ -124,20 +153,24 @@ </row> <row> <cell align="left" valign="middle"><c>{Port,connected}</c></cell> - <cell align="left" valign="middle">Reply to <c>Port ! {Pid,{connect,NewPid}}</c></cell> + <cell align="left" valign="middle">Reply to <c>Port ! {Pid,{connect,NewPid}}</c>.</cell> </row> <row> <cell align="left" valign="middle"><c>{'EXIT',Port,Reason}</c></cell> <cell align="left" valign="middle">If the port has terminated for some reason.</cell> </row> - <tcaption>Messages Received From a Port.</tcaption> + <tcaption>Messages Received From a Port</tcaption> </table> <p>Instead of sending and receiving messages, there are also a - number of BIFs that can be used.</p> + number of BIFs that can be used:</p> <table> <row> + <cell align="left" valign="middle"><em>Port BIF</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>port_command(Port,Data)</c></cell> - <cell align="left" valign="middle">Sends <c>Data</c>to the port.</cell> + <cell align="left" valign="middle">Sends <c>Data</c> to the port.</cell> </row> <row> <cell align="left" valign="middle"><c>port_close(Port)</c></cell> @@ -145,7 +178,10 @@ </row> <row> <cell align="left" valign="middle"><c>port_connect(Port,NewPid)</c></cell> - <cell align="left" valign="middle">Sets the port owner of <c>Port</c>to <c>NewPid</c>. The old port owner <c>Pid</c>stays linked to the port and have to call <c>unlink(Port)</c>if this is not desired.</cell> + <cell align="left" valign="middle">Sets the port owner of + <c>Port</c>to <c>NewPid</c>. The old port owner <c>Pid</c> + stays linked to the port and must call <c>unlink(Port)</c> + if this is not desired.</cell> </row> <row> <cell align="left" valign="middle"><c>erlang:port_info(Port,Item)</c></cell> @@ -155,9 +191,9 @@ <cell align="left" valign="middle"><c>erlang:ports()</c></cell> <cell align="left" valign="middle">Returns a list of all ports on the current node.</cell> </row> - <tcaption>Port BIFs.</tcaption> + <tcaption>Port BIFs</tcaption> </table> - <p>There are some additional BIFs that only apply to port drivers: + <p>Some additional BIFs that apply to port drivers: <c>port_control/3</c> and <c>erlang:port_call/3</c>.</p> </section> </chapter> diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml index 95ae0672ec..d8474c163c 100644 --- a/system/doc/reference_manual/processes.xml +++ b/system/doc/reference_manual/processes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,8 +32,8 @@ <section> <title>Processes</title> <p>Erlang is designed for massive concurrency. Erlang processes are - light-weight (grow and shrink dynamically) with small memory - footprint, fast to create and terminate and the scheduling + lightweight (grow and shrink dynamically) with small memory + footprint, fast to create and terminate, and the scheduling overhead is low.</p> </section> @@ -46,10 +46,10 @@ spawn(Module, Name, Args) -> pid() Args = [Arg1,...,ArgN] ArgI = term()</pre> <p><c>spawn</c> creates a new process and returns the pid.</p> - <p>The new process will start executing in - <c>Module:Name(Arg1,...,ArgN)</c> where the arguments is + <p>The new process starts executing in + <c>Module:Name(Arg1,...,ArgN)</c> where the arguments are the elements of the (possible empty) <c>Args</c> argument list.</p> - <p>There exist a number of other <c>spawn</c> BIFs, for example + <p>There exist a number of other <c>spawn</c> BIFs, for example, <c>spawn/4</c> for spawning a process at another node.</p> </section> @@ -60,18 +60,25 @@ spawn(Module, Name, Args) -> pid() atom and is automatically unregistered if the process terminates:</p> <table> <row> + <cell align="left" valign="middle"><em>BIF</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> <cell align="left" valign="middle"><c>register(Name, Pid)</c></cell> <cell align="left" valign="middle">Associates the name <c>Name</c>, an atom, with the process <c>Pid</c>.</cell> </row> <row> <cell align="left" valign="middle"><c>registered()</c></cell> - <cell align="left" valign="middle">Returns a list of names which have been registered using<c>register/2</c>.</cell> + <cell align="left" valign="middle">Returns a list of names that + have been registered using <c>register/2</c>.</cell> </row> <row> <cell align="left" valign="middle"><c>whereis(Name)</c></cell> - <cell align="left" valign="middle">Returns the pid registered under <c>Name</c>, or<c>undefined</c>if the name is not registered.</cell> + <cell align="left" valign="middle">Returns the pid registered + under <c>Name</c>, or <c>undefined </c>if the name is not + registered.</cell> </row> - <tcaption>Name Registration BIFs.</tcaption> + <tcaption>Name Registration BIFs</tcaption> </table> </section> @@ -79,22 +86,27 @@ spawn(Module, Name, Args) -> pid() <marker id="term"></marker> <title>Process Termination</title> <p>When a process terminates, it always terminates with an - <em>exit reason</em>. The reason may be any term.</p> + <em>exit reason</em>. The reason can be any term.</p> <p>A process is said to terminate <em>normally</em>, if the exit reason is the atom <c>normal</c>. A process with no more code to execute terminates normally.</p> - <p>A process terminates with exit reason <c>{Reason,Stack}</c> + <p>A process terminates with an exit reason <c>{Reason,Stack}</c> when a run-time error occurs. See - <seealso marker="errors#exit_reasons">Error and Error Handling</seealso>.</p> - <p>A process can terminate itself by calling one of the BIFs - <c>exit(Reason)</c>, - <c>erlang:error(Reason)</c>, <c>erlang:error(Reason, Args)</c>, - <c>erlang:fault(Reason)</c> or <c>erlang:fault(Reason, Args)</c>. - The process then terminates with reason <c>Reason</c> for + <seealso marker="errors#exit_reasons">Exit Reasons</seealso>.</p> + <p>A process can terminate itself by calling one of the + following BIFs:</p> + <list type="bulleted"> + <item><c>exit(Reason)</c></item> + <item><c>erlang:error(Reason)</c></item> + <item><c>erlang:error(Reason, Args)</c></item> + <item><c>erlang:fault(Reason)</c></item> + <item><c>erlang:fault(Reason, Args)</c></item> + </list> + <p>The process then terminates with reason <c>Reason</c> for <c>exit/1</c> or <c>{Reason,Stack} for the others</c>.</p> - <p>A process may also be terminated if it receives an exit signal + <p>A process can also be terminated if it receives an exit signal with another exit reason than <c>normal</c>, see - <seealso marker="#errors">Error Handling</seealso> below.</p> + <seealso marker="#errors">Error Handling</seealso>.</p> </section> <section> @@ -113,35 +125,39 @@ spawn(Module, Name, Args) -> pid() <title>Links</title> <p>Two processes can be <em>linked</em> to each other. A link between two processes <c>Pid1</c> and <c>Pid2</c> is created - by <c>Pid1</c> calling the BIF <c>link(Pid2)</c> (or vice versa). + by <c>Pid1</c> calling the BIF <c>link(Pid2)</c> (or conversely). There also exist a number of <c>spawn_link</c> BIFs, which spawn and link to a process in one operation.</p> <p>Links are bidirectional and there can only be one link between two processes. Repeated calls to <c>link(Pid)</c> have no effect.</p> <p>A link can be removed by calling the BIF <c>unlink(Pid)</c>.</p> <p>Links are used to monitor the behaviour of other processes, see - <seealso marker="#errors">Error Handling</seealso> below.</p> + <seealso marker="#errors">Error Handling</seealso>.</p> </section> <section> <marker id="errors"></marker> <title>Error Handling</title> <p>Erlang has a built-in feature for error handling between - processes. Terminating processes will emit exit signals to all - linked processes, which may terminate as well or handle the exit + processes. Terminating processes emit exit signals to all + linked processes, which can terminate as well or handle the exit in some way. This feature can be used to build hierarchical program structures where some processes are supervising other - processes, for example restarting them if they terminate + processes, for example, restarting them if they terminate abnormally.</p> - <p>Refer to OTP Design Principles for more information about - OTP supervision trees, which uses this feature.</p> + <p>See <seealso marker= + "doc/design_principles:des_princ#otp design principles"> + OTP Design Principles</seealso> for more information about + OTP supervision trees, which use this feature.</p> <section> <title>Emitting Exit Signals</title> - <p>When a process terminates, it will terminate with an <em>exit reason</em> as explained in <seealso marker="#term">Process Termination</seealso> above. This exit reason is emitted in + <p>When a process terminates, it terminates with an + <em>exit reason</em> as explained in <seealso marker="#term"> + Process Termination</seealso>. This exit reason is emitted in an <em>exit signal</em> to all linked processes.</p> <p>A process can also call the function <c>exit(Pid,Reason)</c>. - This will result in an exit signal with exit reason + This results in an exit signal with exit reason <c>Reason</c> being emitted to <c>Pid</c>, but does not affect the calling process.</p> </section> @@ -156,14 +172,14 @@ spawn(Module, Name, Args) -> pid() <p>A process can be set to trap exit signals by calling:</p> <pre> process_flag(trap_exit, true)</pre> - <p>When a process is trapping exits, it will not terminate when + <p>When a process is trapping exits, it does not terminate when an exit signal is received. Instead, the signal is transformed - into a message <c>{'EXIT',FromPid,Reason}</c> which is put into - the mailbox of the process just like a regular message.</p> + into a message <c>{'EXIT',FromPid,Reason}</c>, which is put into + the mailbox of the process, just like a regular message.</p> <p>An exception to the above is if the exit reason is <c>kill</c>, - that is if <c>exit(Pid,kill)</c> has been called. This will - unconditionally terminate the process, regardless of if it is - trapping exit signals or not.</p> + that is if <c>exit(Pid,kill)</c> has been called. This + unconditionally terminates the process, regardless of if it is + trapping exit signals.</p> </section> </section> @@ -180,12 +196,12 @@ process_flag(trap_exit, true)</pre> <p>If <c>Pid2</c> does not exist, the 'DOWN' message is sent immediately with <c>Reason</c> set to <c>noproc</c>.</p> <p>Monitors are unidirectional. Repeated calls to - <c>erlang:monitor(process, Pid)</c> will create several, - independent monitors and each one will send a 'DOWN' message when + <c>erlang:monitor(process, Pid)</c> creates several + independent monitors, and each one sends a 'DOWN' message when <c>Pid</c> terminates.</p> <p>A monitor can be removed by calling <c>erlang:demonitor(Ref)</c>.</p> - <p>It is possible to create monitors for processes with registered + <p>Monitors can be created for processes with registered names, also at other nodes.</p> </section> diff --git a/system/doc/reference_manual/records.xml b/system/doc/reference_manual/records.xml index 04766531df..72c56b693d 100644 --- a/system/doc/reference_manual/records.xml +++ b/system/doc/reference_manual/records.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2013</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,16 +32,19 @@ elements. It has named fields and is similar to a struct in C. Record expressions are translated to tuple expressions during compilation. Therefore, record expressions are not understood by - the shell unless special actions are taken. See <c>shell(3)</c> - for details.</p> - <p>More record examples can be found in <em>Programming Examples</em>.</p> + the shell unless special actions are taken. For details, see the + <seealso marker="stdlib:shell">shell(3)</seealso> + manual page in STDLIB.</p> + <p>More examples are provided in + <seealso marker="doc/programming_examples:records"> + Programming Examples</seealso>.</p> <section> <title>Defining Records</title> <p>A record definition consists of the name of the record, followed by the field names of the record. Record and field names must be atoms. Each field can be given an optional default value. - If no default value is supplied, <c>undefined</c> will be used.</p> + If no default value is supplied, <c>undefined</c> is used.</p> <pre> -record(Name, {Field1 [= Value1], ... @@ -60,17 +63,18 @@ the corresponding expression <c>ExprI</c>:</p> <pre> #Name{Field1=Expr1,...,FieldK=ExprK}</pre> - <p>The fields may be in any order, not necessarily the same order as + <p>The fields can be in any order, not necessarily the same order as in the record definition, and fields can be omitted. Omitted - fields will get their respective default value instead.</p> - <p>If several fields should be assigned the same value, + fields get their respective default value instead.</p> + <p>If several fields are to be assigned the same value, the following construction can be used:</p> <pre> #Name{Field1=Expr1,...,FieldK=ExprK, _=ExprL}</pre> - <p>Omitted fields will then get the value of evaluating <c>ExprL</c> + <p>Omitted fields then get the value of evaluating <c>ExprL</c> instead of their default values. This feature was added in Erlang 5.1/OTP R8 and is primarily intended to be used to create - patterns for ETS and Mnesia match functions. Example:</p> + patterns for ETS and Mnesia match functions.</p> + <p><em>Example:</em></p> <pre> -record(person, {name, phone, address}). @@ -84,13 +88,13 @@ lookup(Name, Tab) -> <title>Accessing Record Fields</title> <pre> Expr#Name.Field</pre> - <p>Returns the value of the specified field. <c>Expr</c> should + <p>Returns the value of the specified field. <c>Expr</c> is to evaluate to a <c>Name</c> record.</p> <p>The following expression returns the position of the specified field in the tuple representation of the record:</p> <pre> #Name.Field</pre> - <p>Example:</p> + <p><em>Example:</em></p> <pre> -record(person, {name, phone, address}). @@ -104,8 +108,8 @@ lookup(Name, List) -> <title>Updating Records</title> <pre> Expr#Name{Field1=Expr1,...,FieldK=ExprK}</pre> - <p><c>Expr</c> should evaluate to a <c>Name</c> record. Returns a - copy of this record, with the value of each specified field + <p><c>Expr</c> is to evaluate to a <c>Name</c> record. A + copy of this record is returned, with the value of each specified field <c>FieldI</c> changed to the value of evaluating the corresponding expression <c>ExprI</c>. All other fields retain their old values.</p> @@ -116,17 +120,17 @@ Expr#Name{Field1=Expr1,...,FieldK=ExprK}</pre> <title>Records in Guards</title> <p>Since record expressions are expanded to tuple expressions, creating records and accessing record fields are allowed in - guards. However all subexpressions, for example for field - initiations, must of course be valid guard expressions as well. - Examples:</p> + guards. However all subexpressions, for example, for field + initiations, must be valid guard expressions as well.</p> + <p><em>Examples:</em></p> <code type="none"> handle(Msg, State) when Msg==#msg{to=void, no=3} -> ... handle(Msg, State) when State#state.running==true -> ...</code> - <p>There is also a type test BIF <c>is_record(Term, RecordTag)</c>. - Example:</p> + <p>There is also a type test BIF <c>is_record(Term, RecordTag)</c>.</p> + <p><em>Example:</em></p> <pre> is_person(P) when is_record(P, person) -> true; @@ -136,18 +140,18 @@ is_person(_P) -> <section> <title>Records in Patterns</title> - <p>A pattern that will match a certain record is created the same + <p>A pattern that matches a certain record is created in the same way as a record is created:</p> <pre> #Name{Field1=Expr1,...,FieldK=ExprK}</pre> - <p>In this case, one or more of <c>Expr1</c>...<c>ExprK</c> may be + <p>In this case, one or more of <c>Expr1</c>...<c>ExprK</c> can be unbound variables.</p> </section> <section> - <title>Nested records</title> - <p>Beginning with R14 parentheses when accessing or updating nested - records can be omitted. Assuming we have the following record + <title>Nested Records</title> + <p>Beginning with Erlang/OTP R14, parentheses when accessing or updating nested + records can be omitted. Assume the following record definitions:</p> <pre> -record(nrec0, {name = "nested0"}). @@ -156,12 +160,12 @@ is_person(_P) -> N2 = #nrec2{}, </pre> - <p>Before R14 you would have needed to use parentheses as following:</p> + <p>Before R14, parentheses were needed as follows:</p> <pre> "nested0" = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0.name, N0n = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0{name = "nested0a"}, </pre> - <p>Since R14 you can also write:</p> + <p>Since R14, the following can also be written:</p> <pre> "nested0" = N2#nrec2.nrec1#nrec1.nrec0#nrec0.name, N0n = N2#nrec2.nrec1#nrec1.nrec0#nrec0{name = "nested0a"},</pre> @@ -170,23 +174,23 @@ N0n = N2#nrec2.nrec1#nrec1.nrec0#nrec0{name = "nested0a"},</pre> <section> <title>Internal Representation of Records</title> <p>Record expressions are translated to tuple expressions during - compilation. A record defined as</p> + compilation. A record defined as:</p> <pre> -record(Name, {Field1,...,FieldN}).</pre> - <p>is internally represented by the tuple</p> + <p>is internally represented by the tuple:</p> <pre> {Name,Value1,...,ValueN}</pre> - <p>where each <c>ValueI</c> is the default value for <c>FieldI</c>.</p> + <p>Here each <c>ValueI</c> is the default value for <c>FieldI</c>.</p> <p>To each module using records, a pseudo function is added during compilation to obtain information about records:</p> <pre> record_info(fields, Record) -> [Field] record_info(size, Record) -> Size</pre> - <p><c>Size</c> is the size of the tuple representation, that is + <p><c>Size</c> is the size of the tuple representation, that is, one more than the number of fields.</p> <p>In addition, <c>#Record.Name</c> returns the index in the tuple - representation of <c>Name</c> of the record <c>Record</c>. - <c>Name</c> must be an atom.</p> + representation of <c>Name</c> of the record <c>Record</c>.</p> + <p><c>Name</c> must be an atom.</p> </section> </chapter> diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index e4aa2ceda6..53ef93b60f 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2014</year> + <year>2003</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,43 +34,46 @@ <p> Erlang is a dynamically typed language. Still, it comes with a notation for declaring sets of Erlang terms to form a particular - type, effectively forming a specific sub-type of the set of all + type. This effectively forms specific subtypes of the set of all Erlang terms. </p> <p> Subsequently, these types can be used to specify types of record fields - and the argument and return types of functions. - </p> - <p> - Type information can be used to document function interfaces, - provide more information for bug detection tools such as <c>Dialyzer</c>, - and can be exploited by documentation tools such as <c>Edoc</c> for - generating program documentation of various forms. - It is expected that the type language described in this document will - supersede and replace the purely comment-based <c>@type</c> and - <c>@spec</c> declarations used by <c>Edoc</c>. - </p> + and also the argument and return types of functions. + </p> + <p> + Type information can be used for the following:</p> + <list type="bulleted"> + <item>To document function interfaces</item> + <item>To provide more information for bug detection tools, + such as <c>Dialyzer</c></item> + <item>To be exploited by documentation tools, such as EDoc, for + generating program documentation of various forms</item> + </list> + <p>It is expected that the type language described in this section + supersedes and replaces the purely comment-based <c>@type</c> and + <c>@spec</c> declarations used by EDoc.</p> </section> <section> <marker id="syntax"></marker> <title>Types and their Syntax</title> <p> Types describe sets of Erlang terms. - Types consist and are built from a set of predefined types - (e.g. <c>integer()</c>, <c>atom()</c>, <c>pid()</c>, ...) - described below. - Predefined types represent a typically infinite set of Erlang terms which + Types consist of, and are built from, a set of predefined types, + for example, <c>integer()</c>, <c>atom()</c>, and <c>pid()</c>. + Predefined types represent a typically infinite set of Erlang terms that belong to this type. For example, the type <c>atom()</c> stands for the set of all Erlang atoms. </p> <p> - For integers and atoms, we allow for singleton types (e.g. the integers - <c>-1</c> and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>). + For integers and atoms, it is allowed for singleton types; for example, + the integers + <c>-1</c> and <c>42</c>, or the atoms <c>'foo'</c> and <c>'bar'</c>). All other types are built using unions of either predefined types or singleton types. In a type union between a type and one - of its sub-types the sub-type is absorbed by the super-type and - the union is subsequently treated as if the sub-type was not a + of its subtypes, the subtype is absorbed by the supertype. Thus, + the union is then treated as if the subtype was not a constituent of the union. For example, the type union: </p> <pre> atom() | 'bar' | integer() | 42</pre> @@ -79,13 +82,13 @@ </p> <pre> atom() | integer()</pre> <p> - Because of sub-type relations that exist between types, types - form a lattice where the topmost element, <c>any()</c>, denotes + Because of subtype relations that exist between types, types + form a lattice where the top-most element, <c>any()</c>, denotes the set of all Erlang terms and the bottom-most element, <c>none()</c>, denotes the empty set of terms. </p> <p> - The set of predefined types and the syntax for types is given below: + The set of predefined types and the syntax for types follows: </p> <pre><![CDATA[ Type :: any() %% The top type, the set of all Erlang terms @@ -103,7 +106,7 @@ | Map | Tuple | Union - | UserDefined %% described in Section 7.3 + | UserDefined %% described in Type Declarations of User-Defined Types Atom :: atom() | Erlang_Atom %% 'foo', 'bar', ... @@ -146,22 +149,22 @@ <p> The general form of bitstrings is <c><<_:M, _:_*N>></c>, where <c>M</c> and <c>N</c> are positive integers. It denotes a - bitstring that is <c>M + (k*N)</c> bits long (i.e., a bitstring that + bitstring that is <c>M + (k*N)</c> bits long (that is, a bitstring that starts with <c>M</c> bits and continues with <c>k</c> segments of <c>N</c> bits each, where <c>k</c> is also a positive integer). The notations <c><<_:_*N>></c>, <c><<_:M>></c>, and <c><<>></c> are convenient shorthands for the cases - that <c>M</c>, <c>N</c>, or both, respectively, are zero. + that <c>M</c> or <c>N</c>, or both, are zero. </p> <p> Because lists are commonly used, they have shorthand type notations. The types <c>list(T)</c> and <c>nonempty_list(T)</c> have the shorthands <c>[T]</c> and <c>[T,...]</c>, respectively. - The only difference between the two shorthands is that <c>[T]</c> may be an - empty list but <c>[T,...]</c> may not. + The only difference between the two shorthands is that <c>[T]</c> can be an + empty list but <c>[T,...]</c> cannot. </p> <p> - Notice that the shorthand for <c>list()</c>, i.e. the list of + Notice that the shorthand for <c>list()</c>, that is, the list of elements of unknown type, is <c>[_]</c> (or <c>[any()]</c>), not <c>[]</c>. The notation <c>[]</c> specifies the singleton type for the empty list. </p> @@ -172,7 +175,7 @@ </p> <table> <row> - <cell><b>Built-in type</b></cell><cell><b>Defined as</b></cell> + <cell><em>Built-in type</em></cell><cell><em>Defined as</em></cell> </row> <row> <cell><c>term()</c></cell><cell><c>any()</c></cell> @@ -223,7 +226,7 @@ <cell><c>module()</c></cell><cell><c>atom()</c></cell> </row> <row> - <cell><c>mfa()</c></cell><cell><c>{atom(),atom(),arity()}</c></cell> + <cell><c>mfa()</c></cell><cell><c>{module(),atom(),arity()}</c></cell> </row> <row> <cell><c>arity()</c></cell><cell><c>0..255</c></cell> @@ -237,6 +240,7 @@ <row> <cell><c>no_return()</c></cell><cell><c>none()</c></cell> </row> + <tcaption>Built-in types, predefined aliases</tcaption> </table> <p> In addition, the following three built-in types exist and can be @@ -245,7 +249,8 @@ </p> <table> <row> - <cell><b>Built-in type</b></cell><cell><b>Could be thought defined by the syntax</b></cell> + <cell><em>Built-in type</em></cell><cell><em> + Can be thought defined by the syntax</em></cell> </row> <row> <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell> @@ -256,6 +261,7 @@ <row> <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell> </row> + <tcaption>Additional built-in types</tcaption> </table> <p> @@ -264,8 +270,10 @@ its violation results in a compilation error. </p> <note> - The following built-in list types also exist, - but they are expected to be rarely used. Hence, they have long names: + <p> + The following built-in list types also exist, + but they are expected to be rarely used. Hence, they have long names: + </p> </note> <pre> nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any(), any()) @@ -276,109 +284,118 @@ define the set of Erlang terms one would expect. </p> <p> - Also for convenience, we allow for record notation to be used. - Records are just shorthands for the corresponding tuples. + Also for convenience, record notation is allowed to be used. + Records are shorthands for the corresponding tuples: </p> <pre> Record :: #Erlang_Atom{} | #Erlang_Atom{Fields}</pre> <p> - Records have been extended to possibly contain type information. - This is described in the sub-section <seealso marker="#typeinrecords">"Type information in record declarations"</seealso> below. + Records are extended to possibly contain type information. + This is described in <seealso marker="#typeinrecords"> + Type Information in Record Declarations</seealso>. </p> <note> - <p>Map types, both <c>map()</c> and <c>#{ ... }</c>, are considered experimental during OTP 17.</p> - <p>No type information of maps pairs, only the containing map types, are used by Dialyzer in OTP 17.</p> + <p>Map types, both <c>map()</c> and <c>#{...}</c>, + are considered experimental during OTP 17.</p> + <p>No type information of maps pairs, only the containing map types, + are used by Dialyzer in OTP 17.</p> </note> </section> - + <section> - <title>Type declarations of user-defined types</title> + <title>Type Declarations of User-Defined Types</title> <p> As seen, the basic syntax of a type is an atom followed by closed - parentheses. New types are declared using '-type' and '-opaque' + parentheses. New types are declared using <c>-type</c> and <c>-opaque</c> compiler attributes as in the following: </p> <pre> -type my_struct_type() :: Type. -opaque my_opaq_type() :: Type.</pre> <p> - where the type name is an atom (<c>'my_struct_type'</c> in the above) - followed by parentheses. Type is a type as defined in the + The type name is the atom <c>my_struct_type</c>, + followed by parentheses. <c>Type</c> is a type as defined in the previous section. - A current restriction is that Type can contain only predefined types, - or user-defined types which are either module-local (i.e., with a - definition that is present in the code of the module) or are remote - types (i.e., types defined in and exported by other modules; see below). - For module-local types, the restriction that their definition + A current restriction is that <c>Type</c> can contain + only predefined types, + or user-defined types which are either of the following: + </p> + <list type="bulleted"> + <item>Module-local type, that is, with a + definition that is present in the code of the module</item> + <item>Remote type, that is, type defined in, and exported by, + other modules; more about this soon.</item> + </list> + <p>For module-local types, the restriction that their definition exists in the module is enforced by the compiler and results in a - compilation error. (A similar restriction currently exists for records.) - </p> + compilation error. (A similar restriction currently exists for records.) </p> <p> Type declarations can also be parameterized by including type variables between the parentheses. The syntax of type variables is the same as - Erlang variables (starts with an upper case letter). - Naturally, these variables can - and should - appear on the RHS of the - definition. A concrete example appears below: + Erlang variables, that is, starts with an upper-case letter. + Naturally, these variables can - and is to - appear on the RHS of the + definition. A concrete example follows: </p> <pre> -type orddict(Key, Val) :: [{Key, Val}].</pre> <p> - A module can export some types in order to declare that other modules + A module can export some types to declare that other modules are allowed to refer to them as <em>remote types</em>. - This declaration has the following form: + This declaration has the following form:</p> <pre> -export_type([T1/A1, ..., Tk/Ak]).</pre> - where the Ti's are atoms (the name of the type) and the Ai's are their - arguments. An example is given below: + <p>Here the Ti's are atoms (the name of the type) and the Ai's are their + arguments</p> + <p><em>Example:</em></p> <pre> -export_type([my_struct_type/0, orddict/2]).</pre> - Assuming that these types are exported from module <c>'mod'</c> then - one can refer to them from other modules using remote type expressions - like those below: + <p>Assuming that these types are exported from module <c>'mod'</c>, + you can refer to them from other modules using remote type expressions + like the following:</p> <pre> mod:my_struct_type() mod:orddict(atom(), term())</pre> - One is not allowed to refer to types which are not declared as exported. + <p>It is not allowed to refer to types that are not declared as exported. </p> <p> Types declared as <c>opaque</c> represent sets of terms whose - structure is not supposed to be visible in any way outside of - their defining module (i.e., only the module defining them is - allowed to depend on their term structure). Consequently, such + structure is not supposed to be visible from outside of + their defining module. That is, only the module defining them + is allowed to depend on their term structure. Consequently, such types do not make much sense as module local - module local - types are not accessible by other modules anyway - and should - always be exported. + types are not accessible by other modules anyway - and is + always to be exported. </p> </section> - - <marker id="typeinrecords"/> + <section> - <title>Type information in record declarations</title> + <marker id="typeinrecords"/> + <title>Type Information in Record Declarations</title> <p> - The types of record fields can be specified in the declaration of the - record. The syntax for this is: + The types of record fields can be specified in the declaration of the + record. The syntax for this is as follows: </p> <pre> -record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre> <p> For fields without type annotations, their type defaults to any(). - I.e., the above is a shorthand for: + That is, the previous example is a shorthand for the following: </p> <pre> -record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre> <p> In the presence of initial values for fields, - the type must be declared after the initialization as in the following: + the type must be declared after the initialization, as follows: </p> <pre> -record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre> <p> - Naturally, the initial values for fields should be compatible - with (i.e. a member of) the corresponding types. - This is checked by the compiler and results in a compilation error - if a violation is detected. For fields without initial values, - the singleton type <c>'undefined'</c> is added to all declared types. + The initial values for fields are to be compatible + with (that is, a member of) the corresponding types. + This is checked by the compiler and results in a compilation error + if a violation is detected. For fields without initial values, + the singleton type <c>'undefined'</c> is added to all declared types. In other words, the following two record declarations have identical effects: </p> @@ -396,13 +413,13 @@ </p> <p> Any record, containing type information or not, once defined, - can be used as a type using the syntax: + can be used as a type using the following syntax: </p> <pre> #rec{}</pre> <p> In addition, the record fields can be further specified when using - a record type by adding type information about the field in - the following manner: + a record type by adding type information about the field + as follows: </p> <pre> #rec{some_field :: Type}</pre> <p> @@ -412,16 +429,16 @@ </section> <section> - <title>Specifications for functions</title> + <title>Specifications for Functions</title> <p> A specification (or contract) for a function is given using the new - compiler attribute <c>'-spec'</c>. The general format is as follows: + compiler attribute <c>-spec</c>. The general format is as follows: </p> <pre> -spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> <p> - The arity of the function has to match the number of arguments, - or else a compilation error occurs. + The arity of the function must match the number of arguments, + else a compilation error occurs. </p> <p> This form can also be used in header files (.hrl) to declare type @@ -430,7 +447,7 @@ explicitly) import these functions. </p> <p> - For most uses within a given module, the following shorthand suffices: + Within a given module, the following shorthand suffice in most cases: </p> <pre> -spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre> @@ -448,8 +465,8 @@ ; (T4, T5) -> T6.</pre> <p> A current restriction, which currently results in a warning - (OBS: not an error) by the compiler, is that the domains of - the argument types cannot be overlapping. + (not an error) by the compiler, is that the domains of + the argument types cannot overlap. For example, the following specification results in a warning: </p> <pre> @@ -464,62 +481,67 @@ <pre> -spec id(X) -> X.</pre> <p> - However, note that the above specification does not restrict the input - and output type in any way. - We can constrain these types by guard-like subtype constraints + Notice that the above specification does not restrict the input + and output type in any way. + These types can be constrained by guard-like subtype constraints and provide bounded quantification: </p> <pre> -spec id(X) -> X when X :: tuple().</pre> <p> Currently, the <c>::</c> constraint (read as <c>is_subtype</c>) is - the only guard constraint which can be used in the <c>'when'</c> + the only guard constraint that can be used in the <c>'when'</c> part of a <c>'-spec'</c> attribute. </p> <note> <p> - The above function specification, using multiple occurrences of - the same type variable, provides more type information than the - function specification below where the type variables are missing: + The above function specification uses multiple occurrences of + the same type variable. That provides more type information than the + following function specification, where the type variables are missing: </p> <pre> -spec id(tuple()) -> tuple().</pre> <p> The latter specification says that the function takes some tuple - and returns some tuple, while the one with the <c>X</c> type + and returns some tuple. The specification with the <c>X</c> type variable specifies that the function takes a tuple and returns <em>the same</em> tuple. </p> <p> - However, it's up to the tools that process the specs to choose - whether to take this extra information into account or ignore it. + However, it is up to the tools that process the specificationss + to choose whether to take this extra information into account + or not. </p> </note> <p> - The scope of an <c>::</c> constraint is the - <c>(...) -> RetType</c> - specification after which it appears. To avoid confusion, - we suggest that different variables are used in different - constituents of an overloaded contract as in the example below: + The scope of a <c>::</c> constraint is the + <c>(...) -> RetType</c> + specification after which it appears. To avoid confusion, + it is suggested that different variables are used in different + constituents of an overloaded contract, as shown in the + following example: </p> <pre> -spec foo({X, integer()}) -> X when X :: atom() ; ([Y]) -> Y when Y :: number().</pre> <note> + <p> For backwards compatibility the following form is also allowed: + </p> <pre> -spec id(X) -> X when is_subtype(X, tuple()).</pre> <p> - but its use is discouraged. It will be taken out in a future + but its use is discouraged. It will be removed in a future Erlang/OTP release. </p> </note> <p> Some functions in Erlang are not meant to return; either because they define servers or because they are used to - throw exceptions as the function below: + throw exceptions, as in the following function: </p> <pre> my_error(Err) -> erlang:throw({error, Err}).</pre> <p> - For such functions we recommend the use of the special <c>no_return()</c> - type for their "return", via a contract of the form: + For such functions, it is recommended to use the special + <c>no_return()</c> type for their "return", through a contract + of the following form: </p> <pre> -spec my_error(term()) -> no_return().</pre> </section> |