EVOLUTION-MANAGER

Edit File: igor.3

.TH igor 3 "syntax_tools 1.6.13" "" "Erlang Module Definition"
.SH NAME
igor \- Igor: the Module Merger and Renamer.
.SH DESCRIPTION
.LP
Igor: the Module Merger and Renamer\&.
.LP
The program Igor merges the source code of one or more Erlang modules into a single module, which can then replace the original set of modules\&. Igor is also able to rename a set of (possibly interdependent) modules, without joining them into a single module\&.
.LP
The main user interface consists of the functions \fBmerge/3\fR\& and \fBrename/3\fR\&\&. See also the function \fBparse_transform/2\fR\&\&.
.LP
A note of warning: Igor cannot do anything about the case when the name of a remote function is passed to the built-in functions \fIapply\fR\& and \fIspawn\fR\& \fIunless\fR\& the module and function names are explicitly stated in the call, as in e\&.g\&. \fIapply(lists, reverse, [Xs])\fR\&\&. In all other cases, Igor leaves such calls unchanged, and warns the user that manual editing might be necessary\&.
.LP
Also note that Erlang records will be renamed as necessary to avoid non-equivalent definitions using the same record name\&. This does not work if the source code accesses the name field of such record tuples by \fIelement/2\fR\& or similar methods\&. Always use the record syntax to handle record tuples, if possible\&.
.LP
Disclaimer: the author of this program takes no responsibility for the correctness of the produced output, or for any effects of its execution\&. In particular, the author may not be held responsible should Igor include the code of a deceased madman in the result\&.
.LP
For further information on Igors in general, see e\&.g\&. "Young Frankenstein", Mel Brooks, 1974, and "The Fifth Elephant", Terry Pratchett, 1999\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
\fIstubDescriptor() = {ModuleName, Functions, [Attribute]}\fR\&:

.RS 2
.TP 2
*
\fIModuleName = atom()\fR\&
.LP
.TP 2
*
\fIFunctions = [{FunctionName, {ModuleName, FunctionName}}]\fR\&
.LP
.TP 2
*
\fIFunctionName = {atom(), integer()}\fR\&
.LP
.TP 2
*
\fIAttribute = {atom(), term()}\fR\&
.LP
.RE

.RS 2
.LP
A stub module descriptor contains the module name, a list of exported functions, and a list of module attributes\&. Each function is described by its name (which includes its arity), and the corresponding module and function that it calls\&. (The arities should always match\&.) The attributes are simply described by key-value pairs\&.
.RE
.RE
.SH EXPORTS
.LP
.B
create_stubs(Stubs::[stubDescriptor()], Options::[term()]) -> [string()]
.br
.RS
.LP
Creates stub module source files corresponding to the given stub descriptors\&. The returned value is the list of names of the created files\&. See \fImerge_sources/3\fR\& for more information about stub descriptors\&.
.LP
Options:
.RS 2
.TP 2
.B
\fI{backup_suffix, string()}\fR\&:

.TP 2
.B
\fI{backups, boolean()}\fR\&:

.TP 2
.B
\fI{printer, Function}\fR\&:

.TP 2
.B
\fI{stub_dir, filename()}\fR\&:

.TP 2
.B
\fI{suffix, string()}\fR\&:

.TP 2
.B
\fI{verbose, boolean()}\fR\&:

.RE
.LP
See \fImerge/3\fR\& for details on these options\&.
.LP
\fISee also:\fR\& \fBmerge/3\fR\&, \fBmerge_sources/3\fR\&\&.
.RE
.LP
.B
merge(Name::atom(), Files::[filename()]) -> [filename()]
.br
.RS
.LP
Equivalent to \fBmerge(Name, Files, [])\fR\&\&.
.RE
.LP
.B
merge(Name::atom(), Files::[filename()], Options::[term()]) -> [filename()]
.br
.RS
.LP
Types:

.RS 3
filename() (see module file)
.br
.RE
.RE
.RS
.LP
Merges source code files to a single file\&. \fIName\fR\& specifies the name of the resulting module - not the name of the output file\&. \fIFiles\fR\& is a list of file names and/or module names of source modules to be read and merged (see \fImerge_files/4\fR\& for details)\&. All the input modules must be distinctly named\&.
.LP
The resulting source code is written to a file named "\fIName\&.erl\fR\&" in the current directory, unless otherwise specified by the options \fIdir\fR\& and \fIoutfile\fR\& described below\&.
.LP
Examples:
.RS 2
.TP 2
*
given a module \fIm\fR\& in file "\fIm\&.erl\fR\&" which uses the standard library module \fIlists\fR\&, calling \fIigor:merge(m, [m, lists])\fR\& will create a new file "\fIm\&.erl\fR\& which contains the code from \fIm\fR\& and exports the same functions, and which includes the referenced code from the \fIlists\fR\& module\&. The original file will be renamed to "\fIm\&.erl\&.bak\fR\&"\&.
.LP
.TP 2
*
given modules \fIm1\fR\& and \fIm2\fR\&, in corresponding files, calling \fIigor:merge(m, [m1, m2])\fR\& will create a file "\fIm\&.erl\fR\&" which contains the code from \fIm1\fR\& and \fIm2\fR\& and exports the functions of \fIm1\fR\&\&.
.LP
.RE

.LP
Stub module files are created for those modules that are to be exported by the target module (see options \fIexport\fR\&, \fIstubs\fR\& and \fIstub_dir\fR\&)\&.
.LP
The function returns the list of file names of all created modules, including any automatically created stub modules\&. The file name of the target module is always first in the list\&.
.LP
Note: If you get a "syntax error" message when trying to merge files (and you know those files to be correct), then try the \fIpreprocess\fR\& option\&. It typically means that your code contains too strange macros to be handled without actually performing the preprocessor expansions\&.
.LP
Options:
.RS 2
.TP 2
.B
\fI{backup_suffix, string()}\fR\&:
Specifies the file name suffix to be used when a backup file is created; the default value is \fI"\&.bak"\fR\&\&.
.TP 2
.B
\fI{backups, boolean()}\fR\&:
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
\fI{dir, filename()}\fR\&:
Specifies the name of the directory in which the output file is to be written\&. An empty string is interpreted as the current directory\&. By default, the current directory is used\&.
.TP 2
.B
\fI{outfile, filename()}\fR\&:
Specifies the name of the file (without suffix) to which the resulting source code is to be written\&. By default, this is the same as the \fIName\fR\& argument\&.
.TP 2
.B
\fI{preprocess, boolean()}\fR\&:
If the value is \fItrue\fR\&, preprocessing will be done when reading the source code\&. See \fImerge_files/4\fR\& for details\&.
.TP 2
.B
\fI{printer, Function}\fR\&:

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

.RS 2
.LP
Specifies a function for prettyprinting Erlang syntax trees\&. This is used for outputting the resulting module definition, as well as for creating stub files\&. 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
\fI{stub_dir, filename()}\fR\&:
Specifies the name of the directory to which any generated stub module files are written\&. The default value is \fI"stubs"\fR\&\&.
.TP 2
.B
\fI{stubs, boolean()}\fR\&:
If the value is \fItrue\fR\&, stub module files will be automatically generated for all exported modules that do not have the same name as the target module\&. The default value is \fItrue\fR\&\&.
.TP 2
.B
\fI{suffix, string()}\fR\&:
Specifies the suffix to be used for the output file names; the default value is \fI"\&.erl"\fR\&\&.
.RE
.LP
See \fImerge_files/4\fR\& for further options\&.
.LP
\fISee also:\fR\& \fBmerge/2\fR\&, \fBmerge_files/4\fR\&\&.
.RE
.LP
.B
merge_files(Name::atom(), Files::[filename()], Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}
.br
.RS
.LP
Equivalent to \fBmerge_files(Name, [], Files, Options)\fR\&\&.
.RE
.LP
.B
merge_files(Name::atom(), Sources::[Forms], Files::[filename()], Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}
.br
.RS
.LP
Types:

.RS 3
Forms = syntaxTree() | [syntaxTree()]
.br
.RE
.RE
.RS
.LP
Merges source code files and syntax trees to a single syntax tree\&. This is a file-reading front end to \fImerge_sources/3\fR\&\&. \fIName\fR\& specifies the name of the resulting module - not the name of the output file\&. \fISources\fR\& is a list of syntax trees and/or lists of "source code form" syntax trees, each entry representing a module definition\&. \fIFiles\fR\& is a list of file names and/or module names of source modules to be read and included\&. All the input modules must be distinctly named\&.
.LP
If a name in \fIFiles\fR\& is not the name of an existing file, Igor assumes it represents a module name, and tries to locate and read the corresponding source file\&. The parsed files are appended to \fISources\fR\& and passed on to \fImerge_sources/3\fR\&, i\&.e\&., entries in \fISources\fR\& are listed before entries read from files\&.
.LP
If no exports are listed by an \fIexport\fR\& option (see \fImerge_sources/3\fR\& for details), then if \fIName\fR\& is also the name of one of the input modules, that module will be exported; otherwise, the first listed module will be exported\&. Cf\&. the examples under \fImerge/3\fR\&\&.
.LP
The result is a pair \fI{Tree, Stubs}\fR\&, where \fITree\fR\& represents the source code that is the result of merging all the code in \fISources\fR\& and \fIFiles\fR\&, and \fIStubs\fR\& is a list of stub module descriptors (see \fImerge_sources/3\fR\& for details)\&.
.LP
Options:
.RS 2
.TP 2
.B
\fI{comments, boolean()}\fR\&:
If the value is \fItrue\fR\&, source code comments in the original files will be preserved in the output\&. The default value is \fItrue\fR\&\&.
.TP 2
.B
\fI{find_src_rules, [{string(), string()}]}\fR\&:
Specifies a list of rules for associating object files with source files, to be passed to the function \fIfilename:find_src/2\fR\&\&. This can be used to change the way Igor looks for source files\&. If this option is not specified, the default system rules are used\&. The first occurrence of this option completely overrides any later in the option list\&.
.TP 2
.B
\fI{includes, [filename()]}\fR\&:
Specifies a list of directory names for the Erlang preprocessor, if used, to search for include files (cf\&. the \fIpreprocess\fR\& option)\&. The default value is the empty list\&. The directory of the source file and the current directory are automatically appended to the list\&.
.TP 2
.B
\fI{macros, [{atom(), term()}]}\fR\&:
Specifies a list of "pre-defined" macro definitions for the Erlang preprocessor, if used (cf\&. the \fIpreprocess\fR\& option)\&. The default value is the empty list\&.
.TP 2
.B
\fI{preprocess, boolean()}\fR\&:
If the value is \fIfalse\fR\&, Igor will read source files without passing them through the Erlang preprocessor (\fIepp\fR\&), in order to avoid expansion of preprocessor directives such as \fI-include(\&.\&.\&.)\&.\fR\&, \fI-define(\&.\&.\&.)\&.\fR\& and \fI-ifdef(\&.\&.\&.)\fR\&, and macro calls such as \fI?LINE\fR\& and \fI?MY_MACRO(x, y)\fR\&\&. The default value is \fIfalse\fR\&, i\&.e\&., preprocessing is not done\&. (See the module \fIepp_dodger\fR\& for details\&.)
.RS 2
.LP
Notes: If a file contains too exotic definitions or uses of macros, it will not be possible to read it without preprocessing\&. Furthermore, Igor does not currently try to sort out multiple inclusions of the same file, or redefinitions of the same macro name\&. Therefore, when preprocessing is turned off, it may become necessary to edit the resulting source code, removing such re-inclusions and redefinitions\&.
.RE
.RE
.LP
See \fImerge_sources/3\fR\& for further options\&.
.LP
\fISee also:\fR\& \fBepp_dodger\fR\&, \fBfilename:find_src/2\fR\&, \fBmerge/3\fR\&, \fBmerge_files/3\fR\&, \fBmerge_sources/3\fR\&\&.
.RE
.LP
.B
merge_sources(Name::atom(), Sources::[Forms], Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}
.br
.RS
.LP
Types:

.RS 3
Forms = syntaxTree() | [syntaxTree()]
.br
.RE
.RE
.RS
.LP
Merges syntax trees to a single syntax tree\&. This is the main code merging "engine"\&. \fIName\fR\& specifies the name of the resulting module\&. \fISources\fR\& is a list of syntax trees of type \fIform_list\fR\& and/or lists of "source code form" syntax trees, each entry representing a module definition\&. All the input modules must be distinctly named\&.
.LP
Unless otherwise specified by the options, all modules are assumed to be at least "static", and all except the target module are assumed to be "safe"\&. See the \fIstatic\fR\& and \fIsafe\fR\& options for details\&.
.LP
If \fIName\fR\& is also the name of one of the input modules, the code from that module will occur at the top of the resulting code, and no extra "header" comments will be added\&. In other words, the look of that module will be preserved\&.
.LP
The result is a pair \fI{Tree, Stubs}\fR\&, where \fITree\fR\& represents the source code that is the result of merging all the code in \fISources\fR\&, and \fIStubs\fR\& is a list of stub module descriptors (see below)\&.
.LP
\fIStubs\fR\& contains one entry for each exported input module (cf\&. the \fIexport\fR\& option), each entry describing a stub module that redirects calls of functions in the original module to the corresponding (possibly renamed) functions in the new module\&. The stub descriptors can be used to automatically generate stub modules; see \fIcreate_stubs/2\fR\&\&.
.LP
Options:
.RS 2
.TP 2
.B
\fI{export, [atom()]}\fR\&:
Specifies a list of names of input modules whose interfaces should be exported by the output module\&. A stub descriptor is generated for each specified module, unless its name is \fIName\fR\&\&. If no modules are specified, then if \fIName\fR\& is also the name of an input module, that module will be exported; otherwise the first listed module in \fISources\fR\& will be exported\&. The default value is the empty list\&.
.TP 2
.B
\fI{export_all, boolean()}\fR\&:
If the value is \fItrue\fR\&, this is equivalent to listing all of the input modules in the \fIexport\fR\& option\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
\fI{file_attributes, Preserve}\fR\&:

.RS 2
.TP 2
*
\fIPreserve = yes | comment | no\fR\&
.LP
.RE

.RS 2
.LP
If the value is \fIyes\fR\&, all file attributes \fI-file(\&.\&.\&.)\fR\& in the input sources will be preserved in the resulting code\&. If the value is \fIcomment\fR\&, they will be turned into comments, but remain in their original positions in the code relative to the other source code forms\&. If the value is \fIno\fR\&, all file attributes will be removed from the code, unless they have attached comments, in which case they will be handled as in the \fIcomment\fR\& case\&. The default value is \fIno\fR\&\&.
.RE
.TP 2
.B
\fI{no_banner, boolean()}\fR\&:
If the value is \fItrue\fR\&, no banner comment will be added at the top of the resulting module, even if the target module does not have the same name as any of the input modules\&. Instead, Igor will try to preserve the look of the module whose code is at the top of the output\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
\fI{no_headers, boolean()}\fR\&:
If the value is \fItrue\fR\&, no header comments will be added to the resulting module at the beginning of each section of code that originates from a particular input module\&. The default value is \fIfalse\fR\&, which means that section headers are normally added whenever more than two or more modules are merged\&.
.TP 2
.B
\fI{no_imports, boolean()}\fR\&:
If the value is \fItrue\fR\&, all \fI-import(\&.\&.\&.)\fR\& declarations in the original code will be expanded in the result; otherwise, as much as possible of the original import declarations will be preserved\&. The default value is \fIfalse\fR\&\&.
.TP 2
.B
\fI{notes, Notes}\fR\&:

.RS 2
.TP 2
*
\fINotes = always | yes | no\fR\&
.LP
.RE

.RS 2
.LP
If the value is \fIyes\fR\&, comments will be inserted where important changes have been made in the code\&. If the value is \fIalways\fR\&, \fIall\fR\& changes to the code will be commented\&. If the value is \fIno\fR\&, changes will be made without comments\&. The default value is \fIyes\fR\&\&.
.RE
.TP 2
.B
\fI{redirect, [{atom(), atom()}]}\fR\&:
Specifies a list of pairs of module names, representing a mapping from old names to new\&. \fIThe set of old names may not include any of the names of the input modules\&.\fR\& All calls to the listed old modules will be rewritten to refer to the corresponding new modules\&. \fIThe redirected calls will not be further processed, even if the new destination is in one of the input modules\&.\fR\& This option mainly exists to support module renaming; cf\&. \fIrename/3\fR\&\&. The default value is the empty list\&.
.TP 2
.B
\fI{safe, [atom()]}\fR\&:
Specifies a list of names of input modules such that calls to these "safe" modules may be turned into direct local calls, that do not test for code replacement\&. Typically, this can be done for e\&.g\&. standard library modules\&. If a module is "safe", it is per definition also "static" (cf\&. below)\&. The list may be empty\&. By default, all involved modules \fIexcept the target module\fR\& are considered "safe"\&.
.TP 2
.B
\fI{static, [atom()]}\fR\&:
Specifies a list of names of input modules which will be assumed never to be replaced (reloaded) unless the target module is also first replaced\&. The list may be empty\&. The target module itself (which may also be one of the input modules) is always regarded as "static", regardless of the value of this option\&. By default, all involved modules are assumed to be static\&.
.TP 2
.B
\fI{tidy, boolean()}\fR\&:
If the value is \fItrue\fR\&, the resulting code will be processed using the \fIerl_tidy\fR\& module, which removes unused functions and does general code cleanup\&. (See \fIerl_tidy:module/2\fR\& for additional options\&.) The default value is \fItrue\fR\&\&.
.TP 2
.B
\fI{verbose, boolean()}\fR\&:
If the value is \fItrue\fR\&, progress messages will be output while the program is running; the default value is \fIfalse\fR\&\&.
.RE
.LP
Note: The distinction between "static" and "safe" modules is necessary in order not to break the semantics of dynamic code replacement\&. A "static" source module will not be replaced unless the target module also is\&. Now imagine a state machine implemented by placing the code for each state in a separate module, and suppose that we want to merge this into a single target module, marking all source modules as static\&. At each point in the original code where a call is made from one of the modules to another (i\&.e\&., the state transitions), code replacement is expected to be detected\&. Then, if we in the merged code do not check at these points if the \fItarget\fR\& module (the result of the merge) has been replaced, we can not be sure in general that we will be able to do code replacement of the merged state machine - it could run forever without detecting the code change\&. Therefore, all such calls must remain remote-calls (detecting code changes), but may call the target module directly\&.
.LP
If we are sure that this kind of situation cannot ensue, we may specify the involved modules as "safe", and all calls between them will become local\&. Note that if the target module itself is specified as safe, "remote" calls to itself will be turned into local calls\&. This would destroy the code replacement properties of e\&.g\&. a typical server loop\&.
.LP
\fISee also:\fR\& \fBcreate_stubs/2\fR\&, \fBrename/3\fR\&, \fBerl_tidy:module/2\fR\&\&.
.RE
.LP
.B
parse_transform(Forms::[syntaxTree()], Options::[term()]) -> [syntaxTree()]
.br
.RS
.LP
Types:

.RS 3
syntaxTree() (see module erl_syntax)
.br
.RE
.RE
.RS
.LP
Allows Igor to work as a component of the Erlang compiler\&. Including the term \fI{parse_transform, igor}\fR\& in the compile options when compiling an Erlang module (cf\&. \fIcompile:file/2\fR\&), will call upon Igor to process the source code, allowing automatic inclusion of other source files\&. No files are created or overwritten when this function is used\&.
.LP
Igor will look for terms \fI{igor, List}\fR\& in the compile options, where \fIList\fR\& is a list of Igor-specific options, as follows:
.RS 2
.TP 2
.B
\fI{files, [filename()]}\fR\&:
The value specifies a list of source files to be merged with the file being compiled; cf\&. \fImerge_files/4\fR\&\&.
.RE
.LP
See \fImerge_files/4\fR\& for further options\&. Note, however, that some options are preset by this function and cannot be overridden by the user; in particular, all cosmetic features are turned off, for efficiency\&. Preprocessing is turned on\&.
.LP
\fISee also:\fR\& \fBcompile:file/2\fR\&, \fBmerge_files/4\fR\&\&.
.RE
.LP
.B
rename(Files::[filename()], Renamings) -> [string()]
.br
.RS
.LP
Equivalent to \fBrename(Files, Renamings, [])\fR\&\&.
.RE
.LP
.B
rename(Files::[filename()], Renamings, Options::[term()]) -> [string()]
.br
.RS
.LP
Types:

.RS 3
Renamings = [{atom(), atom()}]
.br
.RE
.RE
.RS
.LP
Renames a set of possibly interdependent source code modules\&. \fIFiles\fR\& is a list of file names of source modules to be processed\&. \fIRenamings\fR\& is a list of pairs of \fImodule names\fR\&, representing a mapping from old names to new\&. The returned value is the list of output file names\&.
.LP
Each file in the list will be read and processed separately\&. For every file, each reference to some module M, such that there is an entry \fI{M, M1}\fR\& in \fIRenamings\fR\&, will be changed to the corresponding M1\&. Furthermore, if a file F defines module M, and there is an entry \fI{M, M1}\fR\& in \fIRenamings\fR\&, a new file named \fIM1\&.erl\fR\& will be created in the same directory as F, containing the source code for module M, renamed to M1\&. If M does not have an entry in \fIRenamings\fR\&, the module is not renamed, only updated, and the resulting source code is written to \fIM\&.erl\fR\& (typically, this overwrites the original file)\&. The \fIsuffix\fR\& option (see below) can be used to change the default "\fI\&.erl\fR\&" suffix for the generated files\&.
.LP
Stub modules will automatically be created (see the \fIstubs\fR\& and \fIstub_dir\fR\& options below) for each module that is renamed\&. These can be used to redirect any calls still using the old module names\&. The stub files are created in the same directory as the source file (typically overwriting the original file)\&.
.LP
Options:
.RS 2
.TP 2
.B
\fI{backup_suffix, string()}\fR\&:

.TP 2
.B
\fI{backups, boolean()}\fR\&:

.TP 2
.B
\fI{printer, Function}\fR\&:

.TP 2
.B
\fI{stubs, boolean()}\fR\&:

.TP 2
.B
\fI{suffix, string()}\fR\&:

.RE
.LP
See \fImerge/3\fR\& for details on these options\&.
.RS 2
.TP 2
.B
\fI{comments, boolean()}\fR\&:

.TP 2
.B
\fI{preprocess, boolean()}\fR\&:

.RE
.LP
See \fImerge_files/4\fR\& for details on these options\&.
.RS 2
.TP 2
.B
\fI{no_banner, boolean()}\fR\&:

.RE
.LP
For the \fIrename\fR\& function, this option is \fItrue\fR\& by default\&. See \fImerge_sources/3\fR\& for details\&.
.RS 2
.TP 2
.B
\fI{tidy, boolean()}\fR\&:

.RE
.LP
For the \fIrename\fR\& function, this option is \fIfalse\fR\& by default\&. See \fImerge_sources/3\fR\& for details\&.
.RS 2
.TP 2
.B
\fI{no_headers, boolean()}\fR\&:

.TP 2
.B
\fI{stub_dir, filename()}\fR\&:

.RE
.LP
These options are preset by the \fIrename\fR\& function and cannot be overridden by the user\&.
.LP
See \fImerge_sources/3\fR\& for further options\&.
.LP
\fISee also:\fR\& \fBmerge/3\fR\&, \fBmerge_files/4\fR\&, \fBmerge_sources/3\fR\&\&.
.RE
.SH AUTHORS
.LP
Richard Carlsson
.I
<carlsson\&.richard@gmail\&.com>