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.

       recomment_forms(Tree::Forms, Comments::[Comment]) -> syntaxTree()

              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.

       recomment_tree(Tree::syntaxTree(), Comments::[Comment]) -> {syntaxTree(), [Comment]}

              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.12                           erl_recomment(3erl)