Main index  |  Module description  |  Classes

ClassCompiler

class Compiler( [path] )

Main interface to the reflexive compiler. more...


Member list

Properties
alwaysRecomp 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 If true (the default) intermediate compilation steps are performed in memory.
ignoreSources If true, sources are ignored, and only .fam or shared object/dynamic link libraries will be loaded.
language Language code used to load language-specific string tables.
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 .fam pre-compiled module, that may be used if the same module is loaded a second time.
sourceEncoding The encoding of the source file.
Constructor
init Initializes the compiler with a default path.
Methods
addFalconPath Adds the default system paths to the path searched by this compiler.
compile Compiles a script on the fly.
loadByName Loads a module given its logical name.
loadModule Loads a Falcon resource from a location on the filesystem.
setDirective Compiles a script on the fly.

Detailed description

Although a single compiler should be enough for the needs of a simple script program, it is possible to create as many instances of the compiler as needed.

However, it is sensible to instance this class through singleton objects, so that they get prepared by the link step of the VM:

       load compiler
 
       object MyCompiler from Compiler
       end
 

Class properties

alwaysRecomp
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
If true (the default) intermediate compilation steps are performed in memory.

If false, temporary files are used instead.

ignoreSources
If true, sources are ignored, and only .fam or shared object/dynamic link libraries will be loaded.

language
Language code used to load language-specific string tables.

When this entry is valorized to a valid international language code, as i.e. "en_US", the compiler tries to use .ftr files found besides their modules to alter their string tables, changing the original strings with their translation for the desired language. If the language table file or the required translation is not available, the operation silently fails and the module is loaded with the string untranslated.

path
The search path for modules loaded by name.

It's a set of Falcon format paths (forward slashes to separate dirs, e.g. “C:/my/path”), separated by semi comma.

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 .fam pre-compiled module, that may be used if the same module is loaded a second time.

Failure in saving the pre-compiled module is not reported, unless saveMandatory option is set.

sourceEncoding
The encoding of the source file.

It defaults to default system encoding that Falcon is able to detect. Use one of the encoding names known by the Transcoder class.


Class methods

init()

Initializes the compiler with a default path.

Compiler.init( [path] )
path

The default search path of the compiler.

If path is not provided, defaults to “.” (script current working directory).

addFalconPath()

Adds the default system paths to the path searched by this compiler.

Compiler.addFalconPath( )

This method instructs the compiler that the default search path used by Falcon engine should be also searched when loading modules. This means that the directory in which official Falcon modules are stored, or those set in the FALCON_LOAD_PATH environment variables, or compiled in for a particular installation of Falcon, will be searched whenever loading a module.

The paths are inserted at the beginning; so, they will be the first searched. It is possible then to alter the search path by changing the (undefined) Expected a link class but found a string: Compiler property and i.e. prepending a desired local search path to it.

compile()

Compiles a script on the fly.

Compiler.compile( modName, data )
modName

A logical unique that will be given to the module after compilation.

data

The data to compile. It may be a string or a stream valid for input.

Returns:

On success, a Module instance that contains the compiled module.

Raises:
SyntaxError

if the module contains logical srror.

IoError

if the input data is a file stream and there have been a read failure.

Tries to compile the module in the data parameter. On failure, a SyntaxError is raised; the subErrors member of the returned error will contain an array where every single compilation error is specified.

On success, an instance of Module class is returned.

loadByName()

Loads a module given its logical name.

Compiler.loadByName( modName )
modName

The logical name of the module to be loaded.

Returns:

On success, a Module instance that contains the loaded module.

Raises:
SyntaxError

if the module contains logical srror.

IoError

if the input data is a file stream and there have been a read failure.

Tries to load a logically named module scanning for suitable sources, pre-compiled modules and binary modules in the search path. In case a suitable module cannot be found, the method returns nil. If a module is found, a CodeError is raised in case compilation or link steps fails.

loadModule()

Loads a Falcon resource from a location on the filesystem.

Compiler.loadModule( modPath )
modPath

Relative or absolute path to a loadable Falcon module or source.

Returns:

On success, a Module instance that contains the loaded module.

Raises:
SyntaxError

if the module contains logical srror.

IoError

if the input data is a file stream and there have been a read failure.

Loads the given file, trying to perform compilation or loading of the relevant .fam precompiled module depending on the property settings. In example, if loading “./test.fal”, unless alwaysRecomp property is true, “./test.fam” will be searched too, and if it's found and newer than ./test.fal, it will be loaded instead, skipping compilation step. Similarly, if “./test.fam” is searched, unless ignoreSource is true, “./test.fal” will be searched too, and if it's newer than ./test.fam it will be recompiled.

In case a suitable module cannot be found, the method returns nil. If a module is found, a CodeError is raised in case compilation or link steps fails.

setDirective()

Compiles a script on the fly.

Compiler.setDirective( dt, value )
dt

Directive to be set.

value

Value to be given to the directive.

Returns:

On success, a Module instance that contains the loaded module.

Raises:
SyntaxError

if the module contains logical srror.

IoError

if the input data is a file stream and there have been a read failure.

Sets a directive as if the scripts that will be loaded by this compiler defined it through the directive statement. Scripts can always override a directive by setting it to a different value in their code; notice also that compilation directives are useful only if a compilation actually take places. In case a .fam or a binary module is loaded, they have no effect.


Main index  |  Module description  |  Classes
Made with Faldoc 1.0.0