查看源代码 erl_recomment (syntax_tools v3.2.1)
将注释插入到抽象 Erlang 语法树中
此模块包含用于将注释(通过位置、缩进和文本描述)作为附件添加到抽象语法树的正确位置的函数。
概要
类型
抽象语法树。有关详细信息,请参见 erl_syntax
模块。
类型
-type syntaxTree() :: erl_syntax:syntaxTree().
抽象语法树。有关详细信息,请参见 erl_syntax
模块。
函数
-spec quick_recomment_forms(erl_syntax:forms(), [erl_comment_scan:comment()]) -> syntaxTree().
类似 recomment_forms/2
,但仅插入顶层注释。
函数定义或声明(“forms”)中的注释会被简单地忽略。
-spec recomment_forms(erl_syntax:forms(), [erl_comment_scan:comment()]) -> syntaxTree().
将注释附加到表示程序的语法树/多个语法树。
给定的 Forms
应该是一个类型为 form_list
的单个语法树,或表示“程序 form”的语法树列表。语法树必须包含有效的位置信息(有关详细信息,请参见 recomment_tree/2
)。结果是一个相应的类型为 form_list
的语法树,其中列表 Comments
中的所有注释都已附加到正确的位置。
假设 Forms
表示一个程序(或任何“程序 form”序列),任何其第一行未直接与特定程序 form 关联的注释都将成为插入到相邻程序 form 之间的独立注释。此外,列位置小于或等于 1 的注释不会附加到与冲突行号开始的程序 form(这可能会发生在预处理器生成的 line
属性中)。
如果 Forms
是除 form_list
之外的其他类型的语法树,则注释将直接使用 recomment_tree/2
插入,并且从该过程中剩余的任何注释都将作为后注释添加到结果中。
Comments
中的条目表示多行注释。对于每个条目,Line
是行号,Column
是注释的左列(第一个注释引入字符 "%
" 的列)。 Indentation
是注释之前最后一个非空白字符(或左边距)与注释左列之间的字符位置数。 Text
是一个字符串列表,表示自上而下顺序的连续注释行,其中每个字符串都包含注释引入字符 "%
" 之后(但不包括)以及终止换行符(但不包括)之前的所有字符。(请参见模块 erl_comment_scan
。)
如果输入中某个子树的关联位置信息 Pos
不具有可识别的格式,则求值将以原因 {bad_position, Pos}
退出,如果由于树结构不正确而导致在行 L
、列 C
处插入注释失败,则以原因 {bad_tree, L, C}
退出。
另请参见:erl_comment_scan
、quick_recomment_forms/2
、recomment_tree/2
。
-spec recomment_tree(syntaxTree(), [erl_comment_scan:comment()]) -> {syntaxTree(), [erl_comment_scan:comment()]}.
将注释附加到语法树。
结果是一对 {NewTree, Remainder}
,其中 NewTree
是给定的 Tree
,其中列表 Comments
中的注释已附加到正确的位置。Remainder
是 Comments
中未插入的条目列表,因为它们的行号大于树中任何节点的行号。Comments
中的条目按顺序插入;如果两个注释附加到同一节点,它们将以相同的顺序出现在程序文本中。
语法树的节点必须包含有效的位置信息。这可以是单个整数(假设表示行号),也可以是 2 元组或 3 元组(其中第一个或第二个元素是整数),在这种情况下,最左侧的整数元素被假定为表示行号。小于 1 的行号将被忽略(通常,新创建的节点的默认行号为零)。
有关 Line
、Column
和 Indentation
字段的详细信息,以及发生错误时的行为,请参见 recomment_forms/2
。
另请参见:recomment_forms/2
。