erl_recomment(3erl)

💖 NAME 💖

erl_recomment — inserting comments into abstract Erlang syntax trees. This is the Erlang Module Definition for erl_recomment(3erl), bestie. 🦋✨

---

✨ DESCRIPTION ✨

Okay so erl_recomment is the module that handles inserting comments into abstract Erlang syntax trees. The comments are described by position, indentation, and text, and this module attaches them onto an abstract syntax tree in the correct places. Slay. 💅

---

🎀 DATA TYPES 🎀

• syntaxTree() = erl_syntax:syntaxTree() — an abstract syntax tree. For the full deets, go look at the erl_syntax module. 👑

---

🌸 EXPORTS 🌸

🫶 quick_recomment_forms/2

quick_recomment_forms(Tree::erl_syntax:forms(),
       Cs::[erl_comment_scan:comment()]) -> erl_syntax:syntaxTree()

Basically like recomment_forms/2, except it only inserts top-level comments. Comments hanging out inside function definitions or declarations ("forms") are simply ignored — not attached, no drama. 🫶

💅 recomment_forms/2

recomment_forms(Tree::erl_syntax:forms(),
       Cs::[erl_comment_scan:comment()]) -> erl_syntax:syntaxTree()

This one attaches comments to the syntax tree/trees that represent a program. Forms should be a single syntax tree of type form_list, or a list of syntax trees representing "program forms". Those syntax trees have to carry valid position information (the details are under recomment_tree/2). The result is a corresponding syntax tree of type form_list where all comments from the Comments list have been attached in 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. Also: 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 get inserted directly using recomment_tree/2, and any comments left over from that process are added as postcomments on the result. 💜

Each entry in Comments represents a multi-line comment. For each entry, Line is the line number and Column is the left column of the comment — meaning 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; 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. It exits 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/2

recomment_tree(Tree::erl_syntax:syntaxTree(),
       Cs::[erl_comment_scan:comment()]) -> {erl_syntax:syntaxTree(),
       [erl_comment_scan:comment()]}

Attaches comments to a syntax tree. The result is a pair {NewTree, Remainder}: NewTree is the given Tree with comments from the list Comments attached in the proper places, and Remainder is the list of entries in Comments that were not inserted because their line numbers are greater than those of any node in the tree. Entries in Comments are inserted in order; if two comments end up attached to the same node, they 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 that 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, plus the behaviour in case of errors, see recomment_forms/2.

See also: recomment_forms/2.

---

💌 AUTHORS 💌

Richard Carlsson <carlsson.richard@gmail.com> — iconic. 🌟

---

That’s the whole page, bestie — brought to you by syntax_tools 3.0.1 and the erl_recomment(3erl) manual page. 💖✨🎀