.TH erl_tidy 3erl "syntax_tools 2.4" "" "Erlang Module Definition"
.SH NAME
erl_tidy \- Tidies and pretty-prints Erlang source code, removing unused  
functions, updating obsolete constructs and function calls, etc.
.SH DESCRIPTION
.LP
Tidies and pretty-prints Erlang source code, removing unused functions, updating obsolete constructs and function calls, etc\&.
.LP
Caveats: It is possible that in some intricate uses of macros, the automatic addition or removal of parentheses around uses or arguments could cause the resulting program to be rejected by the compiler; however, we have found no such case in existing code\&. Programs defining strange macros can usually not be read by this program, and in those cases, no changes will be made\&.
.LP
If you really, really want to, you may call it "Inga"\&.
.LP
Disclaimer: The author accepts no responsibility for errors introduced in code that has been processed by the program\&. It has been reasonably well tested, but the possibility of errors remains\&. Keep backups of your original code safely stored, until you feel confident that the new, modified code can be trusted\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
filename() = file:filename():

.TP 2
.B
syntaxTree() = erl_syntax:syntaxTree():

.RS 2
.LP
An abstract syntax tree\&. See the erl_syntax module for details\&.
.RE

.RE
.SH EXPORTS
.LP
.B
dir() -> ok
.br
.RS
.LP
Equivalent to dir("")\&.
.RE

.LP
.B
dir(Dir) -> ok
.br
.RS
.LP
Equivalent to dir(Dir, [])\&.
.RE

.LP
.B
dir(Directory::filename(), Options::[term()]) -> ok
.br
.RS
.LP
Tidies Erlang source files in a directory and its subdirectories\&.
.LP
Available options:
.RS 2
.TP 2
.B
{follow_links, boolean()}:
If the value is \fItrue\fR\&, symbolic directory links will be followed\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{recursive, boolean()}:
If the value is \fItrue\fR\&, subdirectories will be visited recursively\&. The default value is \fItrue\fR\&\&.
.TP 2
.B
{regexp, string()}:
The value denotes a regular expression (see module \fIre\fR\&)\&. Tidying will only be applied to those regular files whose names match this pattern\&. The default value is \fI"\&.*\\\\\&.erl$"\fR\&, which matches normal Erlang source file names\&.
.TP 2
.B
{test, boolean()}:
If the value is \fItrue\fR\&, no files will be modified\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{verbose, boolean()}:
If the value is \fItrue\fR\&, progress messages will be output while the program is running, unless the \fIquiet\fR\& option is \fItrue\fR\&\&. The default value when calling dir/2 is \fItrue\fR\&\&.
.RE
.LP
See the function file/2 for further options\&.
.LP
\fISee also:\fR\& re(3erl), file/2\&.
.RE

.LP
.B
file(Name) -> ok
.br
.RS
.LP
Equivalent to file(Name, [])\&.
.RE

.LP
.B
file(Name::filename(), Options::[term()]) -> ok
.br
.RS
.LP
Tidies an Erlang source code file\&.
.LP
Available options are:
.RS 2
.TP 2
.B
{backup_suffix, string()}:
Specifies the file name suffix to be used when a backup file is created; the default value is \fI"\&.bak"\fR\& (cf\&. the \fIbackups\fR\& option)\&.
.TP 2
.B
{backups, boolean()}:
If the value is \fItrue\fR\&, existing files will be renamed before new files are opened for writing\&. The new names are formed by appending the string given by the \fIbackup_suffix\fR\& option to the original name\&. The default value is \fItrue\fR\&\&.
.TP 2
.B
{dir, filename()}:
Specifies the name of the directory in which the output file is to be written\&. By default, the current directory is used\&. If the value is an empty string, the current directory is used\&.
.TP 2
.B
{outfile, filename()}:
Specifies the name of the file (without suffix) to which the resulting source code is to be written\&. If this option is not specified, the \fIName\fR\& argument is used\&.
.TP 2
.B
{printer, Function}:

.RS 2
.TP 2
*
\fIFunction = (syntaxTree(), [term()]) -> string()\fR\&
.LP
.RE

.RS 2
.LP
Specifies a function for prettyprinting Erlang syntax trees\&. This is used for outputting the resulting module definition\&. The function is assumed to return formatted text for the given syntax tree, and should raise an exception if an error occurs\&. The default formatting function calls \fIerl_prettypr:format/2\fR\&\&.
.RE

.TP 2
.B
{test, boolean()}:
If the value is \fItrue\fR\&, no files will be modified; this is typically most useful if the \fIverbose\fR\& flag is enabled, to generate reports about the program files without affecting them\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{stdout, boolean()}:
If the value is \fItrue\fR\&, instead of the file being written to disk it will be printed to stdout\&. The default value is \fIfalse\fR\&\&.
.RE
.LP
See the function \fImodule/2\fR\& for further options\&.
.LP
\fISee also:\fR\& module/2, erl_prettypr:format/2\&.
.RE

.LP
.B
module(Forms) -> syntaxTree()
.br
.RS
.LP
Equivalent to module(Forms, [])\&.
.RE

.LP
.B
module(Forms, Options::[term()]) -> syntaxTree()
.br
.RS
.LP
Types:

.RS 3
Forms = syntaxTree() | [syntaxTree()]
.br
.RE
.RE
.RS
.LP
Tidies a syntax tree representation of a module definition\&. The given \fIForms\fR\& may be either a single syntax tree of type \fIform_list\fR\&, or a list of syntax trees representing "program forms"\&. In either case, \fIForms\fR\& must represent a single complete module definition\&. The returned syntax tree has type \fIform_list\fR\& and represents a tidied-up version of the same source code\&.
.LP
Available options are:
.RS 2
.TP 2
.B
{auto_export_vars, boolean()}:
If the value is \fItrue\fR\&, all matches "\fI{V1, \&.\&.\&., Vn} = E\fR\&" where \fIE\fR\& is a case-, if- or receive-expression whose branches all return n-tuples (or explicitly throw exceptions) will be rewritten to bind and export the variables \fIV1\fR\&, \&.\&.\&., \fIVn\fR\& directly\&. The default value is \fIfalse\fR\&\&.
.RS 2
.LP
For example:
.RE

.LP
.nf

                 {X, Y} = case ... of
                              ... -> {17, foo()};
                              ... -> {42, bar()}
                          end
        
.fi
.RS 2
.LP
will be rewritten to:
.RE

.LP
.nf

                 case ... of
                     ... -> X = 17, Y = foo(), {X, Y};
                     ... -> X = 42, Y = bar(), {X, Y}
                 end
        
.fi
.TP 2
.B
{auto_list_comp, boolean()}:
If the value is \fItrue\fR\&, calls to \fIlists:map/2\fR\& and \fIlists:filter/2\fR\& will be rewritten using list comprehensions\&. The default value is \fItrue\fR\&\&.
.TP 2
.B
{file, string()}:
Specifies the name of the file from which the source code was taken\&. This is only used for generation of error reports\&. The default value is the empty string\&.
.TP 2
.B
{idem, boolean()}:
If the value is \fItrue\fR\&, all options that affect how the code is modified are set to "no changes"\&. For example, to only update guard tests, and nothing else, use the options \fI[new_guard_tests, idem]\fR\&\&. (Recall that options closer to the beginning of the list have higher precedence\&.)
.TP 2
.B
{keep_unused, boolean()}:
If the value is \fItrue\fR\&, unused functions will not be removed from the code\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{new_guard_tests, boolean()}:
If the value is \fItrue\fR\&, guard tests will be updated to use the new names, e\&.g\&. "\fIis_integer(X)\fR\&" instead of "\fIinteger(X)\fR\&"\&. The default value is \fItrue\fR\&\&. See also \fIold_guard_tests\fR\&\&.
.TP 2
.B
{no_imports, boolean()}:
If the value is \fItrue\fR\&, all import statements will be removed and calls to imported functions will be expanded to explicit remote calls\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{old_guard_tests, boolean()}:
If the value is \fItrue\fR\&, guard tests will be changed to use the old names instead of the new ones, e\&.g\&. "\fIinteger(X)\fR\&" instead of "\fIis_integer(X)\fR\&"\&. The default value is \fIfalse\fR\&\&. This option overrides the \fInew_guard_tests\fR\& option\&.
.TP 2
.B
{quiet, boolean()}:
If the value is \fItrue\fR\&, all information messages and warning messages will be suppressed\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
{rename, [{{atom(), atom(), integer()}, {atom(), atom()}}]}:
The value is a list of pairs, associating tuples \fI{Module, Name, Arity}\fR\& with tuples \fI{NewModule, NewName}\fR\&, specifying renamings of calls to remote functions\&. By default, the value is the empty list\&.
.RS 2
.LP
The renaming affects only remote calls (also when disguised by import declarations); local calls within a module are not affected, and no function definitions are renamed\&. Since the arity cannot change, the new name is represented by \fI{NewModule, NewName}\fR\& only\&. Only calls matching the specified arity will match; multiple entries are necessary for renaming calls to functions that have the same module and function name, but different arities\&.
.RE

.RS 2
.LP
This option can also be used to override the default renaming of calls which use obsolete function names\&.
.RE

.TP 2
.B
{verbose, boolean()}:
If the value is \fItrue\fR\&, progress messages will be output while the program is running, unless the \fIquiet\fR\& option is \fItrue\fR\&\&. The default value is \fIfalse\fR\&\&.
.RE
.RE

.SH AUTHORS
.LP
Richard Carlsson
.I
<carlsson\&.richard@gmail\&.com>