From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/erl_scan.xml | 362 ++++++++++++++++++++-------------------- 1 file changed, 183 insertions(+), 179 deletions(-) (limited to 'lib/stdlib/doc/src/erl_scan.xml') diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 1199c34f0f..54240dea19 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -37,56 +37,96 @@

This module contains functions for tokenizing characters into Erlang tokens.

-
- DATA TYPES - -category() = atom() -column() = integer() > 0 -line() = integer() -location() = line() | {line(), column()} -reserved_word_fun() -> fun(atom()) -> bool() -set_attribute_fun() -> fun(term()) -> term() -symbol() = atom() | float() | integer() | string() -token() = {category(), attributes()} | {category(), attributes(), symbol()} -attributes() = line() | list() | tuple() -
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - string(String) -> Return - string(String, StartLocation) -> Return - string(String, StartLocation, Options) -> Return + + + Scan a string and return the Erlang tokens - - String = string() - Return = {ok, Tokens, EndLocation} | Error - Tokens = [token()] - Error = {error, ErrorInfo, EndLocation} - StartLocation = EndLocation = location() - Options = Option | [Option] - Option = {reserved_word_fun,reserved_word_fun()} - | return_comments | return_white_spaces | return - | text - -

Takes the list of characters String and tries to - scan (tokenize) them. Returns {ok, Tokens, EndLocation}, - where Tokens are the Erlang tokens from - String. EndLocation is the first location - after the last token.

-

{error, ErrorInfo, EndLocation} is returned if an - error occurs. EndLocation is the first location after +

Takes the list of characters String and tries to + scan (tokenize) them. Returns {ok, Tokens, + EndLocation}, + where Tokens are the Erlang tokens from + String. EndLocation + is the first location after the last token.

+

{error, ErrorInfo, ErrorLocation} + is returned if an error occurs. + ErrorLocation is the first location after the erroneous token.

-

string(String) is equivalent to - string(String, 1), and string(String, - StartLocation) is equivalent to string(String, - StartLocation, []).

-

StartLocation indicates the initial location when - scanning starts. If StartLocation is a line - attributes() as well as EndLocation and - ErrorLocation will be lines. If - StartLocation is a pair of a line and a column +

string(String) is equivalent to + string(String, 1), and + string(String, + StartLocation) is equivalent to + string(String, + StartLocation, []).

+

StartLocation indicates the initial location + when scanning starts. If StartLocation is a line + attributes() as well as EndLocation and + ErrorLocation will be lines. If + StartLocation is a pair of a line and a column attributes() takes the form of an opaque compound - data type, and EndLocation and ErrorLocation + data type, and EndLocation and + ErrorLocation will be pairs of a line and a column. The token attributes contain information about the column and the line where the token begins, as well as the text of the @@ -134,148 +174,130 @@ attributes() = line() | list() | tuple() - tokens(Continuation, CharSpec, StartLocation) -> Return - tokens(Continuation, CharSpec, StartLocation, Options) -> Return + + + + + An opaque continuation Re-entrant scanner - - Continuation = [] | Continuation1 - Return = {done, Result, LeftOverChars} | {more, Continuation1} - LeftOverChars = CharSpec - CharSpec = string() | eof - Continuation1 = tuple() - Result = {ok, Tokens, EndLocation} | {eof, EndLocation} | Error - Tokens = [token()] - Error = {error, ErrorInfo, EndLocation} - StartLocation = EndLocation = location() - Options = Option | [Option] - Option = {reserved_word_fun,reserved_word_fun()} - | return_comments | return_white_spaces | return - | text -

This is the re-entrant scanner which scans characters until a dot ('.' followed by a white space) or eof has been reached. It returns:

- {done, Result, LeftOverChars} + {done, Result, LeftOverChars} +

This return indicates that there is sufficient input - data to get a result. Result is:

+ data to get a result. Result is:

- {ok, Tokens, EndLocation} + {ok, Tokens, EndLocation} + -

The scanning was successful. Tokens is the - list of tokens including dot.

+

The scanning was successful. Tokens + is the list of tokens including dot.

 {eof, EndLocation}

End of file was encountered before any more tokens.

 - {error, ErrorInfo, EndLocation} + {error, ErrorInfo, EndLocation} + -

An error occurred. LeftOverChars is the remaining - characters of the input data, +

An error occurred. LeftOverChars + is the remaining characters of the input data, starting from EndLocation.

 - {more, Continuation1} + {more, Continuation1}

More data is required for building a term. - Continuation1 must be passed in a new call to + Continuation1 must be passed in a new call to tokens/3,4 when more data is available.

 -

The CharSpec eof signals end of file. - LeftOverChars will then take the value eof as - well.

-

tokens(Continuation, CharSpec, StartLocation) is - equivalent to tokens(Continuation, CharSpec, - StartLocation, []).

+

The CharSpec eof signals end of file. + LeftOverChars will then take the value eof + as well.

+

tokens(Continuation, CharSpec, + StartLocation) is equivalent to + tokens(Continuation, CharSpec, + StartLocation, []).

See string/3 for a description of the various options.

 - reserved_word(Atom) -> bool() + Test for a reserved word - - Atom = atom() - -

Returns true if Atom is an Erlang reserved - word, otherwise false.

+

Returns true if Atom is an Erlang + reserved word, otherwise false.

 - token_info(Token) -> TokenInfo + Return information about a token - - Token = token() - TokenInfo = [TokenInfoTuple] - TokenInfoTuple = {TokenItem, Info} - TokenItem = atom() - Info = term() -

Returns a list containing information about the token - Token. The order of the TokenInfoTuples is not - defined. The following TokenItems are returned: - category, column, length, - line, symbol, and text. See Token. The order of the + TokenInfoTuples is not + defined. See token_info/2 for information about specific - TokenInfoTuples.

+ TokenInfoTuples.

Note that if token_info(Token, TokenItem) returns - undefined for some TokenItem in the list above, the - item is not included in TokenInfo.

+ undefined for some TokenItem, the + item is not included in TokenInfo.

 - token_info(Token, TokenItemSpec) -> TokenInfo + + + + Return information about a token - - Token = token() - TokenItemSpec = TokenItem | [TokenItem] - TokenInfo = TokenInfoTuple | undefined | [TokenInfoTuple] - TokenInfoTuple = {TokenItem, Info} - TokenItem = atom() - Info = term() -

Returns a list containing information about the token - Token. If TokenItemSpec is a single - TokenItem, the returned value is the corresponding + Token. If one single + TokenItem is given the returned value is + the corresponding TokenInfoTuple, or undefined if the - TokenItem has no value. If TokenItemSpec is a - list of - TokenItem, the result is a list of - TokenInfoTuple. The TokenInfoTuples will - appear with the corresponding - TokenItems in the same order as the TokenItems - appeared in the list of TokenItems. TokenItems - with no value are not included in the list of - TokenInfoTuple.

-

The following TokenInfoTuples with corresponding - TokenItems are valid:

+ TokenItem has no value. If a list of + TokenItems is given the result is a list of + TokenInfoTuple. The + TokenInfoTuples will + appear with the corresponding TokenItems in + the same order as the TokenItems + appear in the list of TokenItems. + TokenItems with no value are not included + in the list of TokenInfoTuple.

+

The following TokenInfoTuples with corresponding + TokenItems are valid:

- {category, category()} + {category, + category()}

The category of the token.

 - {column, column()} + {column, + column()}

The column where the token begins.

 {length, integer() > 0}

The length of the token's text.

 - {line, line()} + {line, + line()}

The line where the token begins.

 - {location, location()} + {location, + location()}

The line and column where the token begins, or just the line if the column unknown.

 - {symbol, symbol()} + {symbol, + symbol()}

The token's symbol.

 {text, string()} @@ -285,70 +307,59 @@ attributes() = line() | list() | tuple() - attributes_info(Attributes) -> AttributesInfo + Return information about token attributes - - Attributes = attributes() - AttributesInfo = [AttributeInfoTuple] - AttributeInfoTuple = {AttributeItem, Info} - AttributeItem = atom() - Info = term() -

Returns a list containing information about the token - attributes Attributes. The order of the - AttributeInfoTuples is not defined. The following - AttributeItems are returned: - column, length, line, and text. + attributes Attributes. The order of the + AttributeInfoTuples is not defined. See attributes_info/2 for information about specific - AttributeInfoTuples.

+ AttributeInfoTuples.

Note that if attributes_info(Token, AttributeItem) returns undefined for some AttributeItem in the list above, the item is not included in - AttributesInfo.

+ AttributesInfo.

 - attributes_info(Attributes, AttributeItemSpec) -> AttributesInfo + + Return information about a token attributes - - Attributes = attributes() - AttributeItemSpec = AttributeItem | [AttributeItem] - AttributesInfo = AttributeInfoTuple | undefined - | [AttributeInfoTuple] - AttributeInfoTuple = {AttributeItem, Info} - AttributeItem = atom() - Info = term() - +

Returns a list containing information about the token - attributes Attributes. If AttributeItemSpec is - a single AttributeItem, the returned value is the - corresponding AttributeInfoTuple, or undefined - if the AttributeItem has no value. If - AttributeItemSpec is a list of - AttributeItem, the result is a list of - AttributeInfoTuple. The AttributeInfoTuples - will appear with the corresponding AttributeItems in - the same order as the AttributeItems appeared in the - list of AttributeItems. AttributeItems with no + attributes Attributes. If one single + AttributeItem is given the returned value is the + corresponding AttributeInfoTuple, + or undefined if the AttributeItem + has no value. If a list of AttributeItem + is given the result is a list of + AttributeInfoTuple. + The AttributeInfoTuples + will appear with the corresponding AttributeItems + in the same order as the AttributeItems + appear in the list of AttributeItems. + AttributeItems with no value are not included in the list of - AttributeInfoTuple.

-

The following AttributeInfoTuples with corresponding - AttributeItems are valid:

+ AttributeInfoTuple.

+

The following AttributeInfoTuples with + corresponding AttributeItems are valid:

- {column, column()} + {column, + column()}

The column where the token begins.

 {length, integer() > 0}

The length of the token's text.

 - {line, line()} + {line, + line()}

The line where the token begins.

 - {location, location()} + {location, + location()}

The line and column where the token begins, or just the line if the column unknown.

 @@ -359,29 +370,22 @@ attributes() = line() | list() | tuple() - set_attribute(AttributeItem, Attributes, SetAttributeFun) -> AttributesInfo + Set a token attribute value - - AttributeItem = line - Attributes = attributes() - SetAttributeFun = set_attribute_fun() -

Sets the value of the line attribute of the token - attributes Attributes.

-

The SetAttributeFun is called with the value of + attributes Attributes.

+

The SetAttributeFun is called with the value of the line attribute, and is to return the new value of the line attribute.

 - format_error(ErrorDescriptor) -> string() + Format an error descriptor - - ErrorDescriptor = errordesc() - -

Takes an ErrorDescriptor and returns a string which +

Takes an ErrorDescriptor and returns + a string which describes the error or warning. This function is usually called implicitly when processing an ErrorInfo structure (see below).

-- cgit v1.2.3