2.2.2Class ICompiler

Interaface to incremental evaluator.

Class ICompiler( [path] ) from \
                 _BaseCompiler( )

path	The default search path of the compiler.

The incremental compiler, or "evaluator", is meant to provide a falcon-in-falcon compilation environment.

Note: The incremental compiler is currently under development, and subject to sudden changes in behaviors and interfaces.

While the Compiler class is meant to help scripts to load and use foreign code in their context, the ICompiler class provides it's own private virtual machine and executes all the code it receives in a totally separate environment.

Compiling a script through the ICompiler 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.

Incremental compilation means that it's possible to evaluate falcon statements incrementally as they are compiled on the fly and executed one by one.

Compilation methods ICompiler.compileNext and ICompiler.compileAll 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:

- ICompiler.NOTHING - No operation performed (i.e. returned for just comments or whitespaces).

• ICompiler.MORE - The statement is not complete and requires more input.
• ICompiler.INCOMPLETE - While the last statement is complete, the context is still open and requires some more "end" to be closed.
• ICompiler.DECL - The compiler parsed and commited a complete declaration (top level function, class, object etc).
• ICompiler.STATEMENT - A toplevel statement was parsed and executed. Loops, branches, and non-expression statements fall in this category.
• ICompiler.EXPRESSION - A single complete expression was parsed. The evaluated result is available through the ICompiler.result property.
• ICompiler.CALL - It was determined that the expression was a single call, in the form (). Some may want to know this information to avoid printing obvious results (calls returning nil are porbably better to be handled silently).
• ICompiler.TERMINATED - The virtual machine has been requested to terminate.

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:

    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

Everything happening in ICompiler.compileNext and ICompiler.compileAll happens in a separate virtual machine which is totally unrelated with the calling one. Nevertheless, they can safely share the values in the ICompiler.result property:

    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'

Note: Always remember to add a n or ';' after a complete statement in incremental compilation (this requirement might be removed in future).

Note: Don't try to share and call callable symbols. Chances are that they may be callable in one VM, but unaccessible from the other.

Setting the streams in ICompiler.stdIn, ICompiler.stdOut and ICompiler.stdErr 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.

Accessing the stream stored one of the ICompiler properties, an usable base class Stream 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 StringStream. Once set, accessing the stdOut property will return a standard stream, which is actually a shell pointing to your same StringStream. To use StringStream specific methods, as i.e. StringStream.closeToString, 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()).

    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

Properties
result	Item containing last evaluation result.
stdErr	standard error stream of the incremental compiler virtual machine.
stdIn	standard input stream of the incremental compiler virtual machine.
stdOut	standard output stream of the incremental compiler virtual machine.
Methods
compileAll	Compiles entierely the given input.
compileNext	Compiles and executes at most one complete statement or declaration.

Properties inherited from class _BaseCompiler
alwaysRecomp	If true, a load method finding a valid .
compileInMemory	If true (the default) intermediate compilation steps are performed in memory.
ignoreSources	If true, sources are ignored, and only .
language	Language code used to load language-specific string tables.
launchAtLink	If true, the main function (that is, the entry point) of the loaded modules is executed before returning it.
path	The search path for modules loaded by name.
saveMandatory	If true, when saveModule option is true too and a module can't be serialized, the compiler raises an exception.
saveModules	If true, once compiled a source that is located on a local file system, the compiler will also try to save the .
sourceEncoding	The encoding of the source file.
Methods inherited from class _BaseCompiler
addFalconPath	Adds the default system paths to the path searched by this compiler.
setDirective	Compiles a script on the fly.

Properties

result

Item containing last evaluation result.

Item containing last evaluation result.

stdErr

standard error stream of the incremental compiler virtual machine.

standard error stream of the incremental compiler virtual machine. This is used by default error reporting and informative functions as inspect().

stdIn

standard input stream of the incremental compiler virtual machine.

standard input stream of the incremental compiler virtual machine.

stdOut

standard output stream of the incremental compiler virtual machine.

standard output stream of the incremental compiler virtual machine.

Methods

compileAll

Compiles entierely the given input.

ICompiler.compileAll( code )

code	A string containing a complete program (even small).
Return	One of the enumeration values in ICompiler return values.
Raise	CodeError on compilation error. Error (any kind of error) on runtime error.

This method reads exactly as many statements as possible, compiles them and runs them on the fly.

One or more compilation errors will cause a CodeError containing all the detected errors to be raised.

A runtime error will be re-thrown in the context of the calling program.

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 ICompiler class.

compileNext

Compiles and executes at most one complete statement or declaration.

ICompiler.compileNext( code )

code	A string or a Stream containing at least a complete line of code.
Return	One of the enumeration values in ICompiler return values.
Raise	CodeError on compilation error. Error (any kind of error) on runtime error.

This method reads exactly one statement (up to the next n or ';') and executes it immediately.

One or more compilation errors will cause a CodeError containing all the detected errors to be raised.

A runtime error will be re-thrown in the context of the calling program.

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 ICompiler class.