From 83ce6b353391f283fdb3e70f475c4ed1d09b152b Mon Sep 17 00:00:00 2001 From: Jan Uhlig Date: Mon, 23 Mar 2026 17:49:23 +0100 Subject: [PATCH] Fix typos in Reference Manual Co-authored-by: Maria Scott --- system/doc/reference_manual/character_set.md | 2 +- system/doc/reference_manual/code_loading.md | 14 +- system/doc/reference_manual/data_types.md | 104 +++++++-------- system/doc/reference_manual/distributed.md | 38 +++--- system/doc/reference_manual/documentation.md | 66 +++++----- system/doc/reference_manual/errors.md | 24 ++-- system/doc/reference_manual/expressions.md | 120 +++++++++--------- system/doc/reference_manual/features.md | 26 ++-- system/doc/reference_manual/macros.md | 14 +- system/doc/reference_manual/modules.md | 24 ++-- system/doc/reference_manual/nominals.md | 2 +- system/doc/reference_manual/opaques.md | 10 +- system/doc/reference_manual/ports.md | 10 +- .../doc/reference_manual/ref_man_functions.md | 4 +- .../doc/reference_manual/ref_man_processes.md | 96 +++++++------- .../doc/reference_manual/ref_man_records.md | 2 +- .../doc/reference_manual/reference_manual.md | 2 +- system/doc/reference_manual/typespec.md | 24 ++-- 18 files changed, 291 insertions(+), 291 deletions(-) diff --git a/system/doc/reference_manual/character_set.md b/system/doc/reference_manual/character_set.md index 826ad1e9e64c..713e268389c6 100644 --- a/system/doc/reference_manual/character_set.md +++ b/system/doc/reference_manual/character_set.md @@ -23,7 +23,7 @@ limitations under the License. ## Character Set -The syntax of Erlang tokens allow the use of the full ISO-8859-1 (Latin-1) +The syntax of Erlang tokens allows the use of the full ISO-8859-1 (Latin-1) character set. This is noticeable in the following ways: - All the Latin-1 printable characters can be used and are shown without the diff --git a/system/doc/reference_manual/code_loading.md b/system/doc/reference_manual/code_loading.md index 2373e68107ad..67c87cfd6059 100644 --- a/system/doc/reference_manual/code_loading.md +++ b/system/doc/reference_manual/code_loading.md @@ -29,7 +29,7 @@ Erlang/OTP with references to relevant parts of the documentation. Erlang programs must be _compiled_ to object code. 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 +the object code, is called BEAM and therefore the object files get the suffix `.beam`. The compiler can also generate a binary which can be loaded directly. The compiler is located in the module `m:compile` in Compiler. @@ -53,7 +53,7 @@ The compiler can also be accessed from the OS prompt using the % erl -make ``` -The `erlc` program provides way to compile modules from the OS +The `erlc` program provides a way to compile modules from the OS shell, see the [erlc](`e:erts:erlc_cmd.md`) executable in ERTS. It understands a number of flags that can be used to define macros, add search paths for include files, and more. @@ -73,7 +73,7 @@ The code server loads code according to a code loading strategy, which is either _interactive_ (default) or _embedded_. In interactive mode, code is searched for in a _code path_ and loaded when first referenced. In embedded mode, code is loaded at start-up according to a _boot script_. This is described in -[System Principles ](`e:system:system_principles.md#code_loading`). +[System Principles](`e:system:system_principles.md#code_loading`). ## Code Replacement @@ -85,12 +85,12 @@ When a module is loaded into 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'. -Both old and current code is valid, and can be evaluated concurrently. Fully +Both old and current code are valid, and can be evaluated concurrently. Fully qualified function calls always refer to current code. Old code can still be evaluated because of processes lingering in the old code. 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 +the old code and any processes lingering in it are terminated. Then the third instance becomes 'current' and the previously current code becomes 'old'. To change from old code to current code, a process must make a fully qualified @@ -147,7 +147,7 @@ and can be called until the `on_load` function has returned. If the `on_load` function fails, the current code (if any) will remain current. If there is no current code for a module, any process that makes an external call to the module before the `on_load` function has finished will be suspended until the `on_load` -function have finished. +function has finished. > #### Change {: .info } > @@ -172,4 +172,4 @@ load_my_nifs() -> ``` If the call to `erlang:load_nif/2` fails, the module is unloaded and a warning -report is sent to the error loader. +report is sent to the error logger. diff --git a/system/doc/reference_manual/data_types.md b/system/doc/reference_manual/data_types.md index 8d99c1ec067a..90d0ae991e15 100644 --- a/system/doc/reference_manual/data_types.md +++ b/system/doc/reference_manual/data_types.md @@ -25,11 +25,11 @@ Erlang provides a number of data types, which are listed in this section. [](){: #no_user_types } -Note that Erlang has no user defined types, only composite types (data +Note that Erlang has no user-defined types, only composite types (data structures) made of Erlang terms. This means that any function testing for a composite type, typically named `is_type/1`, might return `true` for a term that -coincides with the chosen representation. The corresponding functions for built -in types do not suffer from this. +coincides with the chosen representation. The corresponding functions for built-in +types do not suffer from this. ## Terms @@ -38,28 +38,28 @@ A piece of data of any data type is called a _term_. ## Number There are two types of numeric literals, _integers_ and _floats_. Besides the -conventional notation, there are two Erlang-specific notations: +conventional notation, there are three Erlang-specific notations: - `$`_`char`_ - ASCII value or unicode code-point of the character _`char`_. + ASCII value or Unicode code-point of the character _`char`_. - _`base`_`#`_`digits`_ Integer with the base _`base`_, which must be an integer in the range 2 - through 36. _`digits`_ are `0`-`9` plus letters `A`-`Z` (upper or lower case). + through 36. _`digits`_ are `0`-`9` plus letters `A`-`Z` (upper- or lowercase). This notation can also be found in the Ada programming language. Erlang does _not_ support prefixes such as `0x` for hexadecimal or `077` for octal. - _`base`_`#`_`digits`_`.`_`digits`_`#e`_`exponent`_ - Based floating point number, for example `16#ff.fe#e+6`. Using a base - like 16 or 2 allows for an exact text representation of a floating - point number. Like the base, the exponent is always a decimal number. + Based floating-point number, for example `16#ff.fe#e+6`. Using a base + like 16 or 2 allows for an exact text representation of a floating-point + number. Like the base, the exponent is always a decimal number. Leading zeroes are ignored. Single underscore characters (`_`) can be inserted between digits as a visual separator. -Also note that floating point numbers must start with a digit, and must +Also note that floating-point numbers must start with a digit, and must contain a `.`. In other words, literals such as `.01` and `1e6` are not -allowed, and must be written `0.01` and `1.0e6` respectively. +allowed, and must be written `0.01` and `1.0e6`, respectively. _Examples:_ @@ -99,7 +99,7 @@ than `2.4`, `3` compares greater than `2.99999`, and `5` is equal to `5.0`. When wanting to compare an integer with another integer or a float with another float, it may be tempting to use the term equivalence operators (`=:=`, `=/=`) -or pattern matching. This works for integers which has a distinct representation +or pattern matching. This works for integers, which have a distinct representation for every number, but there's a surprising edge case for floating-point as the latter has two representations for zero which are considered different by the term equivalence operators and pattern matching. @@ -137,9 +137,9 @@ false true ``` -### Representation of Floating Point Numbers +### Representation of Floating-Point Numbers -When working with floats you may not see what you expect when printing or doing +When working with floats, you may not see what you expect when printing or doing arithmetic operations. This is because floats are represented by a fixed number of bits in a base-2 system while printed floats are represented with a base-10 system. Erlang uses 64-bit floats. Here are examples of this phenomenon: @@ -164,7 +164,7 @@ Erlang's pretty printer rounds `36028797018963968.0` to `3.602879701896397e16` `[36028797018963966.0, 36028797018963972.0]` are represented by `36028797018963968.0`. -For more information about floats and issues with them see: +For more information about floats and issues with them, see: - [What Every Programmer Should Know About Floating-Point Arithmetic](https://floating-point-gui.de/) - [0\.30000000000000004.com/](https://0.30000000000000004.com/) @@ -194,9 +194,9 @@ _Examples_: ## Atom -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 `@`. +An atom is a literal, a constant with a name. An atom is to be enclosed in single +quotes (`'`) if it does not begin with a lowercase letter or if it contains +characters other than alphanumeric characters, underscore (`_`), or `@`. _Examples:_ @@ -266,7 +266,7 @@ true ## Fun 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 +function and pass the function itself — not its name — as an argument to other functions. _Examples:_ @@ -279,7 +279,7 @@ _Examples:_ ``` The [`is_function/1`](`erlang:is_function/1`) and [`is_function/2`](`erlang:is_function/2`) -BIFs tests whether a term is a fun. +BIFs test whether a term is a fun. _Examples_: @@ -319,7 +319,7 @@ The BIF [`self/0`](`erlang:self/0`) returns the Pid of the calling process. When process will be able to get the Pid of the child process either via the return value, as is the case when calling the [`spawn/3`](`erlang:spawn/3`) BIF, or via a message, which is the case when calling the -[`spawn_request/5`](`erlang:spawn_request/5`) BIF. A Pid is typically used when +[`spawn_request/5`](`erlang:spawn_request/5`) BIF. A Pid is typically used when sending a process a [signal](ref_man_processes.md#signals). The [`is_pid/1`](`erlang:is_pid/1`) BIF tests whether a term is a Pid. @@ -356,7 +356,7 @@ A tuple is a compound data type with a fixed number of terms: Each term `Term` in the tuple is called an _element_. The number of elements is said to be the _size_ of the tuple. -There exists a number of BIFs to manipulate tuples. +There are a number of BIFs to manipulate tuples. _Examples:_ @@ -389,7 +389,7 @@ Each key-value association in the map is called an _association pair_. The key and value parts of the pair are called _elements_. The number of association pairs is said to be the _size_ of the map. -There exists a number of BIFs to manipulate maps. +There are a number of BIFs to manipulate maps. _Examples:_ @@ -402,13 +402,13 @@ adam {july,29} 4> M2 = maps:update(age, 25, M1). #{age => 25,date => {july,29},name => adam} -5> map_size(M). +5> map_size(M2). 3 6> map_size(#{}). 0 ``` -A collection of maps processing functions are found in module `m:maps` +A collection of map-processing functions can be found in the module `m:maps` in STDLIB. Read more about maps in [Map Expressions](expressions.md#map-expressions). @@ -432,7 +432,7 @@ said to be the _length_ of the list. Formally, a list is either the empty list `[]` or consists of a _head_ (first element) and a _tail_ (remainder of the list). The _tail_ is also a list. The latter can be expressed as `[H|T]`. The notation `[Term1,...,TermN]` above is -equivalent with the list `[Term1|[...|[TermN|[]]]]`. +equivalent to the list `[Term1|[...|[TermN|[]]]]`. _Example:_ @@ -464,16 +464,16 @@ a 0 ``` -A collection of list processing functions are found in module +A collection of list-processing functions can be found in the module `m:lists` in STDLIB. ## String -Strings are enclosed in double quotes ("), but is not a data type in Erlang. +Strings are enclosed in double quotes ("), but are not a data type in Erlang. Instead, a string `"hello"` is shorthand for the list `[$h,$e,$l,$l,$o]`, that is, `[104,101,108,108,111]`. -Two adjacent string literals are concatenated into one. This is done in the +Two adjacent string literals are concatenated into one. This is done during compilation. _Example:_ @@ -490,7 +490,7 @@ is equivalent to > #### Change {: .info } > -> Starting with Erlang/OTP 27 two adjacent string literals have to be separated +> Starting with Erlang/OTP 27, two adjacent string literals have to be separated > by white space, or otherwise it is a syntax error. This avoids possible confusion > with _triple-quoted strings_. @@ -501,11 +501,11 @@ sequences, and thereby do not need double quote characters to be escaped. > #### Change {: .info } > -> Triple-quoted strings were added in Erlang/OTP 27. Before that 3 consecutive -> double quote characters had a different meaning. There were absolutely no good +> Triple-quoted strings were added in Erlang/OTP 27. Before that, 3 consecutive +> double quote characters had a different meaning. There was absolutely no good > reason to write such a character sequence before triple-quoted strings > existed, but there _are_ some gotchas; see the -> [Warning ](data_types.md#triple-quoted-strings-warning) at the end of this +> [Warning](data_types.md#triple-quoted-strings-warning) at the end of this > description of triple-quoted strings. Example, with verbatim double quote characters: @@ -517,7 +517,7 @@ Example, with verbatim double quote characters: """ ``` -That is equivalent to the normal single quoted string (which also allows +That is equivalent to a normal single-quoted string (which also allows newlines): ```text @@ -525,7 +525,7 @@ newlines): Line \"2\"" ``` -The opening and the closing line has got the delimiters: the `"""` characters. +The opening and closing lines contain the delimiters, the `"""` characters. The lines between them are the content lines. The newline on the opening line is not regarded as string content, nor is the newline on the last content line. @@ -536,7 +536,7 @@ line, or else it is regarded as a content line. The opening line is not allowed to have any characters other than white space after the delimiter, and all content lines must start with the defined -indentation character sequence, otherwise the string has a syntax error. +indentation character sequence; otherwise, the string has a syntax error. Here is a larger example: @@ -556,7 +556,7 @@ Not escaped: \"\\t \\r \\xFF\" and \"\"\" " ``` -It is possible to write consecutive double quote characters on the +It is possible to write consecutive double quote characters at the beginning of a content line by using more double quote characters as delimiters. This is a string that contains exactly four double quote characters, using a delimiter with five double quote characters: @@ -601,7 +601,7 @@ These strings are all the empty string: > strings. > > The compiler preprocessor was patched in Erlang/OTP 26.1 to warn about 3 or -> more sequential double quote characters. In Erlang/OTP 26.2 this was improved +> more sequential double quote characters. In Erlang/OTP 26.2, this was improved > to warn about adjacent string literals without intervening white space, which > also covers the same problem at a string end. > @@ -618,7 +618,7 @@ offer mainly two things: a compact way to create UTF-8 encoded binary strings, and a way to write verbatim strings (not having to escape `\` characters), useful for regular expressions, for example. -A sigil starts with the Tilde character (`~`) followed by a name defining the +A sigil starts with the tilde character (`~`) followed by a name defining the sigil type. Immediately after follows the sigil content; a character sequence between @@ -627,19 +627,19 @@ content delimiters. The allowed delimiters are these start-end delimiter pairs: ``/ | ' " ` #``. [Triple-quote](data_types.md#tqstring) string delimiters may also be used. -The [character escaping rules ](data_types.md#escape-sequences)for the sigil -content depends on the sigil type. When the sigil content is _verbatim_, there +The [character escaping rules](data_types.md#escape-sequences) for the sigil +content depend on the sigil type. When the sigil content is _verbatim_, there is no escape character. The sigil content simply ends when the end delimiter is found, so it is impossible to have the end delimiter character in the string content. The set of delimiters is fairly generous, and in most cases it is possible to choose an end delimiter that's not in the literal string content. [Triple-quote](data_types.md#tqstring) string delimiters allow choosing a larger -number of quote characters in the end delimiter, than whatever is in the string +number of quote characters in the end delimiter than whatever is in the string content, which thereby facilitates any content also with a sequence of `"` characters at the start of a line even for a _verbatim_ string. -The Sigils are: +The sigils are: - **`~`** - The Vanilla (default) Sigil. Shorthand for a UTF-8 encoded `t:binary/0`. This sigil does not affect the character escaping rules, so with @@ -648,7 +648,7 @@ The Sigils are: - **`~b`** - The Binary Sigil. Shorthand for a [UTF-8 encoded `binary()`](`t:unicode:unicode_binary/0`), as if calling - [`unicode:characters_to_binary/1` ](`unicode:characters_to_binary/1`)on the + [`unicode:characters_to_binary/1`](`unicode:characters_to_binary/1`) on the sigil content. Character escaping rules are the same as for `~s`. - **`~B`** - The Verbatim Binary Sigil. As `~b`, but the sigil content is @@ -657,14 +657,14 @@ The Sigils are: - **`~s`** - The String Sigil. Shorthand for a [`string()`](`t:erlang:string/0`), that is, a `[char()]` which is a list of Unicode codepoints. - [Character escaping rules ](data_types.md#escape-sequences)are the same as for + [Character escaping rules](data_types.md#escape-sequences) are the same as for a normal `t:string/0`. Using this sigil on a regular string does effectively nothing. - **`~S`** - The Verbatim String Sigil. As `~s`, but the sigil content is verbatim. Using this sigil on a triple-quoted string does effectively nothing. -Examples +_Examples:_ ```text <<"\"\\µA\""/utf8>> = <<$",$\\,194,181,$A,$">> = @@ -692,7 +692,7 @@ Examples """ = "\"\\µA\"" ``` -Adjacent strings are concatenated in the compilation, but that is not possible +Adjacent strings are concatenated during compilation, but that is not possible with sigils, since they are transformed into terms that in general may not be concatenated. So, `"a" "b"` is equivalent to `"ab"`, but `~s"a" "b"` or `~s"a" ~s"b"` is a syntax error. `~s"a" ++ "b"`, however, evaluates to `"ab"` @@ -700,7 +700,7 @@ since both operands to the `++` operator are strings. > #### Change {: .info } > -> Sigils were introduced in Erlang/OTP 27 +> Sigils were introduced in Erlang/OTP 27. ## Record @@ -770,7 +770,7 @@ false ## Boolean -There is no Boolean data type in Erlang. Instead the atoms `true` and `false` +There is no Boolean data type in Erlang. Instead, the atoms `true` and `false` are used to denote Boolean values. The [`is_boolean/1`](`erlang:is_boolean/1`) BIF tests whether a term is a boolean. @@ -834,12 +834,12 @@ recognized. The only text that cannot be written in a triple-quoted string is three consecutive double quote characters at the beginning of a line (preceded only by whitespace). This limitation can be worked around by using more double quote characters for the string delimiters than in the string. Any number three -or above is allowed for the start delimiter and the end delimiter is the same as +or above is allowed for the start delimiter, and the end delimiter is the same as the start delimiter. When triple-quote string delimiters are used with the -[`~`, `~B` or `~S` sigils ](data_types.md#sigil)the same applies, but for the -[`~b` or `~s` sigils ](data_types.md#sigil)the escape sequences for normal +[`~`, `~B` or `~S` sigils](data_types.md#sigil), the same applies, but for the +[`~b` or `~s` sigils](data_types.md#sigil) the escape sequences for normal strings, above, are used. > #### Change {: .info } diff --git a/system/doc/reference_manual/distributed.md b/system/doc/reference_manual/distributed.md index 13fad7c050ac..d1862ce48d9c 100644 --- a/system/doc/reference_manual/distributed.md +++ b/system/doc/reference_manual/distributed.md @@ -38,11 +38,11 @@ an alternative carrier is described in the > > Starting a distributed node without also specifying > [`-proto_dist inet_tls`](`e:erts:erl_cmd.md#proto_dist`) will expose the node -> to attacks that may give the attacker complete access to the node and in -> extension the cluster. When using un-secure distributed nodes, make sure that +> to attacks that may give the attacker complete access to the node and by +> extension the cluster. When using insecure distributed nodes, make sure that > the network is configured to keep potential attackers out. See the > [Using SSL for Erlang Distribution](`e:ssl:ssl_distribution.md`) User's Guide -> for details on how to setup a secure distributed node. +> for details on how to set up a secure distributed node. ## Nodes @@ -68,7 +68,7 @@ _Example:_ dilbert@uab ``` -The node name can also be given in runtime by calling `net_kernel:start/1`. +The node name can also be given at runtime by calling `net_kernel:start/1`. _Example:_ @@ -109,7 +109,7 @@ The list of (visible) nodes currently connected to is returned by `nodes/0`. The Erlang Port Mapper Daemon _epmd_ 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 the [epmd](`e:erts:epmd_cmd.md`) in ERTS. +names to machine addresses. See [epmd](`e:erts:epmd_cmd.md`) in ERTS. ## Hidden Nodes @@ -120,8 +120,8 @@ status of a system, without disturbing it. For this purpose, a _hidden node_ can be used. A hidden node is a node started with the command-line flag `-hidden`. -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 +Connections between hidden nodes and other nodes are not transitive; they must +be set up explicitly. Also, hidden nodes do not show up in the list of nodes returned by `nodes/0`. Instead, [`nodes(hidden)`](`nodes/1`) or [`nodes(connected)`](`nodes/1`) must be used. This means, for example, that the hidden node is not added to the set of nodes that `m:global` is keeping track of. @@ -130,9 +130,9 @@ hidden node is not added to the set of nodes that `m:global` is keeping track of ## Dynamic Node Name -If the node name is set to _`undefined`_ the node will be started in a special +If the node name is set to _`undefined`_, the node will be started in a special mode to be the temporary client of another node. The node will then request a -dynamic node name from the first node it connects to. In addition these +dynamic node name from the first node it connects to. In addition, these distribution settings will be set: ```text @@ -140,7 +140,7 @@ distribution settings will be set: ``` As `-dist_auto_connect` is set to `never`, `net_kernel:connect_node/1` must be -called in order to setup connections. If the first established connection is +called in order to set up connections. If the first established connection is closed (which gave the node its dynamic name), then any other connections will also be closed and the node will lose its dynamic node name. A new call to `net_kernel:connect_node/1` can be made to get a new dynamic node name. The node @@ -158,7 +158,7 @@ A _C node_ is a C program written to act as a hidden node in a distributed Erlang system. The library _Erl_Interface_ contains functions for this purpose. For more information about C nodes, see the [Erl_Interface](`e:erl_interface:ei_users_guide.md`) application and -[Interoperability Tutorial.](`e:system:tutorial.md`). +[Interoperability Tutorial](`e:system:tutorial.md`). ## Security @@ -168,9 +168,9 @@ For more information about C nodes, see the > against accidental misuse, such as preventing a node from connecting to a > cluster with which it is not intended to communicate. > -> Furthermore, the communication between nodes is per default in clear text. If +> Furthermore, the communication between nodes is by default in clear text. If > you need strong security, please see -> [Using TLS for Erlang Distribution ](`e:ssl:ssl_distribution.md`)in the SSL +> [Using TLS for Erlang Distribution](`e:ssl:ssl_distribution.md`) in the SSL > application's User's Guide. > > Also, the default random cookie mentioned in the following text is not very @@ -181,11 +181,11 @@ For more information about C nodes, see the Authentication determines which nodes are allowed to communicate with each other. In a network of different Erlang nodes, it is built into the system at the lowest possible level. All nodes use a _magic cookie_, which is an Erlang -atom, when connecting another node. +atom, when connecting to another node. During the connection setup, after node names have been exchanged, the magic cookies the nodes present to each other are compared. If they do not match, the -connection is rejected. The cookies themselves are never transferred, instead +connection is rejected. The cookies themselves are never transferred; instead, they are compared using hashed challenges, although not in a cryptographically secure manner. @@ -220,17 +220,17 @@ cookie files) can be handled in this way. > > You can also use a `DiffCookie` that neither `Node1` nor `Node2` has as its > default cookie, if you also call `erlang:set_cookie(Node1, DiffCookie)` in -> `Node2` before establishing connection +> `Node2` before establishing a connection. > > Because node names are exchanged during connection setup before cookies are -> selected, connection setup works regardless of which node that initiates it. +> selected, connection setup works regardless of which node initiates it. > > Note that to configure `Node1` to use `Node2`'s default cookie when > communicating with `Node2`, _and vice versa_ results in a broken configuration > (if the cookies are different) because then both nodes use the other node's > (differing) cookie. -The default when a connection is established between two nodes, is to +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 can be inappropriate (since it may not be feasible to configure different @@ -257,7 +257,7 @@ Here are some BIFs that are useful for distributed programming: can connect to other nodes, `false` otherwise. - [`monitor_node(Node, Bool)`](`erlang:monitor_node/2`) - Monitors the - status of `Node`. A message`{nodedown, Node}` is received if the + status of `Node`. A `{nodedown, Node}` message is received if the connection to it is lost. - `node/0` - Returns the name of the current node. Allowed in guards. diff --git a/system/doc/reference_manual/documentation.md b/system/doc/reference_manual/documentation.md index a4c2d31a35f2..1e282dafd8bb 100644 --- a/system/doc/reference_manual/documentation.md +++ b/system/doc/reference_manual/documentation.md @@ -47,12 +47,12 @@ attributes that can be documented are [behaviour module attributes](modules.md#behaviour-module-attribute) (`-callback`). -By default the format used for documentation attributes is +By default, the format used for documentation attributes is [Markdown](https://en.wikipedia.org/wiki/Markdown) but that can be changed by setting [module documentation metadata](#moduledoc-metadata). -A good starting point to writing Markdown is +A good starting point for writing Markdown is [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). For details on what is allowed to be part of the `-moduledoc` and `-doc` @@ -100,7 +100,7 @@ that only [atoms](data_types.md#atom) are used for keys and ## External documentation files -The `-moduledoc` and `-doc` can also be placed in external files. To do so use +The `-moduledoc` and `-doc` attributes can also be placed in external files. To do so, use `-doc {file, "path/to/doc.md"}` to point to the documentation. The path used is relative to the file where the `-doc` attribute is located. For example: @@ -122,11 +122,11 @@ add(One, Two) -> One + Two. The module description should include details on how to use the API and examples of the different functions working together. Here is a good place to use images and other diagrams to better show the usage of the module. Instead of writing a -long text in the `moduledoc` attribute, it could be better to break it out into +long text in the `-moduledoc` attribute, it could be better to break it out into an external page. -The `moduledoc` attribute should start with a short paragraph describing the -module and then go into greater details. For example: +The `-moduledoc` attribute should start with a short paragraph describing the +module and then go into greater detail. For example: ````erlang -module(arith). @@ -136,7 +136,7 @@ module and then go into greater details. For example: This module can be used to add and subtract values. For example: ```erlang - 1> arith:substract(arith:add(2, 3), 1). + 1> arith:subtract(arith:add(2, 3), 1). 4 ``` """. @@ -168,8 +168,8 @@ Example: ## Documenting functions, user-defined types, and callbacks Functions, types, and callbacks can be documented using the `-doc` attribute. -Each entry should start with a short paragraph describing the purpose of entity, -and then go into greater detail in needed. +Each entry should start with a short paragraph describing the purpose of the entity, +and then go into greater detail if needed. It is not recommended to include images or diagrams in this documentation as it is used by IDEs and `\c:h/1` to show the documentation to the user. @@ -204,13 +204,13 @@ Examples in documentation can be tested using `m:ct_doctest`. There are four reserved metadata keys for `-doc`: -- `since => unicode:chardata()` - Shows which version of the application the - module was added. +- `since => unicode:chardata()` - Shows in which version of the application the + function, type, or callback was added. - `deprecated => unicode:chardata()` - Shows a text in the documentation explaining that it is deprecated and what to use instead. The compiler will automatically insert this key if there is a `-deprecated` attribute marking a function as deprecated. -- `group => unicode:chardata()` - A group that the function, type or callback belongs to. +- `group => unicode:chardata()` - A group that the function, type, or callback belongs to. It allows tooling, such as shell autocompletion and documentation generators, to list all entries within the same group together, often using the group name as an indicator. - `equiv => unicode:chardata() | F/A | F(...)` - Notes that this function is equivalent to @@ -242,7 +242,7 @@ There are four reserved metadata keys for `-doc`: ### Doc signatures The doc signature is a short text shown to describe the function and its arguments. -By default it is determined by looking at the names of the arguments in the +By default, it is determined by looking at the names of the arguments in the `-spec` or function. For example: ```erlang @@ -272,7 +272,7 @@ specification. For example: ``` If it is not possible to "easily" figure out a nice signature from the code, the -MFA syntax is used instead. For example: `add/2`, `number/1`, `increment/1` +MFA syntax is used instead. For example: `add/2`, `number/1`, `increment/1`. It is possible to supply a custom signature by placing it as the first line of the `-doc` attribute. The provided signature must be in the form of a function @@ -287,7 +287,7 @@ Adds two numbers. add(A, B) -> A + B. ``` -Will create the signature `add(One, Two)`. The signature will be removed from the +This will create the signature `add(One, Two)`. The signature will be removed from the documentation string, so in the example above only the text `"Adds two numbers"` will be part of the documentation. This works for functions, types, and callbacks. @@ -302,7 +302,7 @@ inline code segment that looks like an MFA. For example: ``` will create a link to the `sub/2` function in the current module if it exists. -One can also use `` `sub/2` ``as the link target. For example: +One can also use `` `sub/2` `` as the link target. For example: ```erlang -doc "See [subtract](`sub/2`) for more details". @@ -321,7 +321,7 @@ See [subtract][1] for more details The above examples result in the same link being created. -The link can also other entities: +The link can also point to other entities: - `remote functions` - Use `module:function/arity` syntax. @@ -331,7 +331,7 @@ Example: -doc "See `arith:sub/2` for more details". ``` -- `modules` - Write the module with a `m` prefix. Use anchors to jump to a +- `modules` - Write the module with an `m` prefix. Use anchors to jump to a specific place in the module. Example: @@ -341,7 +341,7 @@ Example: -doc "See `m:arith#anchor` for more details". ``` -- `types` - Use the same syntax as for local/remote function but add a `t` +- `types` - Use the same syntax as for local/remote functions but add a `t` prefix. Example: @@ -351,7 +351,7 @@ Example: -doc "See `t:arith:number/0` for more details". ``` -- `callbacks` - Use the same syntax as for local/remote function but add a `c` +- `callbacks` - Use the same syntax as for local/remote functions but add a `c` prefix. Example: @@ -361,9 +361,9 @@ Example: -doc "See `c:arith:increment/0` for more details". ``` -- `extra pages` - For extra pages in the current application use a normal link, +- `extra pages` - For extra pages in the current application, use a normal link, for example "`[release notes](notes.md)`". For extra pages in another - application use the `e` prefix and state which application the page belongs + application, use the `e` prefix and state which application the page belongs to. One can also use anchors to jump to a specific place in the page. Example: @@ -377,13 +377,13 @@ Example: An Erlang `m:application` normally consists of various public and private modules. That is, modules that should be used by other applications and modules -that should not. By default all modules in an application are visible, but by -setting `-moduledoc false.` specific modules can be hidden from being listed as +that should not. By default, all modules in an application are visible, but by +setting `-moduledoc false.`, specific modules can be hidden from being listed as part of the available API. An Erlang [module](modules.md) consists of public and private functions and type attributes. By default, all exported functions, exported types and callbacks are -considered visible and part of the modules public API. In addition, any +considered visible and part of the module's public API. In addition, any non-exported type that is referred to by any other visible type attribute is also visible, but not considered to be part of the public API. For example: @@ -395,12 +395,12 @@ also visible, but not considered to be part of the public API. For example: example() -> one. ``` -in the above code, the function `example/0` is exported and it referenced the -un-exported type `private/0`. Therefore both `example/0` and `private/0` will be +In the code above, the function `example/0` is exported and references the +unexported type `private/0`. Therefore both `example/0` and `private/0` will be marked as visible. The `private/0` type will have the metadata field `exported` set to `false` to show that it is not part of the public API. -If you want to make a visible entity hidden you need to set the `-doc` attribute +If you want to make a visible entity hidden, you need to set the `-doc` attribute to `false`. Let us revisit our previous example: ```erlang @@ -449,7 +449,7 @@ the shell built-in command [`h/1`](`\\c:h/1`). For example: documentation from Markdown. The simplest way is by using the [rebar3_ex_doc](https://hexdocs.pm/rebar3_ex_doc) plugin. To set up a rebar3 project to use [ExDoc](https://hexdocs.pm/ex_doc/) to generate -documentation add the following to your `rebar3.config`. +documentation, add the following to your `rebar3.config`. ```erlang %% Enable the plugin @@ -462,15 +462,15 @@ documentation add the following to your `rebar3.config`. ]}. ``` -When configured you can run `rebar3 ex_doc` to generate the -documentation to `doc/index.html`. For more details and options see +When configured, you can run `rebar3 ex_doc` to generate the +documentation to `doc/index.html`. For more details and options, see the [rebar3_ex_doc](https://hexdocs.pm/rebar3_ex_doc) documentation. You can also download the [release escript bundle](https://github.com/elixir/ex_doc/releases/latest) from -github and run it from the command line. The documentation for using the escript +GitHub and run it from the command line. The documentation for using the escript is found by running `ex_doc --help`. If you are writing documentation that will be using -[ExDoc](https://hexdocs.pm/ex_doc/) to generate HTML/ePub it is highly +[ExDoc](https://hexdocs.pm/ex_doc/) to generate HTML/ePub, it is highly recommended to read its documentation. diff --git a/system/doc/reference_manual/errors.md b/system/doc/reference_manual/errors.md index 86812b8efa60..7adba242b99b 100644 --- a/system/doc/reference_manual/errors.md +++ b/system/doc/reference_manual/errors.md @@ -39,7 +39,7 @@ Errors can roughly be divided into four different types: [`error(Reason)`](`erlang:error/1`). Run-time errors are exceptions of class `error`. -- **[](){: #generated-errors } Generated errors** +- **[](){: #generated-errors } Generated errors** - When the code itself calls [`exit/1`](`erlang:exit/1`) or [`throw/1`](`erlang:throw/1`). Generated errors are exceptions of class `exit` or `throw`. @@ -47,7 +47,7 @@ Errors can roughly be divided into four different types: When an exception occurs in Erlang, execution of the process that evaluated the erroneous expression is stopped. This is referred to as a _failure_, that execution or evaluation _fails_, or that the process _fails_, _terminates_, or -_exits_. Notice that a process can terminate/exit for other reasons than a +_exits_. Notice that a process can terminate/exit for reasons other than a failure. A process that terminates emits an _exit signal_ with an _exit reason_ that @@ -96,9 +96,9 @@ caught by a `catch`. Example: [](){: #stacktrace } -### The call-stack back trace (stacktrace) +### The call-stack backtrace (stacktrace) -The stack back-trace ([_stacktrace_](`t:erlang:stacktrace/0`)) is a list that +The stack backtrace ([_stacktrace_](`t:erlang:stacktrace/0`)) is a list that contains `{Module, Function, Arity, ExtraInfo}` and/or `{Fun, Arity, ExtraInfo}` tuples. The field `Arity` in the tuple can be the argument list of that function call instead of an arity integer, depending on the exception. @@ -131,7 +131,7 @@ items can occur: > certain order or contain specific items to fail. > > The only exception to this rule is the class `error` with the reason `undef` -> which is guaranteed to include the `Module`, `Function` and `Arity` of the +> which is guaranteed to include the `Module`, `Function`, and `Arity` of the > attempted function as the first stacktrace entry. ## Handling of Run-time Errors in Erlang @@ -155,11 +155,11 @@ When a run-time error occurs, that is an exception of class `error`. The exit reason is a tuple `{Reason,Stack}`, where `Reason` is a term indicating the type of error: -- **`badarg`** - Bad argument. The argument is of wrong data type, or +- **`badarg`** - Bad argument. The argument is of a wrong data type, or is otherwise badly formed. - **`badarith`** - An argument for an arithmetic expression was not numeric, - or the expression does not evaluate to finite number. + or the expression does not evaluate to a finite number. - **`{badmatch,V}`** - Evaluation of a match expression failed. The value `V` did not match. @@ -180,24 +180,24 @@ of error: - **`undef`** - The function cannot be found when evaluating a function call. -- **`{badfun,F}`** - `F` was expected to a be a fun, but is not. +- **`{badfun,F}`** - `F` was expected to be a fun, but is not. - **`{badarity,{Fun,Args}}`** - A fun is applied to the wrong number of arguments. - **`timeout_value`** - The timeout value in a `receive...after` - expression is evaluated to something else than an integer or + expression is evaluated to something other than an integer or `infinity`. -- **`noproc`** - Trying to create [link](`link/1`) or +- **`noproc`** - Trying to create a [link](`link/1`) or [monitor](`monitor/2`) to a non-existing process or port. - **`noconnection`** - A link or monitor to a remote process was broken because a connection between the nodes could not be established or was severed. -- **`{nocatch,V}`** - Trying to evaluate a `throw `outside a - `catch`. `V` is the thrown term. +- **`{nocatch,V}`** - Trying to evaluate a `throw` outside the scope of a +`catch` or `try`/`catch`. `V` is the thrown term. - **`system_limit`** - A system limit has been reached. See [System Limits in the Efficiency Guide](`e:system:system_limits.md`) diff --git a/system/doc/reference_manual/expressions.md b/system/doc/reference_manual/expressions.md index ce860fa87621..2ccad1868c6e 100644 --- a/system/doc/reference_manual/expressions.md +++ b/system/doc/reference_manual/expressions.md @@ -48,7 +48,7 @@ wrong type causes a `badarg` runtime error. ## Terms -The simplest form of expression is a term, that is one of +The simplest form of expression is a term, that is, one of `t:integer/0`, `t:float/0`, `t:atom/0`, `t:string/0`, `t:list/0`, `t:map/0`, or `t:tuple/0`. The return value is the term itself. @@ -130,7 +130,7 @@ an `if`, `case`, or `receive` expression must be bound in all branches to have a value outside the expression. Otherwise they are regarded as unsafe outside the expression. -For the `try` expression variable scoping is limited so that variables bound in +For the `try` expression, variable scoping is limited so that variables bound in the expression are always unsafe outside the expression. ## Patterns @@ -204,7 +204,7 @@ An arithmetic expression can be used within a pattern if it meets both of the following two conditions: - It uses only numeric or bitwise operators. -- Its value can be evaluated to a constant when complied. +- Its value can be evaluated to a constant when compiled. _Example:_ @@ -260,14 +260,14 @@ PatternN = Temporary, . ., Pattern2 = Temporary, -Pattern = Temporary +Pattern1 = Temporary ``` ## The Match Operator and the Compound Pattern Operator > #### Note {: .info } > -> This is an advanced section, which references to topics not yet introduced. It +> This is an advanced section, which refers to topics not yet introduced. It > can safely be skipped on a first reading. The `=` character is used to denote two similar but distinct operators: the @@ -322,14 +322,14 @@ first. That is, `M` is matched against `#{key := Key}`, and then the value of `M` is matched against pattern `#{Key := Value}`. That is the same evaluation order as in _2_; therefore, the parentheses are redundant. -In the expression at prompt `4>` the expression `M` is matched against a pattern +In the expression at prompt `4>`, the expression `M` is matched against a pattern inside parentheses. Since the construct inside the parentheses is a pattern, the `=` that separates the two patterns is the compound pattern operator (_not_ the match operator). The match fails because the two sub patterns are matched at the same time, and the variable `Key` is therefore not bound when matching against pattern `#{Key := Value}`. -In the expression at prompt `5>` the expressions inside the +In the expression at prompt `5>`, the expressions inside the [block expression](expressions.md#block-expressions) are evaluated first, binding variable `Y` and creating a binary. The binary is then matched against pattern `<>` using the value of `Y` as the size of the segment. @@ -337,8 +337,8 @@ pattern `<>` using the value of `Y` as the size of the segment. ## Function Calls ``` -ExprF(Expr1,...,ExprN) ExprM:ExprF(Expr1,...,ExprN) +ExprF(Expr1,...,ExprN) ``` In the first form of function calls, `ExprM:ExprF(Expr1,...,ExprN)`, each of @@ -383,7 +383,7 @@ Fun1(3). 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 -[Compilation and Code Loading ](code_loading.md)and +[Compilation and Code Loading](code_loading.md) and [Function Evaluation](ref_man_functions.md#eval). ### Local Function Names Clashing With Auto-Imported BIFs @@ -391,7 +391,7 @@ latest version of the module. See 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 confusion, there is a compiler directive -available, `-compile({no_auto_import,[F/A]})`, that makes a BIF not being +available, `-compile({no_auto_import,[F/A]})`, that prevents a BIF from being auto-imported. In certain situations, such a compile-directive is mandatory. > #### Change {: .info } @@ -400,9 +400,9 @@ auto-imported. In certain situations, such a compile-directive is mandatory. > 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 > 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. +> auto-imported BIFs silently change the behavior of old code. -However, to avoid that old (pre R14) code changed its behavior when compiled +However, to avoid old (pre R14) code changing its behavior when compiled with Erlang/OTP version R14A or later, the following restriction applies: If you override the name of a BIF that was auto-imported in OTP versions prior to R14A (ERTS version 5.8) and have an implicitly qualified call to that function in @@ -447,7 +447,7 @@ f(X) -> 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 -`-compile({no_auto_import,[F/A])` directive is not used, the compiler issues a +`-compile({no_auto_import,[F/A]})` directive is not used, the compiler issues a warning whenever the function is called in the module using the implicitly qualified function name. @@ -525,7 +525,7 @@ is_valid_signal(Signal) -> > #### Change {: .info } > > The `maybe` [feature](`e:system:features.md#features`) was introduced -> in Erlang/OTP 25. Starting from Erlang/OTP 27 is is enabled by default. +> in Erlang/OTP 25. Starting from Erlang/OTP 27, it is enabled by default. ``` maybe @@ -641,7 +641,7 @@ end The `else` clauses translate the failing value from the conditional match operators to the value `error`. If the failing value is not one of the -recognized values, a `else_clause` run-time error occurs. +recognized values, an `else_clause` run-time error occurs. ## Send @@ -677,13 +677,13 @@ receive end ``` -The `receive` expression searches for a message in the message queue that match +The `receive` expression searches for a message in the message queue that matches one of the patterns in the clauses of the `receive` expression. The patterns in -the clauses is matched against a message from top to bottom. The first message, -from the start of the message queue, that matches will be selected. Messages are +the clauses are matched against a message from top to bottom. The first message +from the start of the message queue that matches will be selected. Messages are normally [enqueued in the message queue](ref_man_processes.md#message-queue-order) in -order they were received. However, +the order they were received. However, if [reception of priority messages](ref_man_processes.md#enable-prio-msg-recv) has been enabled by the receiving process, this is not always the case. When a match succeeds and the optional guard sequence `GuardSeq` is true, the matching @@ -699,17 +699,17 @@ sequence. [](){: #selective-receive-warning } > #### Warning {: .warning } > The time complexity of a `receive` expression is `O(N)` where `N` corresponds -> to the amount of messages preceeding the matching message in the message queue. +> to the number of messages preceding the matching message in the message queue. > That is, when the combination of patterns of a `receive` expression only match > specific messages and the message queue is huge, executing such a `receive` > expression might become very expensive. > > One type of `receive` expressions matching on only specific patterns can, -> however, be optimized by the compiler and runtime system. This in the scenario -> where you create a [*reference*](`e:system:data_types.md#reference`) and +> however, be optimized by the compiler and runtime system, namely when +> you create a [*reference*](`e:system:data_types.md#reference`) and > match on it in all clauses of a `receive` expression *close* to where the -> reference was created. In this case only the amount of messages received after -> the reference was created needs to be inspected. For more information see the +> reference was created. In this case, only the messages received after +> the reference was created need to be inspected. For more information see the > [*Fetching Received Messages* section of the *Efficiency Guide*](`e:system:eff_guide_processes.md#fetching-received-messages`). _Example:_ @@ -746,7 +746,7 @@ has arrived within `ExprT` milliseconds, then `BodyT` is evaluated instead. The return value of `BodyT` then becomes the return value of the `receive...after` expression. `ExprT` is to evaluate to an integer, or the atom `infinity`. The allowed integer range is from 0 to 4294967295, that is, the longest possible -timeout is almost 50 days. With a zero value the timeout occurs immediately if +timeout is almost 50 days. With a zero value, the timeout occurs immediately if there is no matching message in the message queue. > #### Warning {: .warning } @@ -755,8 +755,8 @@ there is no matching message in the message queue. > *not* necessarily the case. If the patterns in the clauses of the `receive` > expression only match specific messages and no such messages exist in the > message queue, the whole message queue needs to be inspected before the -> timeout can occur. That is, the same apply as in -> [the warning above](#selective-receive-warning). +> timeout can occur. That is, the same caveat as in +> [the warning above](#selective-receive-warning) applies. The atom `infinity` will make the process wait indefinitely for a matching message. This is the same as not using a timeout. It can be useful for timeout @@ -810,7 +810,7 @@ timer(Pid) -> For more information on timers in Erlang in general, see the [*Timers*](`e:erts:time_correction.md#timers`) section of the [*Time and Time Correction in Erlang*](`e:erts:time_correction.md`) -ERTS User's guide. +ERTS User's Guide. ## Term Comparisons @@ -840,15 +840,15 @@ number < atom < reference < fun < port < pid < tuple < map < nil < list < bit st `nil` in the previous expression represents the empty list (`[]`), which is regarded as a separate type from `t:list/0`. That is why `nil < list`. -Lists are compared element by element. Tuples are ordered by size, two tuples +Lists are compared element by element. Tuples are ordered by size; two tuples with the same size are compared element by element. Bit strings are compared bit by bit. If one bit string is a prefix of the other, the shorter bit string is considered smaller. -Maps are ordered by size, two maps with the same size are compared by keys in -ascending term order and then by values in key order. In maps key order integers -types are considered less than floats types. +Maps are ordered by size; two maps with the same size are compared by keys in +ascending term order and then by values in key order. In map key order, integer +types are considered less than float types. Atoms are compared using their string value, codepoint by codepoint. @@ -936,7 +936,7 @@ Expr1 op Expr2 | `+` | Addition | Number | | `-` | Subtraction | Number | | `*` | Multiplication | Number | -| `/` | Floating point division | Number | +| `/` | Floating-point division | Number | | `bnot` | Unary bitwise NOT | Integer | | `div` | Integer division | Integer | | `rem` | Integer remainder of X/Y | Integer | @@ -1057,7 +1057,7 @@ all(_, []) -> > #### Change {: .info } > > Before Erlang/OTP R13A, `Expr2` was required to evaluate to a Boolean value, -> and as consequence, `andalso` and `orelse` were **not** tail-recursive. +> and as a consequence, `andalso` and `orelse` were **not** tail-recursive. ## List Operations @@ -1143,7 +1143,7 @@ two matching keys. ### Updating Maps -Updating a map has a similar syntax as constructing it. +Updating a map has a syntax similar to constructing it. 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: @@ -1152,7 +1152,7 @@ defining the keys to be updated and their respective values: M#{K => V} ``` -Here `M` is a term of type map and `K` and `V` are any expression. +Here `M` is a term of type map, and `K` and `V` can be any expression. If key `K` does not match any existing key in the map, a new association is created from key `K` to value `V`. @@ -1169,7 +1169,7 @@ To only update an existing value, the following syntax is used: M#{K := V} ``` -Here `M` is a term of type map, `V` is an expression and `K` is an expression +Here `M` is a term of type map, `V` is an expression, and `K` is an expression that evaluates to an existing key in `M`. If key `K` does not match any existing keys in map `M`, an exception of type @@ -1186,7 +1186,7 @@ M0 = #{}, M1 = M0#{a => 0}, 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`. +M4 = M3#{a := 2, b := 3}. % 'a' and 'b' were added in `M1` and `M2`. ``` Here `M0` is any map. It follows that `M1` through `M4` are maps as well. @@ -1251,17 +1251,17 @@ Similarly, multiple values from the map can be matched: Here keys `K1` through `Kn` are any expressions with literals or bound variables. If all key expressions evaluate successfully and all keys -exist in map `M`, all variables in `V1 .. Vn` is matched to the +exist in map `M`, all variables in `V1 .. Vn` are matched to the associated values of their respective keys. -If the matching conditions are not met the match fails. +If the matching conditions are not met, the match fails. Note that when matching a map, only the `:=` operator (not the `=>`) is allowed as a delimiter for the associations. The order in which keys are declared in matching has no relevance. -Duplicate keys are allowed in matching and match each pattern associated to the +Duplicate keys are allowed in matching and match each pattern associated with the keys: ``` @@ -1274,7 +1274,7 @@ The empty map literal (`#{}`) matches any map when used as a pattern: #{} = Expr ``` -This expression matches if the expression `Expr` is of type map, otherwise it +This expression matches if the expression `Expr` is of type map; otherwise, it fails with an exception `badmatch`. Here the key to be retrieved is constructed from an expression: @@ -1287,7 +1287,7 @@ Here the key to be retrieved is constructed from an expression: #### Matching Syntax -Matching of literals as keys are allowed in function heads: +Matching of literals as keys is allowed in function heads: ``` %% only start if not_started @@ -1386,7 +1386,7 @@ bytes where each byte's value is its sequence number: ``` Bit strings are a later generalization of binaries, so many texts and much -information about binaries apply just as well for bit strings. +information about binaries apply just as well to bit strings. **Example:** @@ -1451,7 +1451,7 @@ When constructing bit strings, if the size of a float segment is too small to contain the representation of the given float value, an exception is raised. When matching bit strings, matching of float segments fails if the bits of the -segment does not contain the representation of a finite floating point value. +segment do not contain the representation of a finite floating-point value. ### Binary segments @@ -1531,7 +1531,7 @@ constructed binary must be at least as large as the size of the binary segment. ### Unicode segments -The types `utf8`, `utf16`, and `utf32` specifies encoding/decoding of the +The types `utf8`, `utf16`, and `utf32` specify encoding/decoding of the *Unicode Transformation Format*s [UTF-8](https://en.wikipedia.org/wiki/UTF-8), [UTF-16](https://en.wikipedia.org/wiki/UTF-16), and [UTF-32](https://en.wikipedia.org/wiki/UTF-32), respectively. @@ -1606,7 +1606,7 @@ _Examples:_ Notice that bit string patterns cannot be nested. Notice also that "`B=<<1>>`" is interpreted as "`B =< <1>>`" which is a syntax -error. The correct way is to write a space after `=`: "`B = <<1>>`. +error. The correct way is to write a space after `=`: `B = <<1>>`. More examples are provided in [Programming Examples](`e:system:bit_syntax.md`). @@ -1664,7 +1664,7 @@ specify an existing local function. The expression is syntactic sugar for: fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end ``` -In `Module:Name/Arity`, `Module`, and `Name` are atoms and `Arity` is an +In `Module:Name/Arity`, `Module` and `Name` are atoms and `Arity` is an integer. `Module`, `Name`, and `Arity` can also be variables. A fun defined in this way refers to the function `Name` with arity `Arity` in the _latest_ version of module `Module`. A fun defined in this way is not dependent on the @@ -1692,7 +1692,7 @@ exception: - **`exit`** (the code called [`exit(Term)`](`exit/1`)) - `{'EXIT',Term}` is returned. -- **`throw`** (the code called [`throw(Term)`](`throw/1`)): `Term` is returned. +- **`throw`** (the code called [`throw(Term)`](`throw/1`)) - `Term` is returned. `Reason` depends on the type of error that occurred, and `Stack` is the stack of recent function calls, see [Exit Reasons](errors.md#exit_reasons). @@ -1757,7 +1757,7 @@ possibility to: - Distinguish between different exception classes. - Choose to handle only the desired ones. -- Passing the others on to an enclosing `try` or `catch`, or to default error +- Pass the others on to an enclosing `try` or `catch`, or to default error handling. Notice that although the keyword `catch` is used in the `try` expression, there @@ -1870,8 +1870,8 @@ end try Exprs catch - ExpressionPattern -> - ExpressionBody + ExceptionPattern -> + ExceptionBody after AfterBody end @@ -1912,10 +1912,10 @@ Variables bound just after the `try` keyword are: - unsafe in both the `catch` and `after` sections, as well as after the whole construct -Variables bound in `of` section are: +Variables bound in the `of` section are: - unbound in the `catch` section -- unsafe in both the `after` section, as well as after the whole construct +- unsafe in the `after` section, as well as after the whole construct Variables bound in the `catch` section are unsafe in the `after` section, as well as after the whole construct. @@ -1994,7 +1994,7 @@ is either a **generator** or a **filter**. > Map comprehensions and map generators were introduced in Erlang/OTP 26. There are four kinds of generators. Three of them have a relaxed and a strict -variant. The fourth kind of generator, zip generator, is composed by two or +variant. The fourth kind of generator, zip generator, is composed of two or more non-zip generators. > #### Change {: .info } @@ -2002,7 +2002,7 @@ more non-zip generators. > Strict generators and zip generators were introduced in Erlang/OTP 28. > Using strict generators is a better practice when either strict or relaxed > generators work. More details are in -> [Programming Examples.](`e:system:list_comprehensions.md`) +> [Programming Examples](`e:system:list_comprehensions.md`). A _list generator_ has the following syntax for relaxed: @@ -2045,7 +2045,7 @@ and strict variant: KeyPattern := ValuePattern <:- MapExpression ``` -where `MapExpr` is an expression that evaluates to a map, or a map iterator +where `MapExpression` is an expression that evaluates to a map or a map iterator obtained by calling `maps:iterator/1` or `maps:iterator/2`. A _zip generator_ has the following syntax: @@ -2178,7 +2178,7 @@ Filtering out non-matching elements from two lists. ``` More examples are provided in -[Programming Examples.](`e:system:list_comprehensions.md`) +[Programming Examples](`e:system:list_comprehensions.md`). When there are no generators, a comprehension returns either a term constructed from a single element (the result of evaluating `Expr`) if all filters are true, @@ -2258,8 +2258,8 @@ evaluation of a guard expression must be guaranteed to be free of side effects. Valid guard expressions are the following: - Variables -- Constants (atoms, integer, floats, lists, tuples, records, binaries, and maps) -- Expressions that construct atoms, integer, floats, lists, tuples, records, +- Constants (atoms, integers, floats, lists, tuples, records, binaries, and maps) +- Expressions that construct atoms, integers, floats, lists, tuples, records, binaries, and maps - Expressions that update a map - The record expressions `Expr#Name.Field` and `#Name.Field` diff --git a/system/doc/reference_manual/features.md b/system/doc/reference_manual/features.md index 39092aeed383..7a6c791b3a13 100644 --- a/system/doc/reference_manual/features.md +++ b/system/doc/reference_manual/features.md @@ -22,17 +22,17 @@ limitations under the License. # Features [](){: #features } Introduced in OTP 25, Erlang has the concept of selectable -features. A feature can change, add or remove behaviour of the language and/or +features. A feature can change, add, or remove behaviour of the language and/or runtime system. Examples can include: - Adding new syntactical constructs to the language -- Change the semantics of an existing construct -- Change the behaviour of some runtime aspect +- Changing the semantics of an existing construct +- Changing the behaviour of some runtime aspect -A feature will start out with a status of experimental part of OTP, making it -possible to try out for users and give feedback. The possibility to try out -features is enabled by options to the compiler, directives in a module and -options to the runtime system. Even when a feature is not experimental it will +A feature will start out as an experimental part of OTP, making it +possible for users to try it out and give feedback. The possibility to try out +features is enabled by options to the compiler, directives in a module, and +options to the runtime system. Even when a feature is not experimental, it will still be possible to enable or disable it. This makes it possible to adapt a code base at a suitable pace instead of being forced when changing to a new release. @@ -44,11 +44,11 @@ of OTP or rejected, being removed and no longer selectable. A feature is in one of four possible states: -- **Experimental** - The initial state, is meant for trying out and collecting +- **Experimental** - The initial state is meant for trying out and collecting feedback. The feature can be enabled but is disabled by default. - **Approved** - The feature has been finalised and is now part of OTP. By - default it is enabled, but can be disabled. + default, it is enabled, but can be disabled. - **Permanent** - The feature is now a permanent part of OTP. It can no longer be disabled. @@ -84,7 +84,7 @@ compilation. This can be done in a number of different ways: - **Options to `erlc`** - Options [`-enable-feature`](`e:erts:erlc_cmd.md#enable-feature`) and [`-disable-feature`](`e:erts:erlc_cmd.md#disable-feature`) can be used to - enable or disable individal features. + enable or disable individual features. - **Compiler options** - The compiler option [`{feature, , enable|disable}`](`m:compile#feature-option`) can be @@ -101,18 +101,18 @@ compilation. This can be done in a number of different ways: > necessary to also enable the feature in the runtime. This was done using > option [`-enable-feature`](`e:erts:erl_cmd.md#enable-feature`) to `erl`. This > requirement was removed in Erlang/OTP 26. However, if you want to use features -> directly in shell, you still need to enable them in the runtime. +> directly in the shell, you still need to enable them in the runtime. ## Preprocessor Additions To allow for conditional compilation during transitioning of a code base and/or trying out experimental features -[feature](`e:system:macros.md#predefined-macros`) `predefined macros` +[feature predefined macros](`e:system:macros.md#predefined-macros`) `?FEATURE_AVAILABLE(Feature)` and `?FEATURE_ENABLED(Feature)` are available. ## Information about Existing Features -The module `erl_features` `m:erl_features` exports a number of functions that +The module `m:erl_features` exports a number of functions that can be used to obtain information about current features as well as the features used when compiling a module. diff --git a/system/doc/reference_manual/macros.md b/system/doc/reference_manual/macros.md index e300086cd9a7..0cb3d887104d 100644 --- a/system/doc/reference_manual/macros.md +++ b/system/doc/reference_manual/macros.md @@ -195,7 +195,7 @@ The following macros are predefined: > > The `?FEATURE_ENABLED()` macro was introduced in Erlang/OTP 25. -## Macros Overloading +## Macro Overloading It is possible to overload macros, except for predefined macros. An overloaded macro has more than one definition, each with a different number of arguments. @@ -242,7 +242,7 @@ f() -> ## Removing a macro definition -A definition of macro can be removed as follows: +A definition of a macro can be removed as follows: ```erlang -undef(Macro). @@ -281,7 +281,7 @@ Syntactically, the `Condition` in `if` and `elif` must be a a `case` expression) result in a compilation error. As opposed to the standard guard expressions, an expression in an `if` and -`elif` also supports calling the psuedo-function `defined(Name)`, which tests +`elif` also supports calling the pseudo-function `defined(Name)`, which tests whether the `Name` argument is the name of a previously defined macro. `defined(Name)` evaluates to `true` if the macro is defined and `false` otherwise. An attempt to call other functions results in a compilation error. @@ -313,7 +313,7 @@ or {ok,m} ``` -`?LOG(Arg)` is then expanded to a call to `io:format/2` and provide the user +`?LOG(Arg)` is then expanded to a call to `io:format/2` and provides the user with some simple trace output. _Example:_ @@ -321,10 +321,10 @@ _Example:_ ```erlang -module(m) ... --if(?OTP_RELEASE >= 25). -%% Code that will work in OTP 25 or higher --elif(?OTP_RELEASE >= 26). +-if(?OTP_RELEASE >= 26). %% Code that will work in OTP 26 or higher +-elif(?OTP_RELEASE >= 25). +%% Code that will work in OTP 25 or higher -else. %% Code that will work in OTP 24 or lower. -endif. diff --git a/system/doc/reference_manual/modules.md b/system/doc/reference_manual/modules.md index daffd56e13d7..18292fe7bd15 100644 --- a/system/doc/reference_manual/modules.md +++ b/system/doc/reference_manual/modules.md @@ -65,17 +65,17 @@ but user-defined module attributes must have arity one. ### Pre-Defined Module Attributes -Pre-defined module attributes is to be placed before any function declaration. +Pre-defined module attributes are to be placed before any function declaration. - **`-module(Module).`** - Module declaration, defining the name of the module. - The name `Module`, an atom, is to be same as the file name minus the extension + The name `Module`, an atom, is to be the same as the file name minus the extension `.erl`. Otherwise [code loading](code_loading.md#loading) does not work as intended. This attribute is to be specified first and is the only mandatory attribute. - **`-export(Functions).`** - Exported functions. Specifies which of the - functions, defined within the module, that are visible from outside the + functions, defined within the module, are visible from outside the module. `Functions` is a list `[Name1/Arity1, ..., NameN/ArityN]`, where each `NameI` @@ -85,7 +85,7 @@ Pre-defined module attributes is to be placed before any function declaration. way as local functions, that is, without any module prefix. `Module`, an atom, specifies which module to import functions from. - `Functions` is a list similar as for `export`. + `Functions` is a list similar to that for `export`. - **`-moduledoc(Documentation).` or `-moduledoc Documentation.`** - The user documentation for this module. The allowed values for `Documentation` are the @@ -109,14 +109,14 @@ Pre-defined module attributes is to be placed before any function declaration. [Running a Function When a Module is Loaded](code_loading.md#on_load). - **`-nifs(Functions).`{: #nifs_attribute }** - Specifies which of the - functions, defined within the module, that may be loaded as NIFs with + functions, defined within the module, may be loaded as NIFs with `erlang:load_nif/2`. `Functions` is a list `[Name1/Arity1, ..., NameN/ArityN]`, where each `NameI` is an atom and `ArityI` an integer. - While not strictly necessary, it is recommended to use `-nifs()` attribute in - any module that load NIFs, to allow the compiler to make better decisions + While not strictly necessary, it is recommended to use the `-nifs()` attribute in + any module that loads NIFs, to allow the compiler to make better decisions regarding optimizations. There is no need to add `-nifs([])` in modules that do not load NIFs. The lack @@ -207,7 +207,7 @@ which the source program is produced. ### Types and function specifications -A similar syntax as for module attributes is used for specifying types and +A syntax similar to that for module attributes is used for specifying types and function specifications: ```erlang @@ -231,8 +231,8 @@ for a function/type/callback: example() -> ok. ``` -The attribute should be placed just before the entity it documents.The -parenthesis are optional around `Documentation`. The allowed values for +The attribute should be placed just before the entity it documents. The +parentheses are optional around `Documentation`. The allowed values for `Documentation` are: - **[literal string](data_types.md#string) or @@ -307,8 +307,8 @@ When called, these functions retrieve information about the module. ### module_info/0 The `module_info/0` function in each module returns a list of -`{Key,Value}` tuples with information about the module. At the time -writing, the list contain tuples having the following `Key`s: +`{Key,Value}` tuples with information about the module. At the time of this +writing, the list contains tuples having the following `Key`s: `module`, `attributes`, `compile`, `exports`, and `md5`. The order and number of tuples may change without prior notice. diff --git a/system/doc/reference_manual/nominals.md b/system/doc/reference_manual/nominals.md index 25827d46510b..53efd9af6ce0 100644 --- a/system/doc/reference_manual/nominals.md +++ b/system/doc/reference_manual/nominals.md @@ -117,7 +117,7 @@ compatible: when one is derived from the other. For nominal types `s()` and In both cases, `s()` and `t()` are compatible nominal types even though they have different names. Defining them in different modules does not affect -compatiblity. +compatibility. In summary, nominal type-checking rules are as follows: diff --git a/system/doc/reference_manual/opaques.md b/system/doc/reference_manual/opaques.md index 3851c106cef2..944da40452c1 100644 --- a/system/doc/reference_manual/opaques.md +++ b/system/doc/reference_manual/opaques.md @@ -70,12 +70,12 @@ end. recommendations:** - Don't examine the underlying type using pattern-matching, guards, or functions - that reveal the type, such as [`tuple_size/1`](`tuple_size/1`) . One exception + that reveal the type, such as [`tuple_size/1`](`tuple_size/1`). One exception is that `=:=` and `=/=` can be used between two opaques with the same name, or between an opaque and `any()`, as those comparisons do not reveal underlying types. - Use functions provided by the module for working with the type. For - example, `sets` module provides `sets:new/0`, `sets:add_element/2`, + example, the `sets` module provides `sets:new/0`, `sets:add_element/2`, `sets:is_element/2`, and so on. - [`sets:set(a)`](`t:sets:set/1`) is a subtype of `sets:set(a | b)` and not the other way around. Generally, you can rely on the property that `the_opaque(T)` @@ -87,13 +87,13 @@ recommendations:** you must provide functions for constructing, querying, and deconstructing instances of your opaque type. For example, sets can be constructed with `sets:new/0`, `sets:from_list/1`, `sets:add_element/2`, queried with - `sets:is_element/2`, and deconstructed with`sets:to_list/1`. + `sets:is_element/2`, and deconstructed with `sets:to_list/1`. - Don't define an opaque with a type variable in parameter position. This breaks the normal and expected behavior that (for example) `my_type(a)` is a subtype - of `my_type(a | b)` + of `my_type(a | b)`. - Don't write case statements that can produce either an opaque or a non-opaque output. -- Add [specs](typespec.md) to exported functions that use the opaque type +- Add [specs](typespec.md) to exported functions that use the opaque type. > #### Change {: .info } > diff --git a/system/doc/reference_manual/ports.md b/system/doc/reference_manual/ports.md index aa0bae09b35c..7e31a3ba9f8d 100644 --- a/system/doc/reference_manual/ports.md +++ b/system/doc/reference_manual/ports.md @@ -52,7 +52,7 @@ driver_. > #### Warning {: .warning } > > An erroneous port driver causes the entire Erlang runtime system to leak -> memory, hang or crash. +> memory, hang, or crash. For information about port drivers, see: @@ -81,7 +81,7 @@ Valid values for N are 1, 2, or 4. If binaries are to be used instead of lists of bytes, the option `binary` must be included. The port owner `Pid` can communicate with the port `Port` by sending and -receiving messages. (In fact, any process can send the messages to the port, but +receiving messages. (In fact, any process can send messages to the port, but the port owner must be identified in the message). Messages sent to ports are delivered asynchronously. @@ -104,11 +104,11 @@ The following messages can be sent to a port: - **`{Pid,{connect,NewPid}}`** - Sets the port owner of `Port` to `NewPid`. Unless the port is already closed, the port replies - with`{Port,connected}` to the old port owner. Note that the old + with `{Port,connected}` to the old port owner. Note that the old port owner is still linked to the port, but the new port owner is not. -Here follows the possible messages that can be received from a port. They +Here follow the possible messages that can be received from a port. They are sent to the process that owns the port: - **`{Port,{data,Data}}`** - `Data` is received from the external program. @@ -129,7 +129,7 @@ can be used: - [`port_close(Port)`](`port_close/1`) - Closes the port. - [`port_connect(Port, NewPid)`](`port_connect/2`) - Sets the port - owner of `Port`to `NewPid`. The old port owner `Pid` stays linked to + owner of `Port` to `NewPid`. The old port owner `Pid` stays linked to the port and must call [`unlink(Port)`](`unlink/1`) if this is not desired. diff --git a/system/doc/reference_manual/ref_man_functions.md b/system/doc/reference_manual/ref_man_functions.md index e28ed80f3dd9..371f683d5bdb 100644 --- a/system/doc/reference_manual/ref_man_functions.md +++ b/system/doc/reference_manual/ref_man_functions.md @@ -133,7 +133,7 @@ and the body is evaluated: 1 ``` -Evaluation has succeed and `mod:fact(1)` returns 1. +Evaluation has succeeded and `mod:fact(1)` returns 1. If `mod:fact/1` is called with a negative number as argument, no clause head matches. A `function_clause` runtime error occurs. @@ -167,7 +167,7 @@ are also BIFs belonging to a few other modules, for example `m:lists` and `m:ets`. The most commonly used BIFs belonging to `m:erlang` are _auto-imported_. They do -not need to be prefixed with the module name. Which BIFs that are auto-imported +not need to be prefixed with the module name. Which BIFs are auto-imported is specified in the `m:erlang` module in ERTS. For example, standard-type conversion BIFs like `atom_to_list` and BIFs allowed in guards can be called without specifying the module name. diff --git a/system/doc/reference_manual/ref_man_processes.md b/system/doc/reference_manual/ref_man_processes.md index b0a17584eb77..12dedb15e41b 100644 --- a/system/doc/reference_manual/ref_man_processes.md +++ b/system/doc/reference_manual/ref_man_processes.md @@ -24,7 +24,7 @@ limitations under the License. ## Processes Erlang is designed for massive concurrency. Erlang processes are lightweight -(grow and shrink dynamically) with small memory footprint, fast to create and +(grow and shrink dynamically) with a small memory footprint, fast to create and terminate, and the scheduling overhead is low. ## Process Creation @@ -41,7 +41,7 @@ spawn(Module, Name, Args) -> pid() `spawn()` creates a new process and returns the pid. The new process starts executing in `Module:Name(Arg1,...,ArgN)` where the -arguments are the elements of the (possible empty) `Args` argument list. +arguments are the elements of the (possibly empty) `Args` argument list. There exist a number of different `spawn` BIFs: @@ -61,7 +61,7 @@ automatically unregistered if the process terminates: | ------------------------------------- | -------------------------------------------------------------------------------------- | | [`register(Name, Pid)`](`register/2`) | Associates the name `Name`, an atom, with the process `Pid`. | | `registered/0` | Returns a list of names that have been registered using [`register/2`](`register/2`). | -| [`whereis(Name)`](`whereis/1`) | Returns the pid registered under `Name`, or `undefined `if the name is not registered. | +| [`whereis(Name)`](`whereis/1`) | Returns the pid registered under `Name`, or `undefined` if the name is not registered. | _Table: Name Registration BIFs_ @@ -76,7 +76,7 @@ scenario. Using a process alias when sending the reply makes it possible for the receiver of the reply to prevent the reply from reaching its message queue if the operation times out or if the connection between the processes is lost. -A process alias can be used as identifier of the receiver when sending a message +A process alias can be used as an identifier of the receiver when sending a message using the [send operator (`!`)](expressions.md#send) or send BIFs such as `erlang:send/2`. As long as the process alias is active, messages will be delivered the same way as if the process identifier of the process that created @@ -103,7 +103,7 @@ deactivation of aliases. It is _not_ possible to: -- create an alias identifying another process than the caller. +- create an alias identifying a process other than the caller. - deactivate an alias unless it identifies the caller. - look up an alias. - look up the process identified by an alias. @@ -118,7 +118,7 @@ and distribution transparency. When a process terminates, it always terminates with an _exit reason_. The reason can be any term. -A process is said to terminate _normally_, if the exit reason is the atom +A process is said to terminate _normally_ if the exit reason is the atom `normal`. A process with no more code to execute terminates normally. A process terminates with an exit reason `{Reason,Stack}` when a run-time error @@ -133,8 +133,8 @@ A process can terminate itself by calling one of the following BIFs: The process then terminates with reason `Reason` for [`exit/1`](`exit/1`) or `{Reason,Stack}` for the others. -A process can also be terminated if it receives an exit signal with another exit -reason than `normal`, see [Error Handling](ref_man_processes.md#errors). +A process can also be terminated if it receives an exit signal with an exit +reason other than `normal`, see [Error Handling](ref_man_processes.md#errors). ## Signals @@ -225,7 +225,7 @@ been performed. - **`port_command`, `port_connect`, `port_close`** - Sent by a process to a port on the local node using the [send operator (`!`)](expressions.md#send), or by calling one of the [`send()`](`erlang:send/2`) BIFs. The signal is sent by - passing a term on the format `{Owner, {command, Data}}`, + passing a term of the format `{Owner, {command, Data}}`, `{Owner, {connect, Pid}}`, or `{Owner, close}` as message. - **`port_command_request`/`port_command_reply`, @@ -273,7 +273,7 @@ implementation details of the runtime system that you should _not_ rely on. As an example, many of the reply signals are ordinary message signals. When the operation is synchronous, the reply signals do not have to be message signals. The current implementation takes advantage of this and, depending on -the state of the system, use alternative ways of delivering the reply signals. +the state of the system, uses alternative ways of delivering the reply signals. The implementation of these reply signals may also, at any time, be changed to not use message signals where it previously did. @@ -297,8 +297,8 @@ the state of the receiving process. Actions taken for the most common signals: queue, the receiving process can fetch the message from the message queue using the [`receive`](expressions.md#receive) expression. -- **`link`, `unlink`** - Very simplified it can be viewed as updating process - local information about the link. A detailed description of the +- **`link`, `unlink`** - Very simplified, it can be viewed as updating process-local + information about the link. A detailed description of the [link protocol](`e:erts:erl_dist_protocol.md#link_protocol`) can be found in the _Distribution Protocol_ chapter of the _ERTS User's Guide_. @@ -309,18 +309,18 @@ the state of the receiving process. Actions taken for the most common signals: [_Receiving Exit Signals_](ref_man_processes.md#receiving_exit_signals) below gives more details on the action taken when an `exit` signal is received. -- **`monitor`, `demonitor`** - Update process local information about the +- **`monitor`, `demonitor`** - Update process-local information about the monitor. - **`down`, `change`** - Convert into a message if the corresponding monitor is still active; otherwise, drop the signal. If the signal is converted into a - message, it is also added the message queue. + message, it is also added to the message queue. - **`group_leader`** - Change the group leader of the process. -- **`spawn_reply`** - Convert into a message, or drop the signal depending on +- **`spawn_reply`** - Convert into a message or drop the signal, depending on the reply and how the `spawn_request` signal was configured. If the signal is - converted into a message it is also added to the message queue. For + converted into a message, it is also added to the message queue. For more information see the [`spawn_request()`](`erlang:spawn_request/5`) BIF. - **`alive_request`** - Schedule execution of the _is alive_ test. If the @@ -334,7 +334,7 @@ the state of the receiving process. Actions taken for the most common signals: `check_process_code_request`** - Schedule execution of the requested operation. The reply signal will be sent when the operation has been executed. -Note that some actions taken when a signal is received involves _scheduling_ +Note that some of the actions taken when a signal is received involve _scheduling_ further actions which will result in a reply signal when these scheduled actions have completed. This implies that the reply signals may be sent in a different order than the order of the incoming signals that triggered these operations. @@ -347,7 +347,7 @@ language. #### Adding Messages to the Message Queue When a message signal is received, the action taken is to add the message to the -message queue. The actions of other signals at receptions may also add messages +message queue. The actions of other signals, upon reception, may also add messages to the message queue ([see above](ref_man_processes.md#receiving-signals)). Unless the receiving process has enabled priority messages, all messages are added to the end of the message queue. In the case that the receiver has not @@ -360,7 +360,7 @@ language. [](){: #priority-messages } -As of OTP 28.0 a process may +As of OTP 28.0, a process may [enable reception of priority messages](ref_man_processes.md#enable-prio-msg-recv). If the receiving process has enabled priority messages, the receiver will at reception of a message signal, or another signal that is converted into a @@ -379,8 +379,8 @@ order in which the signals corresponding to the messages in the queue were received. However, the order of priority messages corresponds to the order in which those corresponding signals were received, and the order of ordinary messages corresponds to the order in which those corresponding signals -were received. Thus, two messages sent from the same sender may be in another -order than the order they were sent. +were received. Thus, two messages sent from the same sender may be in a different +order from the order in which they were sent. Note that priority messages *do not* violate the [signal ordering guarantee](ref_man_processes.md#signal-delivery) of the @@ -391,7 +391,7 @@ after the signals have been received by the receiving process. A [`receive`](expressions.md#receive) expression will select the first message, from the start, in the message queue that matches, just as if only ordinary messages exist in the message queue. The total message queue length in figure 1 -equals `P+M`. The lengths `P` and `M` are not be visible, only the total message +equals `P+M`. The lengths `P` and `M` are not visible; only the total message queue length can be determined. There is no way for the Erlang code to distinguish a priority message from an ordinary message when fetching a message from the message queue. Such knowledge needs to be part of the message protocol @@ -407,8 +407,8 @@ that the process should adhere to. > Priority messages are intended to solve very specific problems where it > previously was very hard to solve such problems efficiently using ordinary > signaling. You *very seldom* need to resort to usage of priority messages. -> Receiving processes have *not* been optimized for handling large amounts of -> priority messages. If a process accumulate a large amount of priority +> Receiving processes have *not* been optimized for handling large amounts of +> priority messages. If a process accumulates a large amount of priority > messages, the design of that message protocol should be redesigned since > this is not how priority messages are intended to be used. @@ -419,14 +419,14 @@ alias then needs to be distributed to processes that are to be able to send priority messages to the process that created the alias. In order to send a priority message, the priority alias should be passed to the `erlang:send/3` BIF at the same time as the option `priority` is passed in the option list. -Note that both the priority alias as well as the `priority` option need to +Note that both the priority alias and the `priority` option need to be passed in order for the message to be accepted as a priority message. The priority alias can also be used for sending exit signals which will be handled as priority messages if the receiver is trapping exits. In this case -the priority alias should be passed as first argument to the `erlang:exit/3` +the priority alias should be passed as the first argument to the `erlang:exit/3` BIF and the option `priority` should be passed in the option list. Also in -this case both the priority alias as well as the `priority` option need to be +this case both the priority alias and the `priority` option need to be passed in order for the message to be accepted as a priority message. Note that this *only* affects how a potential exit message is handled if the receiver is trapping exits. The exit signal as such will not get a higher priority. @@ -444,11 +444,11 @@ cannot be used for this. In order to enable priority message reception of messages triggered by a monitor, the process that creates the monitor needs to create it using the `erlang:monitor/3` BIF and pass the option `priority`. A message received -due to the the monitor being triggered will then be handled as a priority +due to the monitor being triggered will then be handled as a priority message. -In order to enable priority message reception for an exit signals due to -broken links, the process that wants the exit signal as a priority message, +In order to enable priority message reception for exit signals due to +broken links, the process that wants the exit signal as a priority message needs to call the `erlang:link/2` BIF with the `priority` option. The `priority` option will only enable priority message handling of exit signals for the process that called the `erlang:link/2` BIF with the `priority` @@ -464,7 +464,7 @@ signals from an exiting process due to `alive_request`s are not sent until all _directly visible Erlang resources_ held by the terminating process have been released. With _directly visible Erlang resources_ we here mean all resources made available by the language excluding resources held by heap data, dirty -native code execution and the process identifier of the terminating process. +native code execution, and the process identifier of the terminating process. Examples of _directly visible Erlang resources_ are [registered name](ref_man_processes.md#registered-processes) and [ETS](`m:ets`) tables. @@ -481,15 +481,15 @@ system cannot force the native code to stop executing. The runtime system tries to prevent the execution of the dirty native code from affecting other processes by, for example, disabling functionality such as [`enif_send()`](`e:erts:erl_nif.md#enif_send`) when used from a terminated -process, but if the NIF is not well behaved it can still affect other processes. -A well behaved dirty NIF should test if +process, but if the NIF is not well-behaved it can still affect other processes. +A well-behaved dirty NIF should test if [the process it is executing in has exited](`e:erts:erl_nif.md#enif_is_current_process_alive`), and if so stop executing. In the general case, the heap of a process cannot be removed before all signals that it needs to send have been sent. Resources held by heap data are the memory blocks containing the heap, but also include things referred to from the heap -such as off heap binaries, and resources held via NIF +such as off-heap binaries, and resources held via NIF [resource objects](`e:erts:erl_nif.md#resource_objects`) on the heap. [](){: #signal-delivery } @@ -507,15 +507,15 @@ channel goes down. The only signal ordering guarantee given is the following: if an entity sends multiple signals to the same destination entity, the order is preserved; that is, if `A` sends a signal `S1` to `B`, and later sends signal `S2` to `B`, `S1` -is guaranteed not to arrive after `S2`. Note that `S1` may, or may not have been +is guaranteed not to arrive after `S2`. Note that `S1` may or may not have been lost. [](){: #signal-irregularities } ### Irregularities -- **Synchronous Error Checking** - Some functionality that send signals have - synchronous error checking when sending locally on a node and fail if the +- **Synchronous Error Checking** - Some functionality that sends signals has + synchronous error checking when sending locally on a node and fails if the receiver is not present at the time when the signal is sent: - The [send operator (`!`)](expressions.md#send), @@ -544,8 +544,8 @@ lost. #blocking-signaling-over-distribution } ** When sending a signal over a distribution channel, the sending process may be suspended even though the signal is supposed to be sent asynchronously. This is - due to the built in flow control over the channel that has been present more or - less for ever. When the size of the output buffer for the channel reach the _distribution + due to the built-in flow control over the channel that has been present more or + less forever. When the size of the output buffer for the channel reaches the _distribution buffer busy limit_, processes sending on the channel will be suspended until the size of the buffer shrinks below the limit. @@ -556,9 +556,9 @@ lost. Since this functionality has been present for so long, it is not possible to remove it, but it is possible to enable _fully asynchronous distributed - signaling_ on a per process level using + signaling_ on a per-process level using [`process_flag(async_dist, Bool)`](`m:erlang#process_flag_async_dist`) which - can be used to solve problems occuring due to blocking signaling. However, + can be used to solve problems occurring due to blocking signaling. However, note that you need to make sure that flow control for data sent using _fully asynchronous distributed signaling_ is implemented, or that the amount of such data is known to always be limited; otherwise, you may get into a situation @@ -572,14 +572,14 @@ Erlang too long and it would break a lot of existing code. ## Links -Two processes can be _linked_ to each other. Also a process and a port that +Two processes can be _linked_ to each other. Also, a process and a port that reside on the same node can be linked to each other. A link between two processes can be created if one of them calls the [`link/1`](`erlang:link/1`) BIF with the process identifier of the other process as argument. Links can also -be created using one the following spawn BIFs +be created using one of the following spawn BIFs [`spawn_link()`](`erlang:spawn_link/4`), [`spawn_opt()`](`erlang:spawn_opt/5`), or [`spawn_request()`](`erlang:spawn_request/5`). The spawn operation and the -link operation will be performed atomically, in these cases. +link operation will be performed atomically in these cases. If one of the participants of a link terminates, it will [send an exit signal](ref_man_processes.md#sending_exit_signals) to the other @@ -614,7 +614,7 @@ for more information about OTP supervision trees, which use this feature. ### Sending Exit Signals -When a process or port [terminates](ref_man_processes.md#process-termination) it +When a process or port [terminates](ref_man_processes.md#process-termination), it will send exit signals to all processes and ports that it is [linked](ref_man_processes.md#links) to. The exit signal will contain the following information: @@ -635,7 +635,7 @@ following information: preceding call to the [`link(PidOrPort)`](`erlang:link/1`) BIF. The process or port identified as sender of the exit signal will equal the `PidOrPort` argument passed to [`link/1`](`link/1`). - - `noconnection` in case the linked processes resides on different nodes and + - `noconnection` in case the linked processes reside on different nodes and the connection between the nodes was lost or could not be established. The process or port identified as sender of the exit signal might in this case still be alive. @@ -693,7 +693,7 @@ received by a process: the atom `killed` as exit reason. - the receiver is not trapping exits, and the exit reason is something other than the atom `normal`. Also, if the `link` flag of the exit signal is set, - the link also needs to be active otherwise the exit signal will be dropped. + the link also needs to be active; otherwise, the exit signal will be dropped. The exit reason of the receiving process will equal the exit reason of the exit signal. Note that if the `link` flag is set, an exit reason of `kill` will _not_ be converted to `killed`. @@ -732,7 +732,7 @@ If `Pid2` does not exist, the 'DOWN' message is sent immediately with `Reason` set to `noproc`. Monitors are unidirectional. Repeated calls to `erlang:monitor(process, Pid)` -creates several independent monitors, and each one sends a 'DOWN' message when +create several independent monitors, and each one sends a 'DOWN' message when `Pid` terminates. A monitor can be removed by calling [`erlang:demonitor(Ref)`](`erlang:demonitor/1`). diff --git a/system/doc/reference_manual/ref_man_records.md b/system/doc/reference_manual/ref_man_records.md index 799362d34621..8211da71fe4f 100644 --- a/system/doc/reference_manual/ref_man_records.md +++ b/system/doc/reference_manual/ref_man_records.md @@ -139,7 +139,7 @@ old values. Since record expressions are expanded to tuple expressions, creating records and accessing record fields are allowed in guards. However, -all subexpressions (for initializing fields), must be valid guard +all subexpressions (for initializing fields) must be valid guard expressions as well. _Examples:_ diff --git a/system/doc/reference_manual/reference_manual.md b/system/doc/reference_manual/reference_manual.md index ba18197b3e46..d7095ce51f05 100644 --- a/system/doc/reference_manual/reference_manual.md +++ b/system/doc/reference_manual/reference_manual.md @@ -33,7 +33,7 @@ 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. -Information about implementation of Erlang can, for example, be found, in the +Information about implementation of Erlang can, for example, be found in the following: - [System Principles](`e:system:system_principles.md`) diff --git a/system/doc/reference_manual/typespec.md b/system/doc/reference_manual/typespec.md index b6a5276be71b..bb53adab95fd 100644 --- a/system/doc/reference_manual/typespec.md +++ b/system/doc/reference_manual/typespec.md @@ -189,7 +189,7 @@ association type it is not required for the key type to be present. The notation `#{}` specifies the singleton type for the empty map. Note that this notation is not a shorthand for the `t:map/0` type. -For convenience, the following types are also built-in. They can be thought as +For convenience, the following types are also built-in. They can be thought of as predefined aliases for the type unions also shown in the table. [](){: #builtin_types } @@ -225,15 +225,15 @@ predefined aliases for the type unions also shown in the table. _Table: Built-in types, predefined aliases_ -In addition, the following three built-in types exist and can be thought as +In addition, the following three built-in types exist and can be thought of as defined below, though strictly their "type definition" is not valid syntax according to the type language defined above. -| Built-in type | Can be thought defined by the syntax | -| --------------------- | ------------------------------------ | -| `t:non_neg_integer/0` | `0..` | -| `t:pos_integer/0` | `1..` | -| `t:neg_integer/0` | `..-1` | +| Built-in type | Can be thought of as defined by the syntax | +| --------------------- | ------------------------------------------ | +| `t:non_neg_integer/0` | `0..` | +| `t:pos_integer/0` | `1..` | +| `t:neg_integer/0` | `..-1` | _Table: Additional built-in types_ @@ -317,7 +317,7 @@ similar restriction currently exists for records.) Type declarations can also be parameterized by including type variables between the parentheses. The syntax of type variables is the same as Erlang variables, -that is, starts with an upper-case letter. These variables is to +that is, they start with an uppercase letter. These variables are to appear on the RHS of the definition. A concrete example follows: ```erlang @@ -331,7 +331,7 @@ refer to them as _remote types_. This declaration has the following form: -export_type([T1/A1, ..., Tk/Ak]). ``` -Here the `Ti`s are atoms (the name of the type) and the `Ai`s are their arguments. +Here the `Ti`s are atoms (the name of the type) and the `Ai`s are their arities. _Example:_ @@ -353,7 +353,7 @@ Types declared as `opaque` represent sets of terms whose 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 is always to be exported. +accessible by other modules anyway - and are always to be exported. > #### Change {: .info } > @@ -364,7 +364,7 @@ names instead of their structure. That is, `-nominal feet() :: integer()` and `-nominal meter() :: integer()` are not the same type, while if `-type` is used it would be. -Read more on [Opaques](opaques.md) and [Nominals](nominals.md) +Read more on [Opaques](opaques.md) and [Nominals](nominals.md). [](){: #typeinrecords } @@ -458,7 +458,7 @@ declaration. > ``` > > In specifications and type declarations the type `person()` is to be preferred -> before `#person{}`. +> over `#person{}`. ## Specifications for Functions