GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       igor - Igor: the Module Merger and Renamer.

DESCRIPTION

       Igor: the Module Merger and Renamer.

       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.

       The main user interface consists of the functions merge/3 and rename/3.
       See also the function parse_transform/2.

       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  apply  and
       spawn unless the module and function names are explicitly stated in the
       call, as in e.g. apply(lists, reverse, [Xs]). In all other cases,  Igor
       leaves  such  calls  unchanged,  and warns the user that manual editing
       might be necessary.

       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 element/2 or similar methods. Always use the record syntax to handle
       record tuples, if possible.

       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.

       For   further   information  on  Igors  in  general,  see  e.g.  "Young
       Frankenstein", Mel  Brooks,  1974,  and  "The  Fifth  Elephant",  Terry
       Pratchett, 1999.

DATA TYPES

         stubDescriptor() = {ModuleName, Functions, [Attribute]}:

           * ModuleName = atom()

           * Functions = [{FunctionName, {ModuleName, FunctionName}}]

           * FunctionName = {atom(), integer()}

           * Attribute = {atom(), term()}

           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.

EXPORTS

       create_stubs(Stubs::[stubDescriptor()],      Options::[term()])      ->
       [string()]

              Creates stub module source files corresponding to the given stub
              descriptors. The returned value is the  list  of  names  of  the
              created  files.  See  merge_sources/3 for more information about
              stub descriptors.

              Options:

                {backup_suffix, string()}:

                {backups, boolean()}:

                {printer, Function}:

                {stub_dir, filename()}:

                {suffix, string()}:

                {verbose, boolean()}:

              See merge/3 for details on these options.

              See also: merge/3, merge_sources/3.

       merge(Name::atom(), Files::[filename()]) -> [filename()]

              Equivalent to merge(Name, Files, []).

       merge(Name::atom(),    Files::[filename()],    Options::[term()])    ->
       [filename()]

              Types:

                 filename() (see module file)

              Merges  source  code  files to a single file. Name specifies the
              name of the resulting module - not the name of the output  file.
              Files  is  a  list  of  file names and/or module names of source
              modules to be read and merged (see merge_files/4  for  details).
              All the input modules must be distinctly named.

              The   resulting   source   code  is  written  to  a  file  named
              "<em>Name</em>.erl" in the current directory,  unless  otherwise
              specified by the options dir and outfile described below.

              Examples:

                * given  a  module  m  in file "m.erl" which uses the standard
                  library module lists, calling igor:merge(m, [m, lists]) will
                  create  a new file "m.erl which contains the code from m and
                  exports  the  same  functions,  and   which   includes   the
                  referenced  code  from  the  lists module. The original file
                  will be renamed to "m.erl.bak".

                * given modules m1 and m2,  in  corresponding  files,  calling
                  igor:merge(m,  [m1,  m2])  will  create a file "m.erl" which
                  contains the code from m1 and m2 and exports  the  functions
                  of m1.

              Stub  module  files are created for those modules that are to be
              exported by the target module (see  options  export,  stubs  and
              stub_dir).

              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.

              Note:  If  you get a "syntax error" message when trying to merge
              files (and you know those files to be  correct),  then  try  the
              preprocess  option.  It  typically means that your code contains
              too strange macros to be handled without actually performing the
              preprocessor expansions.

              Options:

                {backup_suffix, string()}:
                  Specifies the file name suffix to be used when a backup file
                  is created; the default value is ".bak".

                {backups, boolean()}:
                  If the value is true, existing files will be renamed  before
                  new  files  are opened for writing. The new names are formed
                  by appending the string given by the backup_suffix option to
                  the original name. The default value is true.

                {dir, filename()}:
                  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.

                {outfile, filename()}:
                  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 Name argument.

                {preprocess, boolean()}:
                  If the value  is  true,  preprocessing  will  be  done  when
                  reading the source code. See merge_files/4 for details.

                {printer, Function}:

                  * Function = (syntaxTree()) -> string()

                  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 erl_prettypr:format/2.

                {stub_dir, filename()}:
                  Specifies the name of the directory to which  any  generated
                  stub module files are written. The default value is "stubs".

                {stubs, boolean()}:
                  If   the   value   is   true,  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 true.

                {suffix, string()}:
                  Specifies the suffix to be used for the output  file  names;
                  the default value is ".erl".

              See merge_files/4 for further options.

              See also: merge/2, merge_files/4.

       merge_files(Name::atom(),  Files::[filename()],  Options::[term()])  ->
       {syntaxTree(), [stubDescriptor()]}

              Equivalent to merge_files(Name, [], Files, Options).

       merge_files(Name::atom(),    Sources::[Forms],     Files::[filename()],
       Options::[term()]) -> {syntaxTree(), [stubDescriptor()]}

              Types:

                 Forms = syntaxTree() | [syntaxTree()]

              Merges  source  code  files  and syntax trees to a single syntax
              tree. This is a file-reading front end to merge_sources/3.  Name
              specifies the name of the resulting module - not the name of the
              output file. Sources is a list of syntax trees and/or  lists  of
              "source  code  form"  syntax  trees,  each  entry representing a
              module definition. Files 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.

              If a name in Files 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  Sources  and  passed  on to merge_sources/3, i.e.,
              entries in Sources are listed before entries read from files.

              If  no  exports  are   listed   by   an   export   option   (see
              merge_sources/3  for  details), then if Name 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 merge/3.

              The result is a pair {Tree, Stubs}, where  Tree  represents  the
              source  code  that  is  the  result  of  merging all the code in
              Sources  and  Files,  and  Stubs  is  a  list  of  stub   module
              descriptors (see merge_sources/3 for details).

              Options:

                {comments, boolean()}:
                  If  the  value is true, source code comments in the original
                  files will be preserved in the output. The default value  is
                  true.

                {find_src_rules, [{string(), string()}]}:
                  Specifies  a list of rules for associating object files with
                  source   files,   to   be    passed    to    the    function
                  filename:find_src/2. 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.

                {includes, [filename()]}:
                  Specifies  a  list  of  directory  names  for   the   Erlang
                  preprocessor,  if used, to search for include files (cf. the
                  preprocess option). The default value is the empty list. The
                  directory  of  the source file and the current directory are
                  automatically appended to the list.

                {macros, [{atom(), term()}]}:
                  Specifies a list of "pre-defined" macro definitions for  the
                  Erlang  preprocessor,  if  used (cf. the preprocess option).
                  The default value is the empty list.

                {preprocess, boolean()}:
                  If the value is false, Igor will read source  files  without
                  passing them through the Erlang preprocessor (epp), in order
                  to  avoid  expansion  of  preprocessor  directives  such  as
                  -include(...).,  -define(...).  and  -ifdef(...),  and macro
                  calls such as ?LINE and ?MY_MACRO(x, y). The  default  value
                  is  false,  i.e., preprocessing is not done. (See the module
                  epp_dodger for details.)

                  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.

              See merge_sources/3 for further options.

              See     also:    epp_dodger,    filename:find_src/2,    merge/3,
              merge_files/3, merge_sources/3.

       merge_sources(Name::atom(),  Sources::[Forms],  Options::[term()])   ->
       {syntaxTree(), [stubDescriptor()]}

              Types:

                 Forms = syntaxTree() | [syntaxTree()]

              Merges  syntax  trees  to a single syntax tree. This is the main
              code merging "engine". Name specifies the name of the  resulting
              module.  Sources  is  a  list  of syntax trees of type form_list
              and/or lists of "source code  form"  syntax  trees,  each  entry
              representing  a module definition. All the input modules must be
              distinctly named.

              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 static and safe options
              for details.

              If  Name  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.

              The result is a pair {Tree, Stubs}, where  Tree  represents  the
              source  code  that  is  the  result  of  merging all the code in
              Sources, and Stubs is a list of  stub  module  descriptors  (see
              below).

              Stubs contains one entry for each exported input module (cf. the
              export  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 create_stubs/2.

              Options:

                {export, [atom()]}:
                  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
                  Name.  If no modules are specified, then if Name is also the
                  name of an input  module,  that  module  will  be  exported;
                  otherwise  the  first  listed  module  in  Sources  will  be
                  exported. The default value is the empty list.

                {export_all, boolean()}:
                  If the value is true, this is equivalent to listing  all  of
                  the input modules in the export option. The default value is
                  false.

                {file_attributes, Preserve}:

                  * Preserve = yes | comment | no

                  If the value is yes, all file attributes -file(...)  in  the
                  input  sources  will  be preserved in the resulting code. If
                  the value is comment, 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  no,  all  file
                  attributes  will  be removed from the code, unless they have
                  attached comments, in which case they will be handled as  in
                  the comment case. The default value is no.

                {no_banner, boolean()}:
                  If the value is true, 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 false.

                {no_headers, boolean()}:
                  If  the  value  is true, 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 false, which means that section headers are
                  normally  added  whenever  more than two or more modules are
                  merged.

                {no_imports, boolean()}:
                  If the value is true, all -import(...) 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 false.

                {notes, Notes}:

                  * Notes = always | yes | no

                  If  the  value  is  yes,  comments  will  be  inserted where
                  important changes have been made in the code. If  the  value
                  is always, all changes to the code will be commented. If the
                  value is no, changes will  be  made  without  comments.  The
                  default value is yes.

                {redirect, [{atom(), atom()}]}:
                  Specifies  a  list  of pairs of module names, representing a
                  mapping from old names to new. The set of old names may  not
                  include  any of the names of the input modules. All calls to
                  the listed old modules will be rewritten  to  refer  to  the
                  corresponding  new modules. The redirected calls will not be
                  further processed, even if the new destination is in one  of
                  the  input  modules.  This  option  mainly exists to support
                  module renaming; cf. rename/3.  The  default  value  is  the
                  empty list.

                {safe, [atom()]}:
                  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 except the target module are considered "safe".

                {static, [atom()]}:
                  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.

                {tidy, boolean()}:
                  If  the  value is true, the resulting code will be processed
                  using the erl_tidy module, which  removes  unused  functions
                  and  does  general  code cleanup. (See erl_tidy:module/2 for
                  additional options.) The default value is true.

                {verbose, boolean()}:
                  If the value is true, progress messages will be output while
                  the program is running; the default value is false.

              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 target 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.

              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.

              See also: create_stubs/2, rename/3, erl_tidy:module/2.

       parse_transform(Forms::[syntaxTree()],      Options::[term()])       ->
       [syntaxTree()]

              Types:

                 syntaxTree() (see module erl_syntax)

              Allows  Igor  to  work  as  a  component of the Erlang compiler.
              Including  the  term  {parse_transform,  igor}  in  the  compile
              options  when  compiling  an Erlang module (cf. compile:file/2),
              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.

              Igor will look for terms {igor, List} in  the  compile  options,
              where List is a list of Igor-specific options, as follows:

                {files, [filename()]}:
                  The value specifies a list of source files to be merged with
                  the file being compiled; cf. merge_files/4.

              See merge_files/4 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.

              See also: compile:file/2, merge_files/4.

       rename(Files::[filename()], Renamings) -> [string()]

              Equivalent to rename(Files, Renamings, []).

       rename(Files::[filename()], Renamings, Options::[term()]) -> [string()]

              Types:

                 Renamings = [{atom(), atom()}]

              Renames  a  set  of possibly interdependent source code modules.
              Files is a list of file names of source modules to be processed.
              Renamings  is  a  list  of pairs of module names, representing a
              mapping from old names to new. The returned value is the list of
              output file names.

              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 {<em>M</em>, <em>M1</em>} in Renamings, will be changed
              to the corresponding M1. Furthermore, if a file F defines module
              M, and there is an entry {<em>M</em>, <em>M1</em>} in Renamings,
              a new file named <em>M1</em>.erl 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 Renamings, the  module  is
              not  renamed,  only  updated,  and  the resulting source code is
              written  to  <em>M</em>.erl  (typically,  this  overwrites   the
              original  file).  The  suffix  option (see below) can be used to
              change the default ".erl" suffix for the generated files.

              Stub modules will automatically be created (see  the  stubs  and
              stub_dir  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).

              Options:

                {backup_suffix, string()}:

                {backups, boolean()}:

                {printer, Function}:

                {stubs, boolean()}:

                {suffix, string()}:

              See merge/3 for details on these options.

                {comments, boolean()}:

                {preprocess, boolean()}:

              See merge_files/4 for details on these options.

                {no_banner, boolean()}:

              For the rename function, this option is  true  by  default.  See
              merge_sources/3 for details.

                {tidy, boolean()}:

              For  the  rename  function, this option is false by default. See
              merge_sources/3 for details.

                {no_headers, boolean()}:

                {stub_dir, filename()}:

              These options are preset by the rename function  and  cannot  be
              overridden by the user.

              See merge_sources/3 for further options.

              See also: merge/3, merge_files/4, merge_sources/3.

AUTHORS

       Richard Carlsson <carlsson.richard@gmail.com>

                              syntax_tools 1.6.15                   igor(3erl)



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.087 seconds. Last modified: November 04 2018 12:49:43.