<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class ICompiler - Class ICompiler</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 ICompiler<span class="faldoc_belong"><a href="./module_feather_compiler.html">[in Compiler]</a></p></h1>
<p class="faldoc_brief">Interaface to incremental evaluator. </p>
<p class="faldoc_funcdecl">
<b>class</b> ICompiler( [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="#result">result</a></td><td>Item containing last evaluation result.</td></tr>
<tr><td><a href="#stdErr">stdErr</a></td><td>standard error stream of the incremental compiler virtual machine.</td></tr>
<tr><td><a href="#stdIn">stdIn</a></td><td>standard input stream of the incremental compiler virtual machine.</td></tr>
<tr><td><a href="#stdOut">stdOut</a></td><td>standard output stream of the incremental compiler virtual machine.</td></tr>
<tr><td><a href="#compileAll">compileAll()</a></td><td>Compiles entierely the given input. </td></tr>
<tr><td><a href="#compileNext">compileNext()</a></td><td>Compiles and executes at most one complete statement or declaration. </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> ICompiler( [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">Interaface to incremental evaluator. </p>
<p class="faldoc_text">The incremental compiler, or "evaluator", is meant to provide a falcon-in-falcon compilation environment. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The incremental compiler is currently under development, and subject to sudden changes in behaviors and interfaces. </p>
<p class="faldoc_text"> While the <a href="./class_Compiler.html">Compiler</a> class is meant to help scripts to load and use foreign code in their context, the <b>ICompiler</b> class provides it's own private virtual machine and executes all the code it receives in a totally separate environment. </p>
<p class="faldoc_text"> Compiling a script through the <b>ICompiler</b> is phisically equivalent to start a new 'falcon' command line interpreter and ordering it to run a script, with two main differences: first, the ICompiler instance runs serially with the caller in the same process, and second, the ICompiler also allows incremental compilation. </p>
<p class="faldoc_text">Incremental compilation means that it's possible to evaluate falcon statements incrementally as they are compiled on the fly and executed one by one. </p>
<p class="faldoc_text"> Compilation methods <a href="./class_ICompiler.html#compileNext">ICompiler.compileNext</a> and <a href="./class_ICompiler.html#compileAll">ICompiler.compileAll</a> returns a compilation state (or eventually raise an error), that is useful to determine what happened and what action to take after a partial compilation. Possible return values are: </p>
<ul>
<li><b>ICompiler.NOTHING</b>- No operation performed (i.e. returned for just comments or whitespaces). </li><li><b>ICompiler.MORE</b>- The statement is not complete and requires more input. </li><li><b>ICompiler.INCOMPLETE</b>- While the last statement is complete, the context is still open and requires some more "end" to be closed. </li><li><b>ICompiler.DECL</b>- The compiler parsed and commited a complete declaration (top level function, class, object etc). </li><li><b>ICompiler.STATEMENT</b>- A toplevel statement was parsed and executed. Loops, branches, and non-expression statements fall in this category. </li><li><b>ICompiler.EXPRESSION</b>- A single complete expression was parsed. The evaluated result is available through the <a href="./class_ICompiler.html#result">ICompiler.result</a> property. </li><li><b>ICompiler.CALL</b>- It was determined that the expression was a single call, in the form <exp1>(<exp2>). Some may want to know this information to avoid printing obvious results (calls returning nil are porbably better to be handled silently). </li><li><b>ICompiler.TERMINATED</b>- The virtual machine has been requested to terminate. </li>
</ul>
<p class="faldoc_text">When the functions return MORE or INCOMPLETE, no operation is actually performed. The caller should provide new input with more data adding it to the previously parsed one, like in the following example: </p>
<pre class="faldoc_code">
load compiler
ic = ICompiler()
str = "printl( 'hello'," // incomplete
> ic.compileNext( str ) // will do nothing and return 2 == ICompiler.MORE
str += " 'world')\n" // add \n for a complete statement
> ic.compileNext( str ) // will do the print return 6 == ICompiler.CALL
</pre>
<p class="faldoc_text"> Everything happening in <a href="./class_ICompiler.html#compileNext">ICompiler.compileNext</a> and <a href="./class_ICompiler.html#compileAll">ICompiler.compileAll</a> happens in a separate virtual machine which is totally unrelated with the calling one. Nevertheless, they can safely share the values in the <a href="./class_ICompiler.html#result">ICompiler.result</a> property: </p>
<pre class="faldoc_code">
load compiler
ic = ICompiler()
ic.compileNext( "a = [1,2,3,4]\n" )
> inspect( ic.result ) // will be the array created by the statement
ic.result[0] = "Changed"
ic.compileNext( "inspect( a )\n" ) // will show the change in 'a'
</pre>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Always remember to add a \n or ';' after a complete statement in incremental compilation (this requirement might be removed in future). </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Don't try to share and call callable symbols. Chances are that they may be callable in one VM, but unaccessible from the other. </p>
<p class="faldoc_text"> Setting the streams in <a href="./class_ICompiler.html#stdIn">ICompiler.stdIn</a>, <a href="./class_ICompiler.html#stdOut">ICompiler.stdOut</a> and <a href="./class_ICompiler.html#stdErr">ICompiler.stdErr</a> to new values, it is possible to intercept output coming from the virtual machine used by the incremental compiler, and to feed different input into it. This is the mechanism used by the macro compiler. </p>
<p class="faldoc_text"> Accessing the stream stored one of the <b>ICompiler</b> properties, an usable base class <b><i>Stream</i></b> clone will be returned; this may differ from the object that was originally stored in the property. For example, suppose you want to capture all the output generated by the scripts you incrementally compile through a <b><i>StringStream</i></b>. Once set, accessing the <b>stdOut</b> property will return a standard stream, which is actually a shell pointing to your same StringStream. To use StringStream specific methods, as i.e. <b><i>StringStream.closeToString</i></b>, you need to have a reference to the original object, otherwise you'll need to use the standard Stream methods to get the data (i.e. seek(0) and grabText()). </p>
<pre class="faldoc_code">
load compiler
ic = ICompiler()
ss = StringStream() // to keep our string stream
// perform redirection
ic.stdOut = ss
ic.compileNext( "> 'Hello world';" )
// get the result, but through our original item.
> ss.getString() // prints Hello world
</pre>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="result">result</a></h3>
<p class="item_brief">Item containing last evaluation result.</p>
<h3 class="faldoc_funcname"><a name="stdErr">stdErr</a></h3>
<p class="item_brief">standard error stream of the incremental compiler virtual machine.</p>
<h3 class="faldoc_funcname"><a name="stdIn">stdIn</a></h3>
<p class="item_brief">standard input stream of the incremental compiler virtual machine.</p>
<h3 class="faldoc_funcname"><a name="stdOut">stdOut</a></h3>
<p class="item_brief">standard output stream of the incremental compiler virtual machine.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="compileAll">compileAll()</a></h3>
<p class="item_brief">Compiles entierely the given input. </p>
<p class="faldoc_funcdecl">ICompiler.compileAll( code )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">code</td><td class="faldoc_paramdesc">A string containing a complete program (even small). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> One of the enumeration values in <a href="./class_ICompiler.html">ICompiler</a> return values. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>CodeError</i></b></td><td class="faldoc_raisedesc">on compilation error. </td></tr><tr><td class="faldoc_raiseitem"><b><i>Error</i></b></td><td class="faldoc_raisedesc">(any kind of error) on runtime error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method reads exactly as many statements as possible, compiles them and runs them on the fly. </p>
<p class="faldoc_text">One or more compilation errors will cause a CodeError containing all the detected errors to be raised. </p>
<p class="faldoc_text">A runtime error will be re-thrown in the context of the calling program. </p>
<p class="faldoc_text"> The method returns a number representing the kind of code detected and eventually executed by the interactive compiler. For more details, see the description of the <a href="./class_ICompiler.html">ICompiler</a> class. </p>
</p>
<h3 class="faldoc_funcname"><a name="compileNext">compileNext()</a></h3>
<p class="item_brief">Compiles and executes at most one complete statement or declaration. </p>
<p class="faldoc_funcdecl">ICompiler.compileNext( code )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">code</td><td class="faldoc_paramdesc"> A string or a <b><i>Stream</i></b> containing at least a complete line of code. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> One of the enumeration values in <a href="./class_ICompiler.html">ICompiler</a> return values. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>CodeError</i></b></td><td class="faldoc_raisedesc">on compilation error. </td></tr><tr><td class="faldoc_raiseitem"><b><i>Error</i></b></td><td class="faldoc_raisedesc">(any kind of error) on runtime error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method reads exactly one statement (up to the next \n or ';') and executes it immediately. </p>
<p class="faldoc_text">One or more compilation errors will cause a CodeError containing all the detected errors to be raised. </p>
<p class="faldoc_text">A runtime error will be re-thrown in the context of the calling program. </p>
<p class="faldoc_text"> The method returns a number representing the kind of code detected and eventually executed by the interactive compiler. For more details, see the description of the <a href="./class_ICompiler.html">ICompiler</a> class. </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>
