table of contents
other versions
- wheezy 1:15.b.1-dfsg-4+deb7u1
- wheezy-backports 1:17.3-dfsg-4~bpo70+1
- jessie 1:17.3-dfsg-4+deb8u1
- jessie-backports 1:19.2.1+dfsg-2~bpo8+1
- testing 1:19.2.1+dfsg-2
- unstable 1:19.2.1+dfsg-2
- experimental 1:19.3.1+dfsg-1
erl_recomment(3erl) | Erlang Module Definition | erl_recomment(3erl) |
NAME¶
erl_recomment - Inserting comments into abstract Erlang syntax trees.DESCRIPTION¶
Inserting comments into abstract Erlang syntax trees This module contains functions for inserting comments, described by position, indentation and text, as attachments on an abstract syntax tree, at the correct places.EXPORTS¶
quick_recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()
Types:
Forms = syntaxTree() | [syntaxTree()]
Comment = {Line, Column, Indentation, Text}
Line = integer()
Column = integer()
Indentation = integer()
Text = [string()]
Like recomment_forms/2, but only inserts top-level comments. Comments
within function definitions or declarations ("forms") are simply
ignored.
Types:
syntaxTree() (see module erl_syntax)
Forms = syntaxTree() | [syntaxTree()]
Comment = {Line, Column, Indentation, Text}
Line = integer()
Column = integer()
Indentation = integer()
Text = [string()]
Attaches comments to the syntax tree/trees representing a program. The given
Forms should be a single syntax tree of type form_list, or a
list of syntax trees representing "program forms". The syntax trees
must contain valid position information (for details, see
recomment_tree/2). The result is a corresponding syntax tree of type
form_list in which all comments in the list Comments have been
attached at the proper places.
Assuming Forms represents a program (or any sequence of "program
forms"), any comments whose first lines are not directly associated with
a specific program form will become standalone comments inserted between the
neighbouring program forms. Furthermore, comments whose column position is
less than or equal to one will not be attached to a program form that begins
at a conflicting line number (this can happen with preprocessor-generated
line-attributes).
If Forms is a syntax tree of some other type than form_list, the
comments will be inserted directly using recomment_tree/2, and any
comments left over from that process are added as postcomments on the result.
Entries in Comments represent multi-line comments. For each entry,
Line is the line number and Column the left column of the
comment (the column of the first comment-introducing " %"
character). Indentation is the number of character positions between
the last non-whitespace character before the comment (or the left margin) and
the left column of the comment. Text is a list of strings representing
the consecutive comment lines in top-down order, where each string contains
all characters following (but not including) the comment-introducing "
%" and up to (but not including) the terminating newline. (Cf.
module erl_comment_scan.)
Evaluation exits with reason {bad_position, Pos} if the associated
position information Pos of some subtree in the input does not have a
recognizable format, or with reason {bad_tree, L, C} if insertion of a
comment at line L, column C, fails because the tree structure is
ill-formed.
See also: erl_comment_scan, quick_recomment_forms/2,
recomment_tree/2.
Types:
Comment = {Line, Column, Indentation, Text}
Line = integer()
Column = integer()
Indentation = integer()
Text = [string()]
Attaches comments to a syntax tree. The result is a pair {NewTree,
Remainder} where NewTree is the given Tree where comments
from the list Comments have been attached at the proper places.
Remainder is the list of entries in Comments which have not been
inserted, because their line numbers are greater than those of any node in the
tree. The entries in Comments are inserted in order; if two comments
become attached to the same node, they will appear in the same order in the
program text.
The nodes of the syntax tree must contain valid position information. This can
be single integers, assumed to represent a line number, or 2- or 3-tuples
where the first or second element is an integer, in which case the leftmost
integer element is assumed to represent the line number. Line numbers less
than one are ignored (usually, the default line number for newly created nodes
is zero).
For details on the Line, Column and Indentation fields, and
the behaviour in case of errors, see recomment_forms/2.
See also: recomment_forms/2.
AUTHORS¶
Richard Carlsson <carlsson.richard@gmail.com>syntax_tools 1.6.16 |