From 3c2be863bde4965a1ac61092b1348b96397940cb Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 9 Mar 2015 16:25:00 +0100 Subject: stdlib: Add module erl_anno Introduce erl_anno, an abstraction of the second element of tokens and tuples in the abstract format. The convention that negative line numbers can be used for silencing compiler warnings will no longer work in OTP 19; instead the annotation 'generated' is to be used. --- lib/stdlib/doc/src/Makefile | 3 +- lib/stdlib/doc/src/erl_anno.xml | 308 +++++++++++++++++++++++++++++++++++++++ lib/stdlib/doc/src/erl_parse.xml | 98 ++++++++++++- lib/stdlib/doc/src/ref_man.xml | 3 +- lib/stdlib/doc/src/specs.xml | 1 + 5 files changed, 408 insertions(+), 5 deletions(-) create mode 100644 lib/stdlib/doc/src/erl_anno.xml (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index f5d8b2072a..ce1e19a2a4 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2012. All Rights Reserved. +# Copyright Ericsson AB 1997-2015. 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 @@ -48,6 +48,7 @@ XML_REF3_FILES = \ digraph.xml \ digraph_utils.xml \ epp.xml \ + erl_anno.xml \ erl_eval.xml \ erl_expand_records.xml \ erl_id_trans.xml \ diff --git a/lib/stdlib/doc/src/erl_anno.xml b/lib/stdlib/doc/src/erl_anno.xml new file mode 100644 index 0000000000..281feacdc4 --- /dev/null +++ b/lib/stdlib/doc/src/erl_anno.xml @@ -0,0 +1,308 @@ + + + + +
+ + 2015 + 2015 + 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 on line 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 Initial Developer of the Original Code is Ericsson AB. + + + erl_anno + Hans Bolinder + Kenneth Lundin + 1 + + + 2015-02-26 + A + erl_anno.xml +
+ erl_anno + + + Abstract Datatype for the Annotations of the Erlang Compiler + + + +

This module implements an abstract type that is used by the + Erlang Compiler and its helper modules for holding data such as + column, line number, and text. The data type is a collection of + annotations as + described in the following.

+

The Erlang Token Scanner returns tokens with a subset of + the following annotations, depending on the options:

+ + column +

The column where the token begins.

 + location +

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

+ + text +

The token's text.

 + +

From the above the following annotation is derived:

+ + line +

The line where the token begins.

 + +

Furthermore, the following annotations are supported by + this module, and used by various modules:

+ + file +

A filename.

 + generated +

A Boolean indicating if the abstract code is + compiler generated. The Erlang Compiler does not emit warnings + for such code.

+ + record +

A Boolean indicating if the origin of the abstract + code is a record. Used by Dialyzer to assign types to tuple + elements.

+ + +

The functions + column(), + end_location(), + line(), + location(), and + text() + in the erl_scan module can be used for inspecting + annotations in tokens.

+

The functions + map_anno(), + fold_anno(), + mapfold_anno(), + new_anno(), + + anno_from_term(), and + + anno_to_term() in the erl_parse module can be + used for manipulating annotations in abstract code. +

+ + + + + anno() +

A collection of annotations.

+ + + + + +

The term representing a collection of annotations. It is + either a location() or a list of key-value pairs.

+ + + + + + + + +

To be changed to a non-negative integer in Erlang/OTP 19.0.

+ + + + + + + + + + + + + + + Return the column + +

Returns the column of the annotations Anno. +

+ + + + + + Return the end location of the text + +

Returns the end location of the text of the + annotations Anno. If there is no text, + undefined is returned. +

+ + + + + + Return the filename + +

Returns the filename of the annotations Anno. + If there is no filename, undefined is returned. +

+ + + + + Return annotations given a term + +

Returns annotations with the representation Term. +

+ +

See also to_term(). +

+ + + + + + Return the generated Boolean + +

Returns true if the annotations Anno + has been marked as generated. The default is to return + false. +

+ + + + + Test for a collection of annotations + +

Returns true if Term is a collection of + annotations, false otherwise.

+ + + + + + Return the line + +

Returns the line of the annotations Anno. +

+ + + + + + Return the location + +

Returns the location of the annotations Anno. +

+ + + + + + Create a new collection of annotations + +

Creates a new collection of annotations given a location.

+ + + + + + Modify the filename + +

Modifies the filename of the annotations Anno. +

+ + + + + + Modify the generated marker + +

Modifies the generated marker of the annotations + Anno. +

+ + + + + + Modify the line + +

Modifies the line of the annotations Anno. +

+ + + + + + Modify the location + +

Modifies the location of the annotations Anno. +

+ + + + + + Modify the record marker + +

Modifies the record marker of the annotations Anno. +

+ + + + + + Modify the text + +

Modifies the text of the annotations Anno. +

+ + + + + + Return the text + +

Returns the text of the annotations Anno. + If there is no text, undefined is returned. +

+ + + + + Return the term representing a collection of + annotations + +

Returns the term representing the annotations Anno. +

+

See also from_term(). +

+ + + +
+ See Also +

erl_scan(3), + erl_parse(3) +

+
+ diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index cf0bff48cd..b97d06e919 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -4,7 +4,7 @@
- 19962014 + 19962015 Ericsson AB. All Rights Reserved. @@ -192,6 +192,97 @@ considered a string.

+ + + + Map a function over the annotations of an abstract form + + +

Modifies the abstract form Abstr by applying + Fun on every collection of annotations of the + abstract form. The abstract form is traversed in a + depth-first, left-to-right, fashion. +

+ + + + + + Fold a function over the annotations of an abstract form + + +

Updates an accumulator by applying Fun on + every collection of annotations of the abstract form + Abstr. The first call to Fun has + AccIn as argument, and the returned accumulator + AccOut is passed to the next call, and so on. + The final value of the accumulator is returned. The abstract + form is traversed in a depth-first, left-to-right, fashion. +

+ + + + + + Map and fold a function over the annotations of an abstract form + + +

Modifies the abstract form Abstr by applying + Fun on every collection of annotations of the + abstract form, while at the same time updating an + accumulator. The first call to Fun has + AccIn as second argument, and the returned + accumulator AccOut is passed to the next call, + and so on. The modified abstract form as well as the the + final value of the accumulator is returned. The abstract + form is traversed in a depth-first, left-to-right, fashion. +

+ + + + + + Create new annotations + + +

Creates an abstract form from a term which has the same + structure as an abstract form, but locations where the + abstract form has annotations. For each location, erl_anno:new/1 is + called, and the annotations replace the location. +

+ + + + + + Return annotations as terms + + +

Assumes that Term is a term with the same + structure as an abstract form, but with terms, T say, on + those places where an abstract form has annotations. Returns + an abstract form where every term T has been replaced by the + value returned by calling erl_anno:from_term(T). The + term Term is traversed in a depth-first, + left-to-right, fashion. +

+ + + + + + Return the representation of annotations + + +

Returns a term where every collection of annotations Anno of + Abstr has been replaced by the term returned by + calling erl_anno:to_term(Anno). The abstract form is + traversed in a depth-first, left-to-right, fashion. +

+ +
@@ -211,8 +302,9 @@
See Also

io(3), - erl_scan(3), - ERTS User's Guide

+ erl_anno(3), + erl_scan(3), + ERTS User's Guide

diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index ea4009dc3e..94c1fb55c2 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -4,7 +4,7 @@
- 19962013 + 19962015 Ericsson AB. All Rights Reserved. @@ -45,6 +45,7 @@ + diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index fd77b52da6..6ae0154800 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -11,6 +11,7 @@ + -- cgit v1.2.3 From 87a0af476ef82ca2f33d0e15ce324afcfafe3aad Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 9 Mar 2015 16:26:09 +0100 Subject: stdlib: Use module erl_anno --- lib/stdlib/doc/src/erl_scan.xml | 79 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 5 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 855c8fc195..8f9c1db25b 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -4,7 +4,7 @@
- 19962013 + 19962015 Ericsson AB. All Rights Reserved. @@ -120,7 +120,7 @@ string(String, StartLocation, []).

StartLocation indicates the initial location - when scanning starts. If StartLocation is a line + 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 @@ -132,8 +132,12 @@ line where the token begins, as well as the text of the token (if the text option is given), all of which can be accessed by calling token_info/1,2 or attributes_info/1,2.

+ marker="#token_info/1">token_info/1,2, attributes_info/1,2, + column/1, + line/1, + location/1, and + text/1.

A token is a tuple containing information about syntactic category, the token attributes, and the actual terminal symbol. For punctuation characters (e.g. ;, @@ -236,6 +240,70 @@ reserved word, otherwise false.

+ + + Return the category + +

Returns the category of Token. +

+ + + + + Return the symbol + +

Returns the symbol of Token. +

+ + + + + Return the column + +

Returns the column of Token's + collection of annotations. +

+ + + + + Return the end location of the text + +

Returns the end location of the text of + Token's collection of annotations. If + there is no text, + undefined is returned. +

+ + + + + Return the line + +

Returns the line of Token's collection + of annotations. +

+ + + + + Return the location + +

Returns the location of Token's + collection of annotations. +

+ + + + + Return the text + +

Returns the text of Token's collection + of annotations. If there is no text, undefined is + returned. +

+ + Return information about a token @@ -417,6 +485,7 @@ Module:format_error(ErrorDescriptor)
See Also

io(3), - erl_parse(3)

+ erl_anno(3), + erl_parse(3)

-- cgit v1.2.3