Class ICompiler[in Compiler]

Interaface to incremental evaluator.

class ICompiler( [path] ) \ from _BaseCompiler

more...

Summary

initInteraface to incremental evaluator.
resultItem containing last evaluation result
stdErrstandard error stream of the incremental compiler virtual machine
stdInstandard input stream of the incremental compiler virtual machine
stdOutstandard output stream of the incremental compiler virtual machine
compileAll()Compiles entierely the given input.
compileNext()Compiles and executes at most one complete statement or declaration.
reset()Resets the compiler.

Inherited properties

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

Inherited methods

addFalconPath from _BaseCompiler Adds the default system paths to the path searched by this compiler.
setDirective from _BaseCompiler Compiles a script on the fly.

Detailed description

Interaface to incremental evaluator.

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:

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

Init Block

Interaface to incremental evaluator.

init ICompiler( [path] )

pathThe 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:

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.

ICompiler.compileAll( code )

codeA string containing a complete program (even small).
Returns: One of the enumeration values in ICompiler return values.
Raises:
CodeErroron 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.
Returns: One of the enumeration values in ICompiler return values.
Raises:
CodeErroron 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.

reset()

Resets the compiler.

ICompiler.reset( )

This method destroys all the entities declared by the module and clears the references held by its virtual machine. It's practically equivalent to create a new instance of the ICompiler, with less overhead.


Made with faldoc 2.1.0