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

NAME

6       igor - Igor: the Module Merger and Renamer.
7

DESCRIPTION

9       Igor: the Module Merger and Renamer.
10
11       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
16       The main user interface consists of the functions merge/3 and rename/3.
17       See also the function parse_transform/2.
18
19       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
26       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
32       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
37       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

DATA TYPES

42         filename() = file:filename():
43
44
45         stubDescriptor() = {ModuleName, Functions, [Attribute]}:
46
47
48           * ModuleName = atom()
49
50           * Functions = [{FunctionName, {ModuleName, FunctionName}}]
51
52           * FunctionName = {atom(), integer()}
53
54           * Attribute = {atom(), term()}
55
56           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
63         syntaxTree() = erl_syntax:syntaxTree():
64
65
66           An abstract syntax tree. See the erl_syntax module for details.
67

EXPORTS

69       create_stubs(Stubs::[stubDescriptor()],      Options::[term()])      ->
70       [string()]
71
72              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
77              Options:
78
79                {backup_suffix, string()}:
80
81
82                {backups, boolean()}:
83
84
85                {printer, Function}:
86
87
88                {stub_dir, filename()}:
89
90
91                {suffix, string()}:
92
93
94                {verbose, boolean()}:
95
96
97              See merge/3 for details on these options.
98
99              See also: merge/3, merge_sources/3.
100
101       merge(Name::atom(), Files::[filename()]) -> [filename()]
102
103              Equivalent to merge(Name, Files, []).
104
105       merge(Name::atom(), Files::[filename()], Options::[term()])  ->  [file‐
106       name()]
107
108              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
114              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
118              Examples:
119
120                * 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
127                * 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
132              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
136              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
140              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
146              Options:
147
148                {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
152                {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
158                {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
163                {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
168                {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
172                {printer, Function}:
173
174
175                  * Function = (syntaxTree()) -> string()
176
177                  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
184                {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
188                {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
194                {suffix, string()}:
195                  Specifies  the  suffix to be used for the output file names;
196                  the default value is ".erl".
197
198              See merge_files/4 for further options.
199
200              See also: merge/2, merge_files/4.
201
202       merge_files(Name::atom(),  Files::[filename()],  Options::[term()])  ->
203       {syntaxTree(), [stubDescriptor()]}
204
205              Equivalent to merge_files(Name, [], Files, Options).
206
207       merge_files(Name::atom(),     Sources::[Forms],    Files::[filename()],
208       Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}
209
210              Types:
211
212                 Forms = syntaxTree() | [syntaxTree()]
213
214              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
223              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
229              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
235              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
240              Options:
241
242                {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
247                {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
256                {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
263                {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
268                {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
277                  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
285              See merge_sources/3 for further options.
286
287              See   also:    epp_dodger,    filelib:find_source/2,    merge/3,
288              merge_files/3, merge_sources/3.
289
290       merge_sources(Name::atom(),   Sources::[Forms],  Options::[term()])  ->
291       {syntaxTree(), [stubDescriptor()]}
292
293              Types:
294
295                 Forms = syntaxTree() | [syntaxTree()]
296
297              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
304              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
309              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
314              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
319              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
326              Options:
327
328                {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
337                {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
342                {file_attributes, Preserve}:
343
344
345                  * Preserve = yes | comment | no
346
347                  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
356                {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
363                {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
371                {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
377                {notes, Notes}:
378
379
380                  * Notes = always | yes | no
381
382                  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
388                {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
399                {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
408                {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
417                {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
423                {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
427              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 cannot 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
445              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
452              See also: create_stubs/2, rename/3, erl_tidy:module/2.
453
454       parse_transform(Forms::[syntaxTree()],  Options::[term()])  -> [syntax‐
455       Tree()]
456
457              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
464              Igor  will  look  for terms {igor, List} in the compile options,
465              where List is a list of Igor-specific options, as follows:
466
467                {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
471              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
476              See also: compile:file/2, merge_files/4.
477
478       rename(Files::[filename()], Renamings) -> [string()]
479
480              Equivalent to rename(Files, Renamings, []).
481
482       rename(Files::[filename()], Renamings, Options::[term()]) -> [string()]
483
484              Types:
485
486                 Renamings = [{atom(), atom()}]
487
488              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
494              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
507              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
513              Options:
514
515                {backup_suffix, string()}:
516
517
518                {backups, boolean()}:
519
520
521                {printer, Function}:
522
523
524                {stubs, boolean()}:
525
526
527                {suffix, string()}:
528
529
530              See merge/3 for details on these options.
531
532                {comments, boolean()}:
533
534
535                {preprocess, boolean()}:
536
537
538              See merge_files/4 for details on these options.
539
540                {no_banner, boolean()}:
541
542
543              For  the  rename  function,  this option is true by default. See
544              merge_sources/3 for details.
545
546                {tidy, boolean()}:
547
548
549              For the rename function, this option is false  by  default.  See
550              merge_sources/3 for details.
551
552                {no_headers, boolean()}:
553
554
555                {stub_dir, filename()}:
556
557
558              These  options  are  preset by the rename function and cannot be
559              overridden by the user.
560
561              See merge_sources/3 for further options.
562
563              See also: merge/3, merge_files/4, merge_sources/3.
564

AUTHORS

566       Richard Carlsson <carlsson.richard@gmail.com>
567
568
569
570                              syntax_tools 2.2.1                       igor(3)
Impressum