PageRenderTime 57ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/lib/syntax_tools/doc/igor.html

http://github.com/gebi/jungerl
HTML | 581 lines | 565 code | 16 blank | 0 comment | 0 complexity | 74bf0d6df36654de4ef261f96c1aee98 MD5 | raw file
Possible License(s): AGPL-1.0, JSON, LGPL-2.1, BSD-3-Clause
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <html>
  3. <head>
  4. <title>Module igor</title>
  5. <link rel="stylesheet" type="text/css" href="stylesheet.css">
  6. </head>
  7. <body bgcolor="white">
  8. <h1>Module igor</h1>
  9. Igor: the Module Merger and Renamer.<ul><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul><h2><a name="description">Description</a></h2>Igor: the Module Merger and Renamer.
  10. <p>The program Igor merges the source code of one or more Erlang
  11. modules into a single module, which can then replace the original set
  12. of modules. Igor is also able to rename a set of (possibly
  13. interdependent) modules, without joining them into a single
  14. module.</p>
  15. <p>The main user interface consists of the functions <a href="#merge-3"><code>merge</code></a> and <a href="#rename-3"><code>rename</code></a>. See also the <a href="#parse_transform-2"><code>parse_transform</code></a>
  16. function</p>
  17. <p>A note of warning: Igor cannot do anything about the case when the
  18. name of a remote function is passed to the built-in functions
  19. <code>apply</code> and <code>spawn</code> <em>unless</em> the module
  20. and function names are explicitly stated in the call, as in e.g.
  21. <code>apply(lists, reverse, [Xs])</code>. In all other cases, Igor
  22. leaves such calls unchanged, and warns the user that manual editing
  23. might be necessary.</p>
  24. <p>Also note that Erlang records will be renamed as necessary to
  25. avoid non-equivalent definitions using the same record name. This
  26. does not work if the source code accesses the name field of such
  27. record tuples by <code>element/2</code> or similar methods. Always
  28. use the record syntax to handle record tuples, if possible.</p>
  29. <p>Disclaimer: the author of this program takes no responsibility for
  30. the correctness of the produced output, or for any effects of its
  31. execution. In particular, the author may not be held responsible
  32. should Igor include the code of a deceased madman in the result.</p>
  33. <p>For further information on Igors in general, see e.g. "Young
  34. Frankenstein", Mel Brooks, 1974, and "The Fifth Elephant", Terry
  35. Pratchett, 1999.</p>
  36. <h2><a name="types">Data Types</a></h2>
  37. <h3><a name="type-stubDescriptor">stubDescriptor()</a></h3>
  38. <p><tt>stubDescriptor() = [{ModuleName, Functions, [Attribute]}]</tt>
  39. <ul><li><tt>ModuleName = atom()</tt></li><li><tt>Functions = [{FunctionName, {ModuleName, FunctionName}}]</tt></li><li><tt>FunctionName = {atom(), integer()}</tt></li><li><tt>Attribute = {atom(), term()}</tt></li></ul></p>
  40. <p>A stub module descriptor contains the module name, a list of
  41. exported functions, and a list of module attributes. Each
  42. function is described by its name (which includes its arity),
  43. and the corresponding module and function that it calls. (The
  44. arities should always match.) The attributes are simply
  45. described by key-value pairs.
  46. </p>
  47. <h2><a name="index">Function Index</a></h2>
  48. <table width="100%" border="1"><tr><td valign="top"><a href="#create_stubs-2">create_stubs/2</a></td><td>Creates stub module source files corresponding to the given stub
  49. descriptors.</td></tr>
  50. <tr><td valign="top"><a href="#merge-2">merge/2</a></td><td><p>Equivalent to <a href="#merge-3"><tt>merge(Name, Files, [])</tt></a>.</p>
  51. </td></tr>
  52. <tr><td valign="top"><a href="#merge-3">merge/3</a></td><td>Merges source code files to a single file.</td></tr>
  53. <tr><td valign="top"><a href="#merge_files-3">merge_files/3</a></td><td><p>Equivalent to <a href="#merge_files-4"><tt>merge_files(Name, [], Files, Options)</tt></a>.</p>
  54. </td></tr>
  55. <tr><td valign="top"><a href="#merge_files-4">merge_files/4</a></td><td>Merges source code files and syntax trees to a single syntax
  56. tree.</td></tr>
  57. <tr><td valign="top"><a href="#merge_sources-3">merge_sources/3</a></td><td>Merges syntax trees to a single syntax tree.</td></tr>
  58. <tr><td valign="top"><a href="#parse_transform-2">parse_transform/2</a></td><td>Allows Igor to work as a component of the Erlang compiler.</td></tr>
  59. <tr><td valign="top"><a href="#rename-2">rename/2</a></td><td><p>Equivalent to <a href="#rename-3"><tt>rename(Files, Renamings, [])</tt></a>.</p>
  60. </td></tr>
  61. <tr><td valign="top"><a href="#rename-3">rename/3</a></td><td>Renames a set of possibly interdependent source code modules.</td></tr>
  62. </table>
  63. <h2><a name="functions">Function Details</a></h2>
  64. <h3><a name="create_stubs-2">create_stubs/2</a></h3>
  65. <p><tt>create_stubs(Stubs::[<a href="#type-stubDescriptor">stubDescriptor()</a>], Options::[term()]) -&gt; [string()]</tt></p>
  66. <p>Creates stub module source files corresponding to the given stub
  67. descriptors. The returned value is the list of names of the created
  68. files. See <code>merge_sources/3</code> for more information about
  69. stub descriptors.
  70. <p>Options:
  71. <dl>
  72. <dt><code>{backup_suffix, string()}</code></dt>
  73. <dt><code>{backups, bool()}</code></dt>
  74. <dt><code>{printer, Function}</code></dt>
  75. <dt><code>{stub_dir, filename()}</code></dt>
  76. <dt><code>{suffix, string()}</code></dt>
  77. <dt><code>{verbose, bool()}</code></dt>
  78. </dl>
  79. See <code>merge/3</code> for details on these options.</p>
  80. </p>
  81. <p><b>See also:</b> <a href="#merge-3">merge/3</a>, <a href="#merge_sources-3">merge_sources/3</a>.</p>
  82. <h3><a name="merge-2">merge/2</a></h3>
  83. <p><tt>merge(Name::atom(), Files::[<a href="#type-filename">filename()</a>]) -&gt; [<a href="#type-filename">filename()</a>]</tt></p>
  84. <p>Equivalent to <a href="#merge-3"><tt>merge(Name, Files, [])</tt></a>.</p>
  85. <h3><a name="merge-3">merge/3</a></h3>
  86. <p><tt>merge(Name::atom(), Files::[<a href="#type-filename">filename()</a>], Options::[term()]) -&gt; [<a href="#type-filename">filename()</a>]</tt>
  87. <ul><li><tt><a name="type-filename">filename()</a> = <a href="/usr/local/home/richardc/hipe/otp/lib/kernel/doc/file.html#type-filename">file:filename()</a></tt></li></ul></p>
  88. <p>Merges source code files to a single file. <code>Name</code>
  89. specifies the name of the resulting module - not the name of the
  90. output file. <code>Files</code> is a list of file names and/or module
  91. names of source modules to be read and merged (see
  92. <code>merge_files/4</code> for details). All the input modules must
  93. be distinctly named.
  94. <p>The resulting source code is written to a file named
  95. "<code><em>Name</em>.erl</code>" in the current directory, unless
  96. otherwise specified by the options <code>dir</code> and
  97. <code>outfile</code> described below.</p>
  98. <p>Examples:
  99. <ul>
  100. <li>given a module <code>m</code> in file "<code>m.erl</code>"
  101. which uses the standard library module <code>lists</code>, calling
  102. <code>igor:merge(m, [m, lists])</code> will create a new file
  103. "<code>m.erl</code> which contains the code from <code>m</code> and
  104. exports the same functions, and which includes the referenced code
  105. from the <code>lists</code> module. The original file will be
  106. renamed to "<code>m.erl.bak</code>".</li>
  107. <li>given modules <code>m1</code> and <code>m2</code>, in
  108. corresponding files, calling <code>igor:merge(m, [m1, m2])</code>
  109. will create a file "<code>m.erl</code>" which contains the code
  110. from <code>m1</code> and <code>m2</code> and exports the functions
  111. of <code>m1</code>.</li>
  112. </ul></p>
  113. <p>Stub module files are created for those modules that are to be
  114. exported by the target module (see options <code>export</code>,
  115. <code>stubs</code> and <code>stub_dir</code>).</p>
  116. <p>The function returns the list of file names of all created
  117. modules, including any automatically created stub modules. The file
  118. name of the target module is always first in the list.</p>
  119. <p>Note: If you get a "syntax error" message when trying to merge
  120. files (and you know those files to be correct), then try the
  121. <code>preprocess</code> option. It typically means that your code
  122. contains too strange macros to be handled without actually performing
  123. the preprocessor expansions.</p>
  124. <p>Options:
  125. <dl>
  126. <dt><code>{backup_suffix, string()}</code></dt>
  127. <dd>Specifies the file name suffix to be used when a backup file
  128. is created; the default value is <code>".bak"</code>.</dd>
  129. <dt><code>{backups, bool()}</code></dt>
  130. <dd>If the value is <code>true</code>, existing files will be
  131. renamed before new files are opened for writing. The new names
  132. are formed by appending the string given by the
  133. <code>backup_suffix</code> option to the original name. The
  134. default value is <code>true</code>.</dd>
  135. <dt><code>{dir, filename()}</code></dt>
  136. <dd>Specifies the name of the directory in which the output file
  137. is to be written. An empty string is interpreted as the current
  138. directory. By default, the current directory is used.</dd>
  139. <dt><code>{outfile, filename()}</code></dt>
  140. <dd>Specifies the name of the file (without suffix) to which the
  141. resulting source code is to be written. By default, this is the
  142. same as the <code>Name</code> argument.</dd>
  143. <dt><code>{preprocess, bool()}</code></dt>
  144. <dd>If the value is <code>true</code>, preprocessing will be done
  145. when reading the source code. See <code>merge_files/4</code> for
  146. details.</dd>
  147. <dt><code>{printer, Function}</code></dt>
  148. <dd><ul>
  149. <li><code>Function = (syntaxTree()) -&gt; string()</code></li>
  150. </ul>
  151. Specifies a function for prettyprinting Erlang syntax trees.
  152. This is used for outputting the resulting module definition, as
  153. well as for creating stub files. The function is assumed to
  154. return formatted text for the given syntax tree, and should raise
  155. an exception if an error occurs. The default formatting function
  156. calls <code>erl_prettypr:format/2</code>.</dd>
  157. <dt><code>{stub_dir, filename()}</code></dt>
  158. <dd>Specifies the name of the directory to which any generated
  159. stub module files are written. The default value is
  160. <code>"stubs"</code>.</dd>
  161. <dt><code>{stubs, bool()}</code></dt>
  162. <dd>If the value is <code>true</code>, stub module files will be
  163. automatically generated for all exported modules that do not have
  164. the same name as the target module. The default value is
  165. <code>true</code>.</dd>
  166. <dt><code>{suffix, string()}</code></dt>
  167. <dd>Specifies the suffix to be used for the output file names;
  168. the default value is <code>".erl"</code>.</dd>
  169. </dl>
  170. See <code>merge_files/4</code> for further options.</p>
  171. </p>
  172. <p><b>See also:</b> <a href="#merge-2">merge/2</a>, <a href="#merge_files-4">merge_files/4</a>.</p>
  173. <h3><a name="merge_files-3">merge_files/3</a></h3>
  174. <p><tt>merge_files(Name::atom(), Files::[<a href="#type-filename">filename()</a>], Options::[term()]) -&gt; {<a href="#type-syntaxTree">syntaxTree()</a>, [<a href="#type-stubDescriptor">stubDescriptor()</a>]}</tt></p>
  175. <p>Equivalent to <a href="#merge_files-4"><tt>merge_files(Name, [], Files, Options)</tt></a>.</p>
  176. <h3><a name="merge_files-4">merge_files/4</a></h3>
  177. <p><tt>merge_files(Name::atom(), Sources::[Forms], Files::[<a href="#type-filename">filename()</a>], Options::[term()]) -&gt; {<a href="#type-syntaxTree">syntaxTree()</a>, [<a href="#type-stubDescriptor">stubDescriptor()</a>]}</tt>
  178. <ul><li><tt>Forms = <a href="#type-syntaxTree">syntaxTree()</a> | [<a href="#type-syntaxTree">syntaxTree()</a>]</tt></li></ul></p>
  179. <p>Merges source code files and syntax trees to a single syntax
  180. tree. This is a file-reading front end to
  181. <code>merge_sources/3</code>. <code>Name</code> specifies the name of
  182. the resulting module - not the name of the output file.
  183. <code>Sources</code> is a list of syntax trees and/or lists of
  184. "source code form" syntax trees, each entry representing a module
  185. definition. <code>Files</code> is a list of file names and/or module
  186. names of source modules to be read and included. All the input
  187. modules must be distinctly named.
  188. <p>If a name in <code>Files</code> is not the name of an existing
  189. file, Igor assumes it represents a module name, and tries to locate
  190. and read the corresponding source file. The parsed files are appended
  191. to <code>Sources</code> and passed on to
  192. <code>merge_sources/3</code>, i.e., entries in <code>Sources</code>
  193. are listed before entries read from files.</p>
  194. <p>If no exports are listed by an <code>export</code> option (see
  195. <code>merge_sources/3</code> for details), then if <code>Name</code>
  196. is also the name of one of the input modules, that module will be
  197. exported; otherwise, the first listed module will be exported. Cf.
  198. the examples under <code>merge/3</code>.</p>
  199. <p>The result is a pair <code>{Tree, Stubs}</code>, where
  200. <code>Tree</code> represents the source code that is the result of
  201. merging all the code in <code>Sources</code> and <code>Files</code>,
  202. and <code>Stubs</code> is a list of stub module descriptors (see
  203. <code>merge_sources/3</code> for details).</p>
  204. <p>Options:
  205. <dl>
  206. <dt><code>{comments, bool()}</code></dt>
  207. <dd>If the value is <code>true</code>, source code comments in
  208. the original files will be preserved in the output. The default
  209. value is <code>true</code>.</dd>
  210. <dt><code>{find_src_rules, [{string(), string()}]}</code></dt>
  211. <dd>Specifies a list of rules for associating object files with
  212. source files, to be passed to the function
  213. <code>filename:find_src/2</code>. This can be used to change the
  214. way Igor looks for source files. If this option is not specified,
  215. the default system rules are used. The first occurrence of this
  216. option completely overrides any later in the option list.</dd>
  217. <dt><code>{includes, [filename()]}</code></dt>
  218. <dd>Specifies a list of directory names for the Erlang
  219. preprocessor, if used, to search for include files (cf. the
  220. <code>preprocess</code> option). The default value is the empty
  221. list. The directory of the source file and the current directory
  222. are automatically appended to the list.</dd>
  223. <dt><code>{macros, [{atom(), term()}]}</code></dt>
  224. <dd>Specifies a list of "pre-defined" macro definitions for the
  225. Erlang preprocessor, if used (cf. the <code>preprocess</code>
  226. option). The default value is the empty list.</dd>
  227. <dt><code>{preprocess, bool()}</code></dt>
  228. <dd>If the value is <code>false</code>, Igor will read source
  229. files without passing them through the Erlang preprocessor
  230. (<code>epp</code>), in order to avoid expansion of preprocessor
  231. directives such as <code>-include(...).</code>,
  232. <code>-define(...).</code> and <code>-ifdef(...)</code>, and
  233. macro calls such as <code>?LINE</code> and <code>?MY_MACRO(x,
  234. y)</code>. The default value is <code>false</code>, i.e.,
  235. preprocessing is not done. (See the module
  236. <code>epp_dodger</code> for details.)
  237. <p>Notes: If a file contains too exotic definitions or uses of
  238. macros, it will not be possible to read it without preprocessing.
  239. Furthermore, Igor does not currently try to sort out multiple
  240. inclusions of the same file, or redefinitions of the same macro
  241. name. Therefore, when preprocessing is turned off, it may become
  242. necessary to edit the resulting source code, removing such
  243. re-inclusions and redefinitions.</p></dd>
  244. </dl>
  245. See <code>merge_sources/3</code> for further options.</p>
  246. </p>
  247. <p><b>See also:</b> <a href="epp_dodger.html">epp_dodger</a>, <a href="#merge-3">merge/3</a>, <a href="#merge_files-3">merge_files/3</a>, <a href="#merge_sources-3">merge_sources/3</a>, <a href="/usr/local/home/richardc/hipe/otp/lib/stdlib/doc/filename.html#find_src-2">filename:find_src/2</a>.</p>
  248. <h3><a name="merge_sources-3">merge_sources/3</a></h3>
  249. <p><tt>merge_sources(Name::atom(), Sources::[Forms], Options::[term()]) -&gt; {<a href="#type-syntaxTree">syntaxTree()</a>, [<a href="#type-stubDescriptor">stubDescriptor()</a>]}</tt>
  250. <ul><li><tt>Forms = <a href="#type-syntaxTree">syntaxTree()</a> | [<a href="#type-syntaxTree">syntaxTree()</a>]</tt></li></ul></p>
  251. <p>Merges syntax trees to a single syntax tree. This is the main
  252. code merging "engine". <code>Name</code> specifies the name of the
  253. resulting module. <code>Sources</code> is a list of syntax trees of
  254. type <code>form_list</code> and/or lists of "source code form" syntax
  255. trees, each entry representing a module definition. All the input
  256. modules must be distinctly named.
  257. <p>Unless otherwise specified by the options, all modules are assumed
  258. to be at least "static", and all except the target module are assumed
  259. to be "safe". See the <code>static</code> and <code>safe</code>
  260. options for details.</p>
  261. <p>If <code>Name</code> is also the name of one of the input modules,
  262. the code from that module will occur at the top of the resulting
  263. code, and no extra "header" comments will be added. In other words,
  264. the look of that module will be preserved.</p>
  265. <p>The result is a pair <code>{Tree, Stubs}</code>, where
  266. <code>Tree</code> represents the source code that is the result of
  267. merging all the code in <code>Sources</code>, and <code>Stubs</code>
  268. is a list of stub module descriptors (see below).</p>
  269. <p><code>Stubs</code> contains one entry for each exported input
  270. module (cf. the <code>export</code> option), each entry describing a
  271. stub module that redirects calls of functions in the original module
  272. to the corresponding (possibly renamed) functions in the new module.
  273. The stub descriptors can be used to automatically generate stub
  274. modules; see <code>create_stubs/2</code>.</p>
  275. <p>Options:
  276. <dl>
  277. <dt><code>{export, [atom()]}</code></dt>
  278. <dd>Specifies a list of names of input modules whose interfaces
  279. should be exported by the output module. A stub descriptor is
  280. generated for each specified module, unless its name is
  281. <code>Name</code>. If no modules are specified, then if
  282. <code>Name</code> is also the name of an input module, that
  283. module will be exported; otherwise the first listed module in
  284. <code>Sources</code> will be exported. The default value is the
  285. empty list.</dd>
  286. <dt><code>{export_all, bool()}</code></dt>
  287. <dd>If the value is <code>true</code>, this is equivalent to
  288. listing all of the input modules in the <code>export</code>
  289. option. The default value is <code>false</code>.</dd>
  290. <dt><code>{file_attributes, Preserve}</code></dt>
  291. <dd><ul>
  292. <li><code>Preserve = yes | comment | no</code></li>
  293. </ul>
  294. If the value is <code>yes</code>, all file attributes
  295. <code>-file(...)</code> in the input sources will be preserved in
  296. the resulting code. If the value is <code>comment</code>, they
  297. will be turned into comments, but remain in their original
  298. positions in the code relative to the other source code forms. If
  299. the value is <code>no</code>, all file attributes will be removed
  300. from the code, unless they have attached comments, in which case
  301. they will be handled as in the <code>comment</code> case. The
  302. default value is <code>no</code>.</dd>
  303. <dt><code>{no_banner, bool()}</code></dt>
  304. <dd>If the value is <code>true</code>, no banner comment will be
  305. added at the top of the resulting module, even if the target
  306. module does not have the same name as any of the input modules.
  307. Instead, Igor will try to preserve the look of the module whose
  308. code is at the top of the output. The default value is
  309. <code>false</code>.</dd>
  310. <dt><code>{no_headers, bool()}</code></dt>
  311. <dd>If the value is <code>true</code>, no header comments will be
  312. added to the resulting module at the beginning of each section of
  313. code that originates from a particular input module. The default
  314. value is <code>false</code>, which means that section headers are
  315. normally added whenever more than two or more modules are
  316. merged.</dd>
  317. <dt><code>{no_imports, bool()}</code></dt>
  318. <dd>If the value is <code>true</code>, all
  319. <code>-import(...)</code> declarations in the original code will
  320. be expanded in the result; otherwise, as much as possible of the
  321. original import declarations will be preserved. The default value
  322. is <code>false</code>.</dd>
  323. <dt><code>{notes, Notes}</code></dt>
  324. <dd><ul>
  325. <li><code>Notes = always | yes | no</code></li>
  326. </ul>
  327. If the value is <code>yes</code>, comments will be inserted where
  328. important changes have been made in the code. If the value is
  329. <code>always</code>, <em>all</em> changes to the code will be
  330. commented. If the value is <code>no</code>, changes will be made
  331. without comments. The default value is <code>yes</code>.</dd>
  332. <dt><code>{redirect, [{atom(), atom()}]}</code></dt>
  333. <dd>Specifies a list of pairs of module names, representing a
  334. mapping from old names to new. <em>The set of old names may not
  335. include any of the names of the input modules.</em> All calls to
  336. the listed old modules will be rewritten to refer to the
  337. corresponding new modules. <em>The redirected calls will not be
  338. further processed, even if the new destination is in one of the
  339. input modules.</em> This option mainly exists to support module
  340. renaming; cf. <code>rename/3</code>. The default value is the
  341. empty list.</dd>
  342. <dt><code>{safe, [atom()]}</code></dt>
  343. <dd>Specifies a list of names of input modules such that calls to
  344. these "safe" modules may be turned into direct local calls, that
  345. do not test for code replacement. Typically, this can be done for
  346. e.g. standard library modules. If a module is "safe", it is per
  347. definition also "static" (cf. below). The list may be empty. By
  348. default, all involved modules <em>except the target module</em>
  349. are considered "safe".</dd>
  350. <dt><code>{static, [atom()]}</code></dt>
  351. <dd>Specifies a list of names of input modules which will be
  352. assumed never to be replaced (reloaded) unless the target module
  353. is also first replaced. The list may be empty. The target module
  354. itself (which may also be one of the input modules) is always
  355. regarded as "static", regardless of the value of this option. By
  356. default, all involved modules are assumed to be static.</dd>
  357. <dt><code>{tidy, bool()}</code></dt>
  358. <dd>If the value is <code>true</code>, the resulting code will be
  359. processed using the <code>erl_tidy</code> module, which removes
  360. unused functions and does general code cleanup. (See
  361. <code>erl_tidy:module/2</code> for additional options.) The
  362. default value is <code>true</code>.</dd>
  363. <dt><code>{verbose, bool()}</code></dt>
  364. <dd>If the value is <code>true</code>, progress messages will be
  365. output while the program is running; the default value is
  366. <code>false</code>.</dd>
  367. </dl></p>
  368. <p>Note: The distinction between "static" and "safe" modules is
  369. necessary in order not to break the semantics of dynamic code
  370. replacement. A "static" source module will not be replaced unless the
  371. target module also is. Now imagine a state machine implemented by
  372. placing the code for each state in a separate module, and suppose
  373. that we want to merge this into a single target module, marking all
  374. source modules as static. At each point in the original code where a
  375. call is made from one of the modules to another (i.e., the state
  376. transitions), code replacement is expected to be detected. Then, if
  377. we in the merged code do not check at these points if the
  378. <em>target</em> module (the result of the merge) has been replaced,
  379. we can not be sure in general that we will be able to do code
  380. replacement of the merged state machine - it could run forever
  381. without detecting the code change. Therefore, all such calls must
  382. remain remote-calls (detecting code changes), but may call the target
  383. module directly.</p>
  384. <p>If we are sure that this kind of situation cannot ensue, we may
  385. specify the involved modules as "safe", and all calls between them
  386. will become local. Note that if the target module itself is specified
  387. as safe, "remote" calls to itself will be turned into local calls.
  388. This would destroy the code replacement properties of e.g. a typical
  389. server loop.</p>
  390. </p>
  391. <p><b>See also:</b> <a href="#create_stubs-2">create_stubs/2</a>, <a href="#rename-3">rename/3</a>, <a href="erl_tidy.html#module-2">erl_tidy:module/2</a>.</p>
  392. <h3><a name="parse_transform-2">parse_transform/2</a></h3>
  393. <p><tt>parse_transform(Forms::[<a href="#type-syntaxTree">syntaxTree()</a>], Options::[term()]) -&gt; [<a href="#type-syntaxTree">syntaxTree()</a>]</tt>
  394. <ul><li><tt><a name="type-syntaxTree">syntaxTree()</a> = <a href="erl_syntax.html#type-syntaxTree">erl_syntax:syntaxTree()</a></tt></li></ul></p>
  395. <p>Allows Igor to work as a component of the Erlang compiler.
  396. Including the term <code>{parse_transform, igor}</code> in the
  397. compile options when compiling an Erlang module (cf.
  398. <code>compile:file/2</code>), will call upon Igor to process the
  399. source code, allowing automatic inclusion of other source files. No
  400. files are created or overwritten when this function is used.
  401. <p>Igor will look for terms <code>{igor, List}</code> in the compile
  402. options, where <code>List</code> is a list of Igor-specific options,
  403. as follows:
  404. <dl>
  405. <dt><code>{files, [filename()]}</code></dt>
  406. <dd>The value specifies a list of source files to be merged with
  407. the file being compiled; cf. <code>merge_files/4</code>.</dd>
  408. </dl>
  409. See <code>merge_files/4</code> for further options. Note, however,
  410. that some options are preset by this function and cannot be
  411. overridden by the user; in particular, all cosmetic features are
  412. turned off, for efficiency. Preprocessing is turned on.</p>
  413. </p>
  414. <p><b>See also:</b> <a href="#merge_files-4">merge_files/4</a>, <a href="/usr/local/home/richardc/hipe/otp/lib/compiler/doc/compile.html#file-2">compile:file/2</a>.</p>
  415. <h3><a name="rename-2">rename/2</a></h3>
  416. <p><tt>rename(Files::[<a href="#type-filename">filename()</a>], Renamings) -&gt; [string()]</tt></p>
  417. <p>Equivalent to <a href="#rename-3"><tt>rename(Files, Renamings, [])</tt></a>.</p>
  418. <h3><a name="rename-3">rename/3</a></h3>
  419. <p><tt>rename(Files::[<a href="#type-filename">filename()</a>], Renamings, Options::[term()]) -&gt; [string()]</tt>
  420. <ul><li><tt>Renamings = [{atom(), atom()}]</tt></li></ul></p>
  421. <p>Renames a set of possibly interdependent source code modules.
  422. <code>Files</code> is a list of file names of source modules to be
  423. processed. <code>Renamings</code> is a list of pairs of <em>module
  424. names</em>, representing a mapping from old names to new. The
  425. returned value is the list of output file names.
  426. <p>Each file in the list will be read and processed separately. For
  427. every file, each reference to some module M, such that there is an
  428. entry <code>{<em>M</em>, <em>M1</em>}</code> in
  429. <code>Renamings</code>, will be changed to the corresponding M1.
  430. Furthermore, if a file F defines module M, and there is an entry
  431. <code>{<em>M</em>, <em>M1</em>}</code> in <code>Renamings</code>, a
  432. new file named <code><em>M1</em>.erl</code> will be created in the
  433. same directory as F, containing the source code for module M, renamed
  434. to M1. If M does not have an entry in <code>Renamings</code>, the
  435. module is not renamed, only updated, and the resulting source code is
  436. written to <code><em>M</em>.erl</code> (typically, this overwrites
  437. the original file). The <code>suffix</code> option (see below) can be
  438. used to change the default "<code>.erl</code>" suffix for the
  439. generated files.</p>
  440. <p>Stub modules will automatically be created (see the
  441. <code>stubs</code> and <code>stub_dir</code> options below) for each
  442. module that is renamed. These can be used to redirect any calls still
  443. using the old module names. The stub files are created in the same
  444. directory as the source file (typically overwriting the original
  445. file).</p>
  446. <p>Options:
  447. <dl>
  448. <dt><code>{backup_suffix, string()}</code></dt>
  449. <dt><code>{backups, bool()}</code></dt>
  450. <dt><code>{printer, Function}</code></dt>
  451. <dt><code>{stubs, bool()}</code></dt>
  452. <dt><code>{suffix, string()}</code></dt>
  453. </dl>
  454. See <code>merge/3</code> for details on these options.</p>
  455. <p><dl>
  456. <dt><code>{comments, bool()}</code></dt>
  457. <dt><code>{preprocess, bool()}</code></dt>
  458. </dl>
  459. See <code>merge_files/4</code> for details on these options.</p>
  460. <p><dl>
  461. <dt><code>{no_banner, bool()}</code></dt>
  462. </dl>
  463. For the <code>rename</code> function, this option is
  464. <code>true</code> by default. See <code>merge_sources/3</code> for
  465. details.</p>
  466. <p><dl>
  467. <dt><code>{tidy, bool()}</code></dt>
  468. </dl>
  469. For the <code>rename</code> function, this option is
  470. <code>false</code> by default. See <code>merge_sources/3</code> for
  471. details.</p>
  472. <p><dl>
  473. <dt><code>{no_headers, bool()}</code></dt>
  474. <dt><code>{stub_dir, filename()}</code></dt>
  475. </dl>
  476. These options are preset by the <code>rename</code> function and
  477. cannot be overridden by the user.</p>
  478. <p>See <code>merge_sources/3</code> for further options.</p>
  479. </p>
  480. <p><b>See also:</b> <a href="#merge-3">merge/3</a>, <a href="#merge_files-4">merge_files/4</a>, <a href="#merge_sources-3">merge_sources/3</a>.</p>
  481. </body>
  482. </html>