erl_pp(3erl)

1erl_pp(3)                  Erlang Module Definition                  erl_pp(3)
2
3
4

NAME

6       erl_pp - The Erlang pretty printer.
7

DESCRIPTION

9       The functions in this module are used to generate aesthetically attrac‐
10       tive representations of abstract forms, which are suitable  for  print‐
11       ing.  All functions return (possibly deep) lists of characters and gen‐
12       erate an error if the form is wrong.
13
14       All functions can have an optional argument,  which  specifies  a  hook
15       that is called if an attempt is made to print an unknown form.
16
17       Note  that if the functions in this module are used to convert abstract
18       code back to Erlang source code, the enclosing function should first be
19       processed  by legalize_vars/1 in order to ensure that the output is se‐
20       mantically equivalent to the abstract code.
21

DATA TYPES

23       hook_function() =
24           none |
25           fun((Expr :: erl_parse:abstract_expr(),
26                CurrentIndentation :: integer(),
27                CurrentPrecedence :: integer() >= 0,
28                Options :: options()) ->
29                   io_lib:chars())
30
31              Optional argument HookFunction, shown in the functions described
32              in  this  module,  defines a function that is called when an un‐
33              known form occurs where there is to be a  valid  expression.  If
34              HookFunction is equal to none, there is no hook function.
35
36              The  called hook function is to return a (possibly deep) list of
37              characters. Function expr/4 is useful in a hook.
38
39              If CurrentIndentation is negative, there are no line breaks  and
40              only a space is used as a separator.
41
42       option() =
43           {hook, hook_function()} |
44           {encoding, latin1 | unicode | utf8} |
45           {quote_singleton_atom_types, boolean()} |
46           {linewidth, integer() >= 1} |
47           {indent, integer() >= 1}
48
49              The  option  quote_singleton_atom_types is used to add quotes to
50              all singleton atom types.
51
52              The option linewidth controls the maximum line width for format‐
53              ted lines (defaults to 72 characters).
54
55              The  option  indent  controls  the indention for formatted lines
56              (defaults to 4 spaces).
57
58       options() = hook_function() | [option()]
59

EXPORTS

61       attribute(Attribute) -> io_lib:chars()
62
63       attribute(Attribute, Options) -> io_lib:chars()
64
65              Types:
66
67                 Attribute = erl_parse:abstract_form()
68                 Options = options()
69
70              Same as form/1,2, but only for attribute Attribute.
71
72       expr(Expression) -> io_lib:chars()
73
74       expr(Expression, Options) -> io_lib:chars()
75
76       expr(Expression, Indent, Options) -> io_lib:chars()
77
78       expr(Expression, Indent, Precedence, Options) -> io_lib:chars()
79
80              Types:
81
82                 Expression = erl_parse:abstract_expr()
83                 Indent = integer()
84                 Precedence = integer() >= 0
85                 Options = options()
86
87              Prints one expression. It is useful for implementing hooks  (see
88              section Known Limitations).
89
90       exprs(Expressions) -> io_lib:chars()
91
92       exprs(Expressions, Options) -> io_lib:chars()
93
94       exprs(Expressions, Indent, Options) -> io_lib:chars()
95
96              Types:
97
98                 Expressions = [erl_parse:abstract_expr()]
99                 Indent = integer()
100                 Options = options()
101
102              Same  as  form/1,2,  but only for the sequence of expressions in
103              Expressions.
104
105       form(Form) -> io_lib:chars()
106
107       form(Form, Options) -> io_lib:chars()
108
109              Types:
110
111                 Form = erl_parse:abstract_form() | erl_parse:form_info()
112                 Options = options()
113
114              Pretty prints a Form, which is an abstract form of a  type  that
115              is returned by erl_parse:parse_form/1.
116
117       function(Function) -> io_lib:chars()
118
119       function(Function, Options) -> io_lib:chars()
120
121              Types:
122
123                 Function = erl_parse:abstract_form()
124                 Options = options()
125
126              Same as form/1,2, but only for function Function.
127
128       guard(Guard) -> io_lib:chars()
129
130       guard(Guard, Options) -> io_lib:chars()
131
132              Types:
133
134                 Guard = [erl_parse:abstract_expr()]
135                 Options = options()
136
137              Same as form/1,2, but only for the guard test Guard.
138
139       legalize_vars(Function) -> erl_parse:abstract_form()
140
141              Types:
142
143                 Function = erl_parse:abstract_form()
144
145              The  Erlang compiler will, when expanding records to tuples, in‐
146              troduce new variables in the abstract representation. As the ex‐
147              pansion is done on the abstract representation, the compiler can
148              safely name the new variables with names that are not  syntacti‐
149              cally valid in Erlang source code (the name starts with a lower‐
150              case letter), thus ensuring the uniqueness of the new names.
151
152              The above strategy leads to problems if a user wants to  convert
153              the  abstract representation, using the functions of this module
154              back to Erlang source code.  Typically,  pattern  variables  are
155              output  as  atoms  thus changing the sematics of the program. To
156              solve this problem legalize_vars/1, when  run  on  the  abstract
157              representation of a function, will return an equivalent function
158              where all variables will have syntactically valid names.
159

KNOWN LIMITATIONS

161       It is not possible to have hook functions for unknown  forms  at  other
162       places than expressions.
163

NAME

DESCRIPTION

DATA TYPES

EXPORTS

KNOWN LIMITATIONS

SEE ALSO