1erl_recomment(3) Erlang Module Definition erl_recomment(3)
2
6 erl_recomment - Inserting comments into abstract Erlang syntax trees.
7
9 Inserting comments into abstract Erlang syntax trees
10 This module contains functions for inserting comments, described by
12 position, indentation and text, as attachments on an abstract syntax
13 tree, at the correct places.
14
16 syntaxTree() = erl_syntax:syntaxTree():
17 An abstract syntax tree. See the erl_syntax module for details.
20
22 quick_recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()
23 Types:
25 Forms = syntaxTree() | [syntaxTree()]
27 Comment = {Line, Column, Indentation, Text}
28 Line = integer()
29 Column = integer()
30 Indentation = integer()
31 Text = [string()]
32 Like recomment_forms/2, but only inserts top-level comments.
34 Comments within function definitions or declarations ("forms")
35 are simply ignored.
36 recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()
38 Types:
40 Forms = syntaxTree() | [syntaxTree()]
42 Comment = {Line, Column, Indentation, Text}
43 Line = integer()
44 Column = integer()
45 Indentation = integer()
46 Text = [string()]
47 Attaches comments to the syntax tree/trees representing a pro‐
49 gram. The given Forms should be a single syntax tree of type
50 form_list, or a list of syntax trees representing "program
51 forms". The syntax trees must contain valid position information
52 (for details, see recomment_tree/2). The result is a correspond‐
53 ing syntax tree of type form_list in which all comments in the
54 list Comments have been attached at the proper places.
55 Assuming Forms represents a program (or any sequence of "program
57 forms"), any comments whose first lines are not directly associ‐
58 ated with a specific program form will become standalone com‐
59 ments inserted between the neighbouring program forms. Further‐
60 more, comments whose column position is less than or equal to
61 one will not be attached to a program form that begins at a con‐
62 flicting line number (this can happen with preprocessor-gener‐
63 ated line-attributes).
64 If Forms is a syntax tree of some other type than form_list, the
66 comments will be inserted directly using recomment_tree/2, and
67 any comments left over from that process are added as postcom‐
68 ments on the result.
69 Entries in Comments represent multi-line comments. For each
71 entry, Line is the line number and Column the left column of the
72 comment (the column of the first comment-introducing "%" charac‐
73 ter). Indentation is the number of character positions between
74 the last non-whitespace character before the comment (or the
75 left margin) and the left column of the comment. Text is a list
76 of strings representing the consecutive comment lines in top-
77 down order, where each string contains all characters following
78 (but not including) the comment-introducing "%" and up to (but
79 not including) the terminating newline. (Cf. module erl_com‐
80 ment_scan.)
81 Evaluation exits with reason {bad_position, Pos} if the associ‐
83 ated position information Pos of some subtree in the input does
84 not have a recognizable format, or with reason {bad_tree, L, C}
85 if insertion of a comment at line L, column C, fails because the
86 tree structure is ill-formed.
87 See also: erl_comment_scan, quick_recomment_forms/2, recom‐
89 ment_tree/2.
90 recomment_tree(Tree::syntaxTree(), Comments::[Comment]) -> {syntax‐
92 Tree(), [Comment]}
93 Types:
95 Comment = {Line, Column, Indentation, Text}
97 Line = integer()
98 Column = integer()
99 Indentation = integer()
100 Text = [string()]
101 Attaches comments to a syntax tree. The result is a pair
103 {NewTree, Remainder} where NewTree is the given Tree where com‐
104 ments from the list Comments have been attached at the proper
105 places. Remainder is the list of entries in Comments which have
106 not been inserted, because their line numbers are greater than
107 those of any node in the tree. The entries in Comments are
108 inserted in order; if two comments become attached to the same
109 node, they will appear in the same order in the program text.
110 The nodes of the syntax tree must contain valid position infor‐
112 mation. This can be single integers, assumed to represent a line
113 number, or 2- or 3-tuples where the first or second element is
114 an integer, in which case the leftmost integer element is
115 assumed to represent the line number. Line numbers less than one
116 are ignored (usually, the default line number for newly created
117 nodes is zero).
118 For details on the Line, Column and Indentation fields, and the
120 behaviour in case of errors, see recomment_forms/2.
121 See also: recomment_forms/2.
123
125 Richard Carlsson <carlsson.richard@gmail.com>
126 syntax_tools 2.5 erl_recomment(3)