<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Compiler - Class Compiler</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Compiler<span class="faldoc_belong"><a href="./module_feather_compiler.html">[in Compiler]</a></p></h1>
<p class="faldoc_brief">Main interface to the reflexive compiler. </p>
<p class="faldoc_funcdecl">
<b>class</b> Compiler( [path] ) \
<b>from</b> <a href="./class__BaseCompiler.html">_BaseCompiler</a>
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#compile">compile()</a></td><td>Compiles a script on the fly. </td></tr>
<tr><td><a href="#loadByName">loadByName()</a></td><td>Loads a module given its logical name. </td></tr>
<tr><td><a href="#loadFile">loadFile()</a></td><td>Loads a Falcon resource from a location on the filesystem. </td></tr>
</table>
<h3 class="faldoc_title">Inherited properties</h3>
<table class="faldoc_list">
<tr><td><a href="./class__BaseCompiler.html#alwaysRecomp">alwaysRecomp</a> from _BaseCompiler </td><td>If true, a load method finding a valid .fam that may substitute a .fal will ignore it, and will try to compile and load the .fal instead.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#compileInMemory">compileInMemory</a> from _BaseCompiler </td><td>If true (the default) intermediate compilation steps are performed in memory.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#ignoreSources">ignoreSources</a> from _BaseCompiler </td><td>If true, sources are ignored, and only .fam or shared object/dynamic link libraries will be loaded.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#language">language</a> from _BaseCompiler </td><td>Language code used to load language-specific string tables.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#launchAtLink">launchAtLink</a> from _BaseCompiler </td><td>If true, the __main__ function (that is, the entry point) of the loaded modules is executed before returning it.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#path">path</a> from _BaseCompiler </td><td>The search path for modules loaded by name.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#saveMandatory">saveMandatory</a> from _BaseCompiler </td><td>If true, when saveModule option is true too and a module can't be serialized, the compiler raises an exception.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#saveModules">saveModules</a> from _BaseCompiler </td><td>If true, once compiled a source that is located on a local file system, the compiler will also try to save the .fam pre-compiled module, that may be used if the same module is loaded a second time.</td></tr>
<tr><td><a href="./class__BaseCompiler.html#sourceEncoding">sourceEncoding</a> from _BaseCompiler </td><td>The encoding of the source file.</td></tr>
</table>
<h3 class="faldoc_title">Inherited methods</h3>
<table class="faldoc_list">
<tr><td><a href="./class__BaseCompiler.html#addFalconPath">addFalconPath</a> from _BaseCompiler </td><td>Adds the default system paths to the path searched by this compiler. </td></tr>
<tr><td><a href="./class__BaseCompiler.html#setDirective">setDirective</a> from _BaseCompiler </td><td>Compiles a script on the fly. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Compiler( [path] ) \
<b>from</b> <a href="./class__BaseCompiler.html">_BaseCompiler</a>
</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">path</td><td class="faldoc_optparamdesc">The default search path of the compiler. </td></tr>
</table>
<br/>
<p class="item_brief">Main interface to the reflexive compiler. </p>
<p class="faldoc_text">The static compiler class is an interface to the compilation facilities and the vritual machine currently running the caller Falcon program. </p>
<p class="faldoc_text"> Compiled resources (either external binary modules or falcon scripts, that can be stored on external resources or compiled on-the-fly) are integrated in the running virtual machine as a separate module, immediately linked and made runnable. The caller script receives a <a href="./class_Module.html">Module</a> instance which can be used to control the execution of the target module, or to unload it at a later time. </p>
<p class="faldoc_text">The linked modules receive every globally exported symbol that is accessible to the caller script, but their export requests are ignored (they can't modify the global execution environment of the calling script). </p>
<p class="faldoc_text">Although a single compiler should be enough for the needs of a simple script program, it is possible to create as many instances of the compiler as needed. </p>
<p class="faldoc_text">However, it is sensible to instance this class through singleton objects, so that they get prepared by the link step of the VM: </p>
<pre class="faldoc_code">
load compiler
object MyCompiler from Compiler
end
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> If <b>path</b> is not provided, defaults to "." (script current working directory). </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="compile">compile()</a></h3>
<p class="item_brief">Compiles a script on the fly. </p>
<p class="faldoc_funcdecl">Compiler.compile( modName, data )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">modName</td><td class="faldoc_paramdesc">A logical unique that will be given to the module after compilation. </td></tr><tr><td class="faldoc_param">data</td><td class="faldoc_paramdesc">The data to compile. It may be a string or a stream valid for input. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> On success, a <a href="./class_Module.html">Module</a> instance that contains the compiled module. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>SyntaxError</i></b></td><td class="faldoc_raisedesc">if the module contains logical error. </td></tr><tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">if the input data is a file stream and there have been a read failure. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Tries to compile the module in the <b>data</b> parameter. On failure, a SyntaxError is raised; the subErrors member of the returned error will contain an array where every single compilation error is specified. </p>
<p class="faldoc_text">On success, an instance of Module class is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="loadByName">loadByName()</a></h3>
<p class="item_brief">Loads a module given its logical name. </p>
<p class="faldoc_funcdecl">Compiler.loadByName( modName )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">modName</td><td class="faldoc_paramdesc">The logical name of the module to be loaded. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> On success, a <a href="./class_Module.html">Module</a> instance that contains the loaded module. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>SyntaxError</i></b></td><td class="faldoc_raisedesc">if the module contains logical error. </td></tr><tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">if the input data is a file stream and there have been a read failure. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Tries to load a logically named module scanning for suitable sources, pre-compiled modules and binary modules in the search path. In case a suitable module cannot be found, the method returns nil. If a module is found, a CodeError is raised in case compilation or link steps fails. </p>
</p>
<h3 class="faldoc_funcname"><a name="loadFile">loadFile()</a></h3>
<p class="item_brief">Loads a Falcon resource from a location on the filesystem. </p>
<p class="faldoc_funcdecl">Compiler.loadFile( modPath, [alias] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">modPath</td><td class="faldoc_paramdesc">Relative or absolute path to a loadable Falcon module or source. </td></tr>
<tr><td class="faldoc_optparam">alias</td><td class="faldoc_optparamdesc">Alias under which the module should be loaded. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> On success, a <a href="./class_Module.html">Module</a> instance that contains the loaded module. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>SyntaxError</i></b></td><td class="faldoc_raisedesc">if the module contains logical error. </td></tr><tr><td class="faldoc_raiseitem"><b><i>IoError</i></b></td><td class="faldoc_raisedesc">if the input data is a file stream and there have been a read failure. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Loads the given file, trying to perform compilation or loading of the relevant .fam precompiled module depending on the property settings. In example, if loading "./test.fal", unless alwaysRecomp property is true, "./test.fam" will be searched too, and if it's found and newer than ./test.fal, it will be loaded instead, skipping compilation step. Similarly, if "./test.fam" is searched, unless ignoreSource is true, "./test.fal" will be searched too, and if it's newer than ./test.fam it will be recompiled. </p>
<p class="faldoc_text"> If <b>alias</b> parameter is given, the loaded modules assumes the given name. The same naming conventions used by the load directive (names starting with a single "." or with "self.") are provided. Notice that the path separators are NOT automatically transformed into "." in the module logical name, so to import the module under a local namespace, using this parameter is essential. </p>
<p class="faldoc_text">In case a suitable module cannot be found, the method returns nil. If a module is found, a CodeError is raised in case compilation or link steps fails. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
