Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
erl_recomment(3)	   Erlang Module Definition	      erl_recomment(3)

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 po-
       sition, indentation and text, as	 attachments  on  an  abstract	syntax
       tree, at	the correct places.

DATA TYPES
	 syntaxTree() =	erl_syntax:syntaxTree():

	   An abstract syntax tree. See	the erl_syntax module for details.

EXPORTS
       quick_recomment_forms(Tree::erl_syntax:forms(),		 Cs::[erl_com-
       ment_scan:comment()]) ->	erl_syntax:syntaxTree()

	      Like recomment_forms/2, but  only	 inserts  top-level  comments.
	      Comments	within	function definitions or	declarations ("forms")
	      are simply ignored.

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

	      Attaches	comments  to the syntax	tree/trees representing	a pro-
	      gram. 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 correspond-
	      ing 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 associ-
	      ated  with  a  specific program form will	become standalone com-
	      ments inserted between the neighbouring program forms.  Further-
	      more,  comments  whose  column position is less than or equal to
	      one will not be attached to a program form that begins at	a con-
	      flicting	line  number (this can happen with preprocessor-gener-
	      ated 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  postcom-
	      ments on the result.

	      Entries  in Comments represent multi-line	comments. For each en-
	      try, Line	is the line number and Column the left column  of  the
	      comment (the column of the first comment-introducing "%" charac-
	      ter). 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_com-
	      ment_scan.)

	      Evaluation  exits	with reason {bad_position, Pos}	if the associ-
	      ated 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,	recom-
	      ment_tree/2.

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

	      Attaches comments	to  a  syntax  tree.  The  result  is  a  pair
	      {NewTree,	 Remainder} where NewTree is the given Tree where com-
	      ments 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 in-
	      serted 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	infor-
	      mation. 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  as-
	      sumed  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 2.6		      erl_recomment(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=erl_recomment&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help