From df88b47cdafcc2e04452456942ea572a7b72e2f2 Mon Sep 17 00:00:00 2001 From: Lars G Thorsen Date: Tue, 26 Jan 2010 10:13:35 +0000 Subject: OTP-8343 The documentation is now possible to build in an open source environment after a number of bugs are fixed and some features are added in the documentation build process. - The arity calculation is updated. - The module prefix used in the function names for bif's are removed in the generated links so the links will look like http://www.erlang.org/doc/man/erlang.html#append_element-2 instead of http://www.erlang.org/doc/man/erlang.html#erlang:append_element-2 - Enhanced the menu positioning in the html documentation when a new page is loaded. - A number of corrections in the generation of man pages (thanks to Sergei Golovan) - Moved some man pages to more apropriate sections, pages in section 4 moved to 5 and pages in 6 moved to 7. - The legal notice is taken from the xml book file so OTP's build process can be used for non OTP applications. --- system/doc/extensions/bit_syntax.xml | 403 ----------------------------------- 1 file changed, 403 deletions(-) delete mode 100644 system/doc/extensions/bit_syntax.xml (limited to 'system/doc/extensions/bit_syntax.xml') diff --git a/system/doc/extensions/bit_syntax.xml b/system/doc/extensions/bit_syntax.xml deleted file mode 100644 index d86f73cd9a..0000000000 --- a/system/doc/extensions/bit_syntax.xml +++ /dev/null @@ -1,403 +0,0 @@ - - - - -
- - 20002009 - Ericsson AB. All Rights Reserved. - - - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. - - - - The Bit Syntax - Björn Gustavsson - Bjarne Däcker - 1 - Bjarne DäKer - - 00-06-21 - PA1 - bit_syntax.sgml -
-

This section describes the "bit syntax" which was added to - the Erlang language in release 5.0 (R7). - Compared to the original bit syntax prototype - by Claes Wikström and Tony Rogvall (presented on the - Erlang User's Conference 1999), this implementation differs - primarily in the following respects, -

- - -

the character pairs '<<' and '>>' are used to delimit - a binary patterns and constructor (not '<' and '>' as in - the prototype), -

- - -

the tail syntax ('|Variable') has been eliminated, -

- - -

all size expressions must be bound, -

- - -

a type unit:U has been added, -

- - -

lists and tuples cannot be generated -

- - -

there are no paddings whatsoever. -

- - - -
- Introduction -

In Erlang a Bin is used for constructing binaries and - matching binary patterns. A Bin is written with the - following syntax:

- > - ]]> -

A Bin is a low-level sequence of bytes. The purpose of a - Bin is to be able to, from a high level, - construct a binary, -

- > - ]]> -

in which case all elements must be bound, or to - match a binary, -

- > = Bin - ]]> -

where Bin is bound, and where the elements are bound or unbound, - as in any match. -

-

Each element specifies a certain segment of the binary. - A segment is is a set of contiguous bits of the binary (not - necessarily on a byte boundary). The first element specifies - the initial segment, the second element specifies the following - segment etc. -

-

The following examples illustrate how binaries are constructed - or matched, and how elements and tails are specified. -

- -
- Examples -

Example 1: A binary can be constructed from a set of - constants or a string literal:

- >, - Bin12 = <<"abc">> - ]]> -

yields binaries of size 3; binary_to_list(Bin11) - evaluates to [1, 17, 42], and - binary_to_list(Bin12) evaluates to [97, 98, 99]. -

-

Example 2: Similarly, a binary can be constructed - from a set of bound variables:

- > - ]]> -

yields a binary of size 4, and binary_to_list(Bin2) - evaluates to [1, 17, 00, 42] too. Here we used a - size expression for the variable C in order to - specify a 16-bits segment of Bin2. -

-

Example 3: A Bin can also be used for matching: if - D, E, and F are unbound variables, and - Bin2 is bound as in the former example,

- > = Bin2 - ]]> -

yields D = 273, E = 00, and F binds to a binary - of size 1: binary_to_list(F) = [42]. -

-

Example 4: The following is a more elaborate example - of matching, where Dgram is bound to the consecutive - bytes of an IP datagram of IP protocol version 4, and where we - want to extract the header and the data of the datagram:

- > when HLen >= 5, 4*HLen =< DgramSize -> - OptsLen = 4*(HLen - ?IP_MIN_HDR_LEN), - <> = RestDgram, - ... - end. - ]]> -

Here the segment corresponding to the Opts variable - has a type modifier specifying that Opts should - bind to a binary. All other variables have the default type - equal to unsigned integer. -

-

An IP datagram header is of variable length, and its length - - measured in the number of 32-bit words - is given in the segment - corresponding to HLen, the minimum value of which is - 5. It is the segment corresponding to Opts that is - variable: if HLen is equal to 5, Opts will be an - empty binary. -

-

The tail variables RestDgram and Data bind to - binaries, as all tail variables do. Both may bind to empty - binaries. -

-

If the first 4-bits segment of Dgram is not equal to - 4, or if HLen is less than 5, or if the size of - Dgram is less than 4*HLen, the match of - Dgram fails. -

-
-
- -
- A Lexical Note -

Note that ">]]>" will be interpreted as - ">]]>", which is a syntax error. - The correct way to write the expression is ">]]>".

-
- -
- Segments -

Each segment has the following general syntax:

-

Value:Size/TypeSpecifierList

-

Both the Size and the TypeSpecifier or both may be - omitted; thus the following variations are allowed: -

-

Value

-

Value:Size

-

Value/TypeSpecifierList

-

Default values will be used for missing specifications. The default - values are described in the section "Defaults" below. -

-

Used in binary construction, the Value part is any expression. - Used in binary matching, the Value part must be a literal or - variable. You can read more about the Value part in the - sections about constructing binaries and matching binaries. -

-

The Size part of the segment multiplied by the unit in the - TypeSpecifierList (described below) gives the number of bits - for the segment. In construction, Size is any expression that - evaluates to an integer. In matching, Size must be a constant - expression or a variable. -

-

The TypeSpecifierList is a list of type specifiers separated by - hyphens. -

- - Type - The type can be integer, float, or binary. - Signedness - The signedness specification can be either signed - or unsigned. Note that signedness only matters for matching. - Endianness - The endianness specification can be either big, - little, or native. Native-endian means that - the endian will be resolved at load time to be either - big-endian or little-endian, depending on what is "native" - for the CPU that the Erlang machine is run on. - Unit - The unit size is given as unit:IntegerLiteral. - The allowed range is 1-256. It will be multiplied by the Size - specifier to give the effective size of the segment. - -

Example: -

- -X:4/little-signed-integer-unit:8 - -

This element has a total size of 4*8 = 32 bits, and it contains a - signed integer in little-endian order.

-
- -
- Defaults -

The default type for a segment is integer. The default type - does not depend on the value, even if the value is a literal. - For instance, the default type in '>]]>' is integer, - not float. -

-

The default Size depends on the type. - For integer it is 8. For float it is 64. - For binary it is all of the binary. In matching, this default - value is only valid for the very last element. All other binary elements - in matching must have a size specification. -

-

The default unit depends on the the type. - For integer and float it is 1. - For binary it is 8. -

-

The default signedness is unsigned. -

-

The default endianness is big.

-
- -
- Constructing Binaries -

This section describes the rules for constructing binaries using - the bit syntax. Unlike when constructing lists or tuples, the construction - of a binary can fail with a badarg exception. -

-

There can be zero or more segments in a binary to be constructed. - The expression '>]]>' constructs a zero length binary. -

-

Each segment in a binary can consist of zero or more bits. - There are no alignment rules for individual segments, but the total - number of bits in all segments must be evenly divisible by 8, - or in other words, the resulting binary must consist of a whole number - of bytes. An badarg exception will be thrown if the resulting - binary is not byte-aligned. Example: -

- > - ]]> -

The total number of bits is 7, which is not evenly divisible by 8; - thus, there will be badarg exception (and a compiler warning - as well). The following example -

- > - ]]> -

will successfully construct a binary of 8 bits, or one byte. (Provided - that all of X, Y and Z are integers.) -

-

As noted earlier, segments have the following general syntax: -

-

Value:Size/TypeSpecifierList

-

When constructing binaries, Value and Size can be - any Erlang expression. However, for syntactical reasons, - both Value and Size must be enclosed in parenthesis - if the expression consists of anything more than a single literal - or variable. The following gives a compiler syntax error: -

- > - ]]> -

This expression must be rewritten to -

- > - ]]> -

in order to be accepted by the compiler. -

- -
- Including Literal Strings -

As syntactic sugar, an literal string may be written instead of a - element.

- > ]]> -

which is syntactic sugar for

- > ]]> -
-
- -
- Matching Binaries -

This section describes the rules for matching binaries using the - bit syntax. -

-

There can be zero or more segments in a binary binary pattern. - A binary pattern can occur in every place patterns are allowed, also - inside other patterns. Binary patterns cannot be nested. -

-

The pattern '>]]>' matches a zero length binary. -

-

Each segment in a binary can consist of zero or more bits. -

-

A segment of type binary must have a size evenly divisible by 8. -

-

This means that the following head will never match:

- >) -> ]]> -

As noted earlier, segments have the following general syntax: -

-

Value:Size/TypeSpecifierList

-

When matching Value value must be either a variable or an integer - or floating point literal. Expressions are not allowed. -

-

Size must be an integer literal, or a previously bound variable. - Note that the following is not allowed:

- >) -> - {X,T}. ]]> -

The two occurrences of N are not related. The compiler - will complain that the N in the size field is unbound. -

-

The correct way to write this example is like this:

- - <> = Bin, - {X,T}. ]]> - -
- Getting the Rest of the Binary -

To match out the rest of binary, specify a binary field without size:

- >) -> ]]> -

As always, the size of the tail must be evenly divisible by 8. -

-
-
- -
- Traps and Pitfalls -

Assume that we need a function that creates a binary out of a - list of triples of integers. A first (inefficient) version of such - a function could look like this:

- - triples_to_bin(T, <<>>). - -triples_to_bin([{X,Y,Z} | T], Acc) -> - triples_to_bin(T, <>); % inefficient -triples_to_bin([], Acc) -> - Acc. ]]> -

The reason for the inefficiency of this function is that for - each triple, the binary constructed so far (Acc) is copied. - (Note: The original bit syntax prototype avoided the copy operation - by using segmented binaries, which are not implemented in R7.) -

-

The efficient way to write this function in R7 is:

- - triples_to_bin(T, []). - -triples_to_bin([{X,Y,Z} | T], Acc) -> - triples_to_bin(T, [<> | Acc]); -triples_to_bin([], Acc) -> - list_to_binary(lists:reverse(Acc)). ]]> -

Note that list_to_binary/1 handles deep lists of binaries - and small integers. (This fact was previously undocumented.) -

-
- - -- cgit v1.2.3