Interaface to incremental evaluator.
class ICompiler( [path] ) \ from _BaseCompiler
| 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. |
| compileAll() | Compiles entierely the given input. |
| compileNext() | Compiles and executes at most one complete statement or declaration. |
| alwaysRecomp from _BaseCompiler | 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. |
| compileInMemory from _BaseCompiler | If true (the default) intermediate compilation steps are performed in memory. |
| ignoreSources from _BaseCompiler | If true, sources are ignored, and only .fam or shared object/dynamic link libraries will be loaded. |
| language from _BaseCompiler | Language code used to load language-specific string tables. |
| launchAtLink 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 .fam pre-compiled module, that may be used if the same module is loaded a second time. |
| sourceEncoding from _BaseCompiler | The encoding of the source file. |
| addFalconPath from _BaseCompiler | Adds the default system paths to the path searched by this compiler. |
| setDirective from _BaseCompiler | Compiles a script on the fly. |
class ICompiler( [path] ) \ from _BaseCompiler
| path | The default search path of the compiler. |
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
Item containing last evaluation result.
standard error stream of the incremental compiler virtual machine.
standard input stream of the incremental compiler virtual machine.
standard output stream of the incremental compiler virtual machine.
Compiles entierely the given input.
ICompiler.compileAll( code )
| code | A string containing a complete program (even small). | ||||
| Returns: | One of the enumeration values in ICompiler return values. | ||||
| Raises: |
|
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.
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: |
|
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.