<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
<head><meta content="text/html;charset=&quot;utf-8&quot;" http-equiv="Content-type"/><link href="faldoc.css" rel="stylesheet" type="text/css"/><title> - Class ICompiler</title></head><body class="faldoc"><ul class="navi_top"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="feathers_compiler.html">Up: Reflexive compiler</a></li>
<li class="prev"><a href="feathers_compiler_Compiler.html">Previous: Class Compiler</a></li>
<li class="next"><a href="feathers_compiler_Module.html">Next: Class Module</a></li>
<li class="clear"></li>
</ul><div id="page_body"><h1><span class="toc_number">2.2.2</span>Class ICompiler</h1><p class="brief">Interaface to incremental evaluator. </p>
<pre class="prototype">Class ICompiler( [path] ) from \
<a href="feathers_compiler__BaseCompiler.html">_BaseCompiler</a>( )</pre>
<table class="prototype">
<tbody><tr class="optparam"><td class="name">path</td><td class="content"> The default search path of the compiler. </td></tr>
</tbody>
</table>
<p>The incremental compiler, or "evaluator", is meant to provide a falcon-in-falcon compilation environment. </p>
<p class='note'><b>Note:</b> The incremental compiler is currently under development, and subject to sudden changes in behaviors and interfaces. </p>
<p>While the <a href="feathers_compiler_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>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>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>Compilation methods <a href="feathers_compiler_ICompiler.html#compileNext">ICompiler.compileNext</a> and <a href="feathers_compiler_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>
<p>- <b>ICompiler.NOTHING</b> - No operation performed (i.e. returned for just comments or whitespaces). <ul><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="feathers_compiler_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>
<p>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>
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>Everything happening in <a href="feathers_compiler_ICompiler.html#compileNext">ICompiler.compileNext</a> and <a href="feathers_compiler_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="feathers_compiler_ICompiler.html#result">ICompiler.result</a> property: </p>
<pre>
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='note'><b>Note:</b> Always remember to add a n or ';' after a complete statement in incremental compilation (this requirement might be removed in future). </p>
<p class='note'><b>Note:</b> 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>Setting the streams in <a href="feathers_compiler_ICompiler.html#stdIn">ICompiler.stdIn</a>, <a href="feathers_compiler_ICompiler.html#stdOut">ICompiler.stdOut</a> and <a href="feathers_compiler_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>Accessing the stream stored one of the <b>ICompiler</b> properties, an usable base class <b>Stream</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>StringStream</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>StringStream.closeToString</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>
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><table class="members">
<tbody><tr class="member_type"><td class="member_type" colspan="2">Properties</td></tr>
<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>
</tbody>
<tbody><tr class="member_type"><td class="member_type" colspan="2">Methods</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>
</tbody>
</table>
<table class="members">
<tbody><tr class="member_type"><td class="member_type" colspan="2">Properties inherited from class <a href="feathers_compiler__BaseCompiler.html">_BaseCompiler</a></td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#alwaysRecomp">alwaysRecomp</a></td><td> If true, a load method finding a valid .</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#compileInMemory">compileInMemory</a></td><td> If true (the default) intermediate compilation steps are performed in memory.</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#ignoreSources">ignoreSources</a></td><td> If true, sources are ignored, and only .</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#language">language</a></td><td> Language code used to load language-specific string tables.</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#launchAtLink">launchAtLink</a></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="feathers_compiler__BaseCompiler.html#path">path</a></td><td> The search path for modules loaded by name.</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#saveMandatory">saveMandatory</a></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="feathers_compiler__BaseCompiler.html#saveModules">saveModules</a></td><td> If true, once compiled a source that is located on a local file system, the compiler will also try to save the .</td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#sourceEncoding">sourceEncoding</a></td><td> The encoding of the source file.</td></tr>
</tbody>
<tbody><tr class="member_type"><td class="member_type" colspan="2">Methods inherited from class <a href="feathers_compiler__BaseCompiler.html">_BaseCompiler</a></td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#addFalconPath">addFalconPath</a></td><td>Adds the default system paths to the path searched by this compiler. </td></tr>
<tr><td><a href="feathers_compiler__BaseCompiler.html#setDirective">setDirective</a></td><td>Compiles a script on the fly. </td></tr>
</tbody>
</table>
<h2>Properties</h2><h3><a name="result">result</a></h3><p class="brief"> Item containing last evaluation result.</p>
<p> Item containing last evaluation result. </p>
<h3><a name="stdErr">stdErr</a></h3><p class="brief"> standard error stream of the incremental compiler virtual machine.</p>
<p> standard error stream of the incremental compiler virtual machine. This is used by default error reporting and informative functions as inspect(). </p>
<h3><a name="stdIn">stdIn</a></h3><p class="brief"> standard input stream of the incremental compiler virtual machine.</p>
<p> standard input stream of the incremental compiler virtual machine. </p>
<h3><a name="stdOut">stdOut</a></h3><p class="brief"> standard output stream of the incremental compiler virtual machine.</p>
<p> standard output stream of the incremental compiler virtual machine. </p>
<h2>Methods</h2><h3><a name="compileAll">compileAll</a></h3><p class="brief">Compiles entierely the given input. </p>
<pre class="prototype">ICompiler.compileAll( code )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">code</td><td class="content"> A string containing a complete program (even small). </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">One of the enumeration values in <a href="feathers_compiler_ICompiler.html">ICompiler</a> return values. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><b>CodeError</b></td><td class="content"> on compilation error. </td></tr>
<tr><td class="name"><b>Error</b></td><td class="content"> (any kind of error) on runtime error. </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<p>This method reads exactly as many statements as possible, compiles them and runs them on the fly. </p>
<p>One or more compilation errors will cause a CodeError containing all the detected errors to be raised. </p>
<p>A runtime error will be re-thrown in the context of the calling program. </p>
<p>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="feathers_compiler_ICompiler.html">ICompiler</a> class. </p>
<h3><a name="compileNext">compileNext</a></h3><p class="brief">Compiles and executes at most one complete statement or declaration. </p>
<pre class="prototype">ICompiler.compileNext( code )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">code</td><td class="content"> A string or a <b>Stream</b> containing at least a complete line of code. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">One of the enumeration values in <a href="feathers_compiler_ICompiler.html">ICompiler</a> return values. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><b>CodeError</b></td><td class="content"> on compilation error. </td></tr>
<tr><td class="name"><b>Error</b></td><td class="content"> (any kind of error) on runtime error. </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<p>This method reads exactly one statement (up to the next n or ';') and executes it immediately. </p>
<p>One or more compilation errors will cause a CodeError containing all the detected errors to be raised. </p>
<p>A runtime error will be re-thrown in the context of the calling program. </p>
<p>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="feathers_compiler_ICompiler.html">ICompiler</a> class. </p>
</div><ul class="navi_bottom"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="feathers_compiler.html">Up: Reflexive compiler</a></li>
<li class="prev"><a href="feathers_compiler_Compiler.html">Previous: Class Compiler</a></li>
<li class="next"><a href="feathers_compiler_Module.html">Next: Class Module</a></li>
<li class="clear"></li>
</ul><div class="signature">Made with <a href="faldoc 3.0">http://www.falconpl.org</a></div></body></html>
