1erl_recomment(3)           Erlang Module Definition           erl_recomment(3)
2
3
4

NAME

6       erl_recomment - Inserting comments into abstract Erlang syntax trees.
7

DESCRIPTION

9       Inserting comments into abstract Erlang syntax trees
10
11       This module contains functions for inserting comments, described by po‐
12       sition, indentation and text, as  attachments  on  an  abstract  syntax
13       tree, at the correct places.
14

DATA TYPES

16         syntaxTree() = erl_syntax:syntaxTree():
17
18
19           An abstract syntax tree. See the erl_syntax module for details.
20

EXPORTS

22       quick_recomment_forms(Tree::erl_syntax:forms(),           Cs::[erl_com‐
23       ment_scan:comment()]) -> erl_syntax:syntaxTree()
24
25              Like recomment_forms/2, but  only  inserts  top-level  comments.
26              Comments  within  function definitions or declarations ("forms")
27              are simply ignored.
28
29       recomment_forms(Tree::erl_syntax:forms(),    Cs::[erl_comment_scan:com‐
30       ment()]) -> erl_syntax:syntaxTree()
31
32              Attaches  comments  to the syntax tree/trees representing a pro‐
33              gram. The given Forms should be a single  syntax  tree  of  type
34              form_list,  or  a  list  of  syntax  trees representing "program
35              forms". The syntax trees must contain valid position information
36              (for details, see recomment_tree/2). The result is a correspond‐
37              ing syntax tree of type form_list in which all comments  in  the
38              list Comments have been attached at the proper places.
39
40              Assuming Forms represents a program (or any sequence of "program
41              forms"), any comments whose first lines are not directly associ‐
42              ated  with  a  specific program form will become standalone com‐
43              ments inserted between the neighbouring program forms.  Further‐
44              more,  comments  whose  column position is less than or equal to
45              one will not be attached to a program form that begins at a con‐
46              flicting  line  number (this can happen with preprocessor-gener‐
47              ated line-attributes).
48
49              If Forms is a syntax tree of some other type than form_list, the
50              comments  will  be inserted directly using recomment_tree/2, and
51              any comments left over from that process are added  as  postcom‐
52              ments on the result.
53
54              Entries  in Comments represent multi-line comments. For each en‐
55              try, Line is the line number and Column the left column  of  the
56              comment (the column of the first comment-introducing "%" charac‐
57              ter). Indentation is the number of character  positions  between
58              the  last  non-whitespace  character  before the comment (or the
59              left margin) and the left column of the comment. Text is a  list
60              of  strings  representing  the consecutive comment lines in top-
61              down order, where each string contains all characters  following
62              (but  not  including) the comment-introducing "%" and up to (but
63              not including) the terminating  newline.  (Cf.  module  erl_com‐
64              ment_scan.)
65
66              Evaluation  exits with reason {bad_position, Pos} if the associ‐
67              ated position information Pos of some subtree in the input  does
68              not  have a recognizable format, or with reason {bad_tree, L, C}
69              if insertion of a comment at line L, column C, fails because the
70              tree structure is ill-formed.
71
72              See   also:  erl_comment_scan,  quick_recomment_forms/2,  recom‐
73              ment_tree/2.
74
75       recomment_tree(Tree::erl_syntax:syntaxTree(),             Cs::[erl_com‐
76       ment_scan:comment()])     ->     {erl_syntax:syntaxTree(),    [erl_com‐
77       ment_scan:comment()]}
78
79              Attaches comments to  a  syntax  tree.  The  result  is  a  pair
80              {NewTree,  Remainder} where NewTree is the given Tree where com‐
81              ments from the list Comments have been attached  at  the  proper
82              places.  Remainder is the list of entries in Comments which have
83              not been inserted, because their line numbers are  greater  than
84              those  of  any node in the tree. The entries in Comments are in‐
85              serted in order; if two comments become  attached  to  the  same
86              node, they will appear in the same order in the program text.
87
88              The  nodes of the syntax tree must contain valid position infor‐
89              mation. This can be single integers, assumed to represent a line
90              number,  or  2- or 3-tuples where the first or second element is
91              an integer, in which case the leftmost integer  element  is  as‐
92              sumed  to  represent the line number. Line numbers less than one
93              are ignored (usually, the default line number for newly  created
94              nodes is zero).
95
96              For  details on the Line, Column and Indentation fields, and the
97              behaviour in case of errors, see recomment_forms/2.
98
99              See also: recomment_forms/2.
100

AUTHORS

102       Richard Carlsson <carlsson.richard@gmail.com>
103
104
105
106                               syntax_tools 3.1               erl_recomment(3)
Impressum