1igor(3) Erlang Module Definition igor(3)
2
6 igor - Igor: the Module Merger and Renamer.
7
9 Igor: the Module Merger and Renamer.
10 The program Igor merges the source code of one or more Erlang modules
12 into a single module, which can then replace the original set of mod‐
13 ules. Igor is also able to rename a set of (possibly interdependent)
14 modules, without joining them into a single module.
15 The main user interface consists of the functions merge/3 and rename/3.
17 See also the function parse_transform/2.
18 A note of warning: Igor cannot do anything about the case when the name
20 of a remote function is passed to the built-in functions apply and
21 spawn unless the module and function names are explicitly stated in the
22 call, as in e.g. apply(lists, reverse, [Xs]). In all other cases, Igor
23 leaves such calls unchanged, and warns the user that manual editing
24 might be necessary.
25 Also note that Erlang records will be renamed as necessary to avoid
27 non-equivalent definitions using the same record name. This does not
28 work if the source code accesses the name field of such record tuples
29 by element/2 or similar methods. Always use the record syntax to handle
30 record tuples, if possible.
31 Disclaimer: the author of this program takes no responsibility for the
33 correctness of the produced output, or for any effects of its execu‐
34 tion. In particular, the author may not be held responsible should Igor
35 include the code of a deceased madman in the result.
36 For further information on Igors in general, see e.g. "Young Franken‐
38 stein", Mel Brooks, 1974, and "The Fifth Elephant", Terry Pratchett,
39 1999.
40
42 filename() = file:filename():
43 stubDescriptor() = {ModuleName, Functions, [Attribute]}:
46 * ModuleName = atom()
49 * Functions = [{FunctionName, {ModuleName, FunctionName}}]
51 * FunctionName = {atom(), integer()}
53 * Attribute = {atom(), term()}
55 A stub module descriptor contains the module name, a list of
57 exported functions, and a list of module attributes. Each function
58 is described by its name (which includes its arity), and the corre‐
59 sponding module and function that it calls. (The arities should
60 always match.) The attributes are simply described by key-value
61 pairs.
62 syntaxTree() = erl_syntax:syntaxTree():
64 An abstract syntax tree. See the erl_syntax module for details.
67
69 create_stubs(Stubs::[stubDescriptor()], Options::[term()]) ->
70 [string()]
71 Creates stub module source files corresponding to the given stub
73 descriptors. The returned value is the list of names of the cre‐
74 ated files. See merge_sources/3 for more information about stub
75 descriptors.
76 Options:
78 {backup_suffix, string()}:
80 {backups, boolean()}:
83 {printer, Function}:
86 {stub_dir, filename()}:
89 {suffix, string()}:
92 {verbose, boolean()}:
95 See merge/3 for details on these options.
98 See also: merge/3, merge_sources/3.
100 merge(Name::atom(), Files::[filename()]) -> [filename()]
102 Equivalent to merge(Name, Files, []).
104 merge(Name::atom(), Files::[filename()], Options::[term()]) -> [file‐
106 name()]
107 Merges source code files to a single file. Name specifies the
109 name of the resulting module - not the name of the output file.
110 Files is a list of file names and/or module names of source mod‐
111 ules to be read and merged (see merge_files/4 for details). All
112 the input modules must be distinctly named.
113 The resulting source code is written to a file named
115 "<em>Name</em>.erl" in the current directory, unless otherwise
116 specified by the options dir and outfile described below.
117 Examples:
119 * given a module m in file "m.erl" which uses the standard
121 library module lists, calling igor:merge(m, [m, lists]) will
122 create a new file "m.erl which contains the code from m and
123 exports the same functions, and which includes the refer‐
124 enced code from the lists module. The original file will be
125 renamed to "m.erl.bak".
126 * given modules m1 and m2, in corresponding files, calling
128 igor:merge(m, [m1, m2]) will create a file "m.erl" which
129 contains the code from m1 and m2 and exports the functions
130 of m1.
131 Stub module files are created for those modules that are to be
133 exported by the target module (see options export, stubs and
134 stub_dir).
135 The function returns the list of file names of all created mod‐
137 ules, including any automatically created stub modules. The file
138 name of the target module is always first in the list.
139 Note: If you get a "syntax error" message when trying to merge
141 files (and you know those files to be correct), then try the
142 preprocess option. It typically means that your code contains
143 too strange macros to be handled without actually performing the
144 preprocessor expansions.
145 Options:
147 {backup_suffix, string()}:
149 Specifies the file name suffix to be used when a backup file
150 is created; the default value is ".bak".
151 {backups, boolean()}:
153 If the value is true, existing files will be renamed before
154 new files are opened for writing. The new names are formed
155 by appending the string given by the backup_suffix option to
156 the original name. The default value is true.
157 {dir, filename()}:
159 Specifies the name of the directory in which the output file
160 is to be written. An empty string is interpreted as the cur‐
161 rent directory. By default, the current directory is used.
162 {outfile, filename()}:
164 Specifies the name of the file (without suffix) to which the
165 resulting source code is to be written. By default, this is
166 the same as the Name argument.
167 {preprocess, boolean()}:
169 If the value is true, preprocessing will be done when read‐
170 ing the source code. See merge_files/4 for details.
171 {printer, Function}:
173 * Function = (syntaxTree()) -> string()
176 Specifies a function for prettyprinting Erlang syntax trees.
178 This is used for outputting the resulting module definition,
179 as well as for creating stub files. The function is assumed
180 to return formatted text for the given syntax tree, and
181 should raise an exception if an error occurs. The default
182 formatting function calls erl_prettypr:format/2.
183 {stub_dir, filename()}:
185 Specifies the name of the directory to which any generated
186 stub module files are written. The default value is "stubs".
187 {stubs, boolean()}:
189 If the value is true, stub module files will be automati‐
190 cally generated for all exported modules that do not have
191 the same name as the target module. The default value is
192 true.
193 {suffix, string()}:
195 Specifies the suffix to be used for the output file names;
196 the default value is ".erl".
197 See merge_files/4 for further options.
199 See also: merge/2, merge_files/4.
201 merge_files(Name::atom(), Files::[filename()], Options::[term()]) ->
203 {syntaxTree(), [stubDescriptor()]}
204 Equivalent to merge_files(Name, [], Files, Options).
206 merge_files(Name::atom(), Sources::[Forms], Files::[filename()],
208 Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}
209 Types:
211 Forms = syntaxTree() | [syntaxTree()]
213 Merges source code files and syntax trees to a single syntax
215 tree. This is a file-reading front end to merge_sources/3. Name
216 specifies the name of the resulting module - not the name of the
217 output file. Sources is a list of syntax trees and/or lists of
218 "source code form" syntax trees, each entry representing a mod‐
219 ule definition. Files is a list of file names and/or module
220 names of source modules to be read and included. All the input
221 modules must be distinctly named.
222 If a name in Files is not the name of an existing file, Igor
224 assumes it represents a module name, and tries to locate and
225 read the corresponding source file. The parsed files are
226 appended to Sources and passed on to merge_sources/3, i.e.,
227 entries in Sources are listed before entries read from files.
228 If no exports are listed by an export option (see
230 merge_sources/3 for details), then if Name is also the name of
231 one of the input modules, that module will be exported; other‐
232 wise, the first listed module will be exported. Cf. the examples
233 under merge/3.
234 The result is a pair {Tree, Stubs}, where Tree represents the
236 source code that is the result of merging all the code in
237 Sources and Files, and Stubs is a list of stub module descrip‐
238 tors (see merge_sources/3 for details).
239 Options:
241 {comments, boolean()}:
243 If the value is true, source code comments in the original
244 files will be preserved in the output. The default value is
245 true.
246 {find_src_rules, [{string(), string()}]}:
248 Specifies a list of rules for associating object files with
249 source files, to be passed to the function
250 filelib:find_source/2. This can be used to change the way
251 Igor looks for source files. If this option is not speci‐
252 fied, the default system rules are used. The first occur‐
253 rence of this option completely overrides any later in the
254 option list.
255 {includes, [filename()]}:
257 Specifies a list of directory names for the Erlang pre‐
258 processor, if used, to search for include files (cf. the
259 preprocess option). The default value is the empty list. The
260 directory of the source file and the current directory are
261 automatically appended to the list.
262 {macros, [{atom(), term()}]}:
264 Specifies a list of "pre-defined" macro definitions for the
265 Erlang preprocessor, if used (cf. the preprocess option).
266 The default value is the empty list.
267 {preprocess, boolean()}:
269 If the value is false, Igor will read source files without
270 passing them through the Erlang preprocessor (epp), in order
271 to avoid expansion of preprocessor directives such as
272 -include(...)., -define(...). and -ifdef(...), and macro
273 calls such as ?LINE and ?MY_MACRO(x, y). The default value
274 is false, i.e., preprocessing is not done. (See the module
275 epp_dodger for details.)
276 Notes: If a file contains too exotic definitions or uses of
278 macros, it will not be possible to read it without prepro‐
279 cessing. Furthermore, Igor does not currently try to sort
280 out multiple inclusions of the same file, or redefinitions
281 of the same macro name. Therefore, when preprocessing is
282 turned off, it may become necessary to edit the resulting
283 source code, removing such re-inclusions and redefinitions.
284 See merge_sources/3 for further options.
286 See also: epp_dodger, filelib:find_source/2, merge/3,
288 merge_files/3, merge_sources/3.
289 merge_sources(Name::atom(), Sources::[Forms], Options::[term()]) ->
291 {syntaxTree(), [stubDescriptor()]}
292 Types:
294 Forms = syntaxTree() | [syntaxTree()]
296 Merges syntax trees to a single syntax tree. This is the main
298 code merging "engine". Name specifies the name of the resulting
299 module. Sources is a list of syntax trees of type form_list
300 and/or lists of "source code form" syntax trees, each entry rep‐
301 resenting a module definition. All the input modules must be
302 distinctly named.
303 Unless otherwise specified by the options, all modules are
305 assumed to be at least "static", and all except the target mod‐
306 ule are assumed to be "safe". See the static and safe options
307 for details.
308 If Name is also the name of one of the input modules, the code
310 from that module will occur at the top of the resulting code,
311 and no extra "header" comments will be added. In other words,
312 the look of that module will be preserved.
313 The result is a pair {Tree, Stubs}, where Tree represents the
315 source code that is the result of merging all the code in
316 Sources, and Stubs is a list of stub module descriptors (see
317 below).
318 Stubs contains one entry for each exported input module (cf. the
320 export option), each entry describing a stub module that redi‐
321 rects calls of functions in the original module to the corre‐
322 sponding (possibly renamed) functions in the new module. The
323 stub descriptors can be used to automatically generate stub mod‐
324 ules; see create_stubs/2.
325 Options:
327 {export, [atom()]}:
329 Specifies a list of names of input modules whose interfaces
330 should be exported by the output module. A stub descriptor
331 is generated for each specified module, unless its name is
332 Name. If no modules are specified, then if Name is also the
333 name of an input module, that module will be exported; oth‐
334 erwise the first listed module in Sources will be exported.
335 The default value is the empty list.
336 {export_all, boolean()}:
338 If the value is true, this is equivalent to listing all of
339 the input modules in the export option. The default value is
340 false.
341 {file_attributes, Preserve}:
343 * Preserve = yes | comment | no
346 If the value is yes, all file attributes -file(...) in the
348 input sources will be preserved in the resulting code. If
349 the value is comment, they will be turned into comments, but
350 remain in their original positions in the code relative to
351 the other source code forms. If the value is no, all file
352 attributes will be removed from the code, unless they have
353 attached comments, in which case they will be handled as in
354 the comment case. The default value is no.
355 {no_banner, boolean()}:
357 If the value is true, no banner comment will be added at the
358 top of the resulting module, even if the target module does
359 not have the same name as any of the input modules. Instead,
360 Igor will try to preserve the look of the module whose code
361 is at the top of the output. The default value is false.
362 {no_headers, boolean()}:
364 If the value is true, no header comments will be added to
365 the resulting module at the beginning of each section of
366 code that originates from a particular input module. The
367 default value is false, which means that section headers are
368 normally added whenever more than two or more modules are
369 merged.
370 {no_imports, boolean()}:
372 If the value is true, all -import(...) declarations in the
373 original code will be expanded in the result; otherwise, as
374 much as possible of the original import declarations will be
375 preserved. The default value is false.
376 {notes, Notes}:
378 * Notes = always | yes | no
381 If the value is yes, comments will be inserted where impor‐
383 tant changes have been made in the code. If the value is
384 always, all changes to the code will be commented. If the
385 value is no, changes will be made without comments. The
386 default value is yes.
387 {redirect, [{atom(), atom()}]}:
389 Specifies a list of pairs of module names, representing a
390 mapping from old names to new. The set of old names may not
391 include any of the names of the input modules. All calls to
392 the listed old modules will be rewritten to refer to the
393 corresponding new modules. The redirected calls will not be
394 further processed, even if the new destination is in one of
395 the input modules. This option mainly exists to support mod‐
396 ule renaming; cf. rename/3. The default value is the empty
397 list.
398 {safe, [atom()]}:
400 Specifies a list of names of input modules such that calls
401 to these "safe" modules may be turned into direct local
402 calls, that do not test for code replacement. Typically,
403 this can be done for e.g. standard library modules. If a
404 module is "safe", it is per definition also "static" (cf.
405 below). The list may be empty. By default, all involved mod‐
406 ules except the target module are considered "safe".
407 {static, [atom()]}:
409 Specifies a list of names of input modules which will be
410 assumed never to be replaced (reloaded) unless the target
411 module is also first replaced. The list may be empty. The
412 target module itself (which may also be one of the input
413 modules) is always regarded as "static", regardless of the
414 value of this option. By default, all involved modules are
415 assumed to be static.
416 {tidy, boolean()}:
418 If the value is true, the resulting code will be processed
419 using the erl_tidy module, which removes unused functions
420 and does general code cleanup. (See erl_tidy:module/2 for
421 additional options.) The default value is true.
422 {verbose, boolean()}:
424 If the value is true, progress messages will be output while
425 the program is running; the default value is false.
426 Note: The distinction between "static" and "safe" modules is
428 necessary in order not to break the semantics of dynamic code
429 replacement. A "static" source module will not be replaced
430 unless the target module also is. Now imagine a state machine
431 implemented by placing the code for each state in a separate
432 module, and suppose that we want to merge this into a single
433 target module, marking all source modules as static. At each
434 point in the original code where a call is made from one of the
435 modules to another (i.e., the state transitions), code replace‐
436 ment is expected to be detected. Then, if we in the merged code
437 do not check at these points if the target module (the result of
438 the merge) has been replaced, we can not be sure in general that
439 we will be able to do code replacement of the merged state
440 machine - it could run forever without detecting the code
441 change. Therefore, all such calls must remain remote-calls
442 (detecting code changes), but may call the target module
443 directly.
444 If we are sure that this kind of situation cannot ensue, we may
446 specify the involved modules as "safe", and all calls between
447 them will become local. Note that if the target module itself is
448 specified as safe, "remote" calls to itself will be turned into
449 local calls. This would destroy the code replacement properties
450 of e.g. a typical server loop.
451 See also: create_stubs/2, rename/3, erl_tidy:module/2.
453 parse_transform(Forms::[syntaxTree()], Options::[term()]) -> [syntax‐
455 Tree()]
456 Allows Igor to work as a component of the Erlang compiler.
458 Including the term {parse_transform, igor} in the compile
459 options when compiling an Erlang module (cf. compile:file/2),
460 will call upon Igor to process the source code, allowing auto‐
461 matic inclusion of other source files. No files are created or
462 overwritten when this function is used.
463 Igor will look for terms {igor, List} in the compile options,
465 where List is a list of Igor-specific options, as follows:
466 {files, [filename()]}:
468 The value specifies a list of source files to be merged with
469 the file being compiled; cf. merge_files/4.
470 See merge_files/4 for further options. Note, however, that some
472 options are preset by this function and cannot be overridden by
473 the user; in particular, all cosmetic features are turned off,
474 for efficiency. Preprocessing is turned on.
475 See also: compile:file/2, merge_files/4.
477 rename(Files::[filename()], Renamings) -> [string()]
479 Equivalent to rename(Files, Renamings, []).
481 rename(Files::[filename()], Renamings, Options::[term()]) -> [string()]
483 Types:
485 Renamings = [{atom(), atom()}]
487 Renames a set of possibly interdependent source code modules.
489 Files is a list of file names of source modules to be processed.
490 Renamings is a list of pairs of module names, representing a
491 mapping from old names to new. The returned value is the list of
492 output file names.
493 Each file in the list will be read and processed separately. For
495 every file, each reference to some module M, such that there is
496 an entry {<em>M</em>, <em>M1</em>} in Renamings, will be changed
497 to the corresponding M1. Furthermore, if a file F defines module
498 M, and there is an entry {<em>M</em>, <em>M1</em>} in Renamings,
499 a new file named <em>M1</em>.erl will be created in the same
500 directory as F, containing the source code for module M, renamed
501 to M1. If M does not have an entry in Renamings, the module is
502 not renamed, only updated, and the resulting source code is
503 written to <em>M</em>.erl (typically, this overwrites the origi‐
504 nal file). The suffix option (see below) can be used to change
505 the default ".erl" suffix for the generated files.
506 Stub modules will automatically be created (see the stubs and
508 stub_dir options below) for each module that is renamed. These
509 can be used to redirect any calls still using the old module
510 names. The stub files are created in the same directory as the
511 source file (typically overwriting the original file).
512 Options:
514 {backup_suffix, string()}:
516 {backups, boolean()}:
519 {printer, Function}:
522 {stubs, boolean()}:
525 {suffix, string()}:
528 See merge/3 for details on these options.
531 {comments, boolean()}:
533 {preprocess, boolean()}:
536 See merge_files/4 for details on these options.
539 {no_banner, boolean()}:
541 For the rename function, this option is true by default. See
544 merge_sources/3 for details.
545 {tidy, boolean()}:
547 For the rename function, this option is false by default. See
550 merge_sources/3 for details.
551 {no_headers, boolean()}:
553 {stub_dir, filename()}:
556 These options are preset by the rename function and cannot be
559 overridden by the user.
560 See merge_sources/3 for further options.
562 See also: merge/3, merge_files/4, merge_sources/3.
564
566 Richard Carlsson <carlsson.richard@gmail.com>
567 syntax_tools 2.1.4.1 igor(3)