Falcon::ModuleLoader Class Reference

Module Loader support. More...

#include <modloader.h>

Inheritance diagram for Falcon::ModuleLoader:

Inheritance graph
[legend]

List of all members.

Public Types


Public Member Functions

void addDirectoryBack (const String &directory)
 Adds a single path specification to the module loader path, with lower priority.
void addDirectoryFront (const String &directory)
 Adds a single directory to the module loader path, with higher priority.
void addFalconPath ()
 Add standard system Falcon module paths to the search path of this module loader.
void addSearchPath (const String &path)
 Adds one or more directories to the module loader search path.
void alwaysRecomp (bool mode)
bool alwaysRecomp () const
 Always recompile accessor.
virtual ModuleLoader * clone () const
uint32 compileErrors () const
 return last compile errors.
bool compileInMemory () const
void compileInMemory (bool ci)
Compiler & compiler ()
 Return the compiler used by this module loader (non const).
const Compiler & compiler () const
 Return the compiler used by this module loader.
bool compileTemplate () const
void compileTemplate (bool bCompTemplate)
bool delayRaise () const
void delayRaise (bool setting)
bool detectTemplate () const
void detectTemplate (bool bDetect)
const String & getLanguage () const
 Returns the translation language that is searched by this module loader.
String getSearchPath () const
 Get the search path used by this module loader.
void getSearchPath (String &target) const
 Get the search path used by this module loader.
void ignoreSources (bool mode)
bool ignoreSources () const
 Ignore Source accessor.
virtual Module * loadBinaryModule (const String &module_path)
 Loads a binary module by realizing a system dynamic file.
virtual Module * loadFile (const URI &module_URI, t_filetype type=t_none, bool scan=false)
 Loads a module by its URI.
virtual Module * loadFile (const String &module_path, t_filetype type=t_none, bool scan=false)
 Loads a module by its path.
bool loadLanguageTable (Module *module, const String &language)
 Load a determined language table directly into the module.
Module * loadModule (const String &file)
 Loads a Falcon precompiled native module.
virtual Module * loadModule (Stream *input)
 Loads a Falcon precompiled native module from the input stream.
virtual Module * loadName (const String &module_name, const String &parent_module="")
 Loads a module by its name.
virtual Module * loadSource (Stream *in, const String &uri, const String &modname)
 Compile the source from an input stream.
virtual Module * loadSource (const String &file)
 Load a source.
 ModuleLoader (const String &path)
 Creates a module loader with a given path.
 ModuleLoader (const ModuleLoader &other)
 ModuleLoader ()
 Creates a module loader.
void raiseError (int code, const String &expl, int fsError=0)
void saveIntTemplates (bool mode)
 Save international templates for loaded modules.
bool saveMandatory () const
void saveMandatory (bool setting)
bool saveModules () const
void saveModules (bool t)
bool saveRemote () const
 Tells wether this loader tries to save .fam on remote filesystems.
void saveRemote (bool brem)
 Tells if this modloader should save .fam on remote filesystems.
void setLanguage (const String &langname)
 Sets the language required to modules during load.
void setSearchPath (const String &path)
 Changes the search path used to load modules by this module loader.
const String & sourceEncoding () const
void sourceEncoding (const String &name)
virtual ~ModuleLoader ()

Protected Member Functions

bool applyLangTable (Module *mod, const String &file_path)
 Try to load the language table for the given module.
t_filetype checkForModuleAlreadyThere (String &final_name)
Module * compile (const String &path)
virtual t_filetype fileType (const String &path)
 Determine file types.
Module * loadModule_select_ver (Stream *in)
Module * loadModule_ver_1_0 (Stream *in)
virtual Stream * openResource (const String &path, t_filetype type=t_none)
 Basic function used to open modules.
bool scanForFile (URI &origUri, VFSProvider *, t_filetype &type, FileStat &fs)
 Scan for files that may be loaded.
t_filetype searchForModule (String &final_name)

Static Protected Member Functions

static void getModuleName (const String &path, String &modName)
 Discovers the module name given a complete file path.

Protected Attributes

bool m_alwaysRecomp
bool m_bSaveIntTemplate
uint32 m_compileErrors
Compiler m_compiler
bool m_compMemory
bool m_delayRaise
bool m_detectTemplate
bool m_forceTemplate
bool m_ignoreSources
String m_language
 Required language during load.
List m_path
 Path where to search the modules.
bool m_saveMandatory
bool m_saveModule
bool m_saveRemote
String m_srcEncoding

Detailed Description

Module Loader support.

This class enables embedding applications and falcon VM (and thus, Falcon scripts) to load modueles.

Member Enumeration Documentation

enum Falcon::ModuleLoader::t_filetype

File type enumeration.

The module loader tries to determine which type of file the it is trying to load (or is told this information by the loader user).

Enumerator:
t_none  Undetermined / detect.

t_source  The module is a source.

t_ftd  The module is a Falcon Templage Document.

t_vmmod  The module is a falcon FAM module.

t_binmod  The module is a native .so/.dll.

t_defaultSource  Special file type.

Try to determine the type of the file, but in case it cannot be determined, defaults to source.

Constructor & Destructor Documentation

Falcon::ModuleLoader::ModuleLoader (  ) 

Creates a module loader.

As default, the current directory is included in the path. If this is not desired, use ModuleLoader( "" ) as a constructor.

Falcon::ModuleLoader::ModuleLoader ( const ModuleLoader &  other  ) 

Falcon::ModuleLoader::ModuleLoader ( const String &  path  ) 

Creates a module loader with a given path.

The path is in the FALCON format; path are separated by semicolons (;). If the system uses disk specification, falcon is able to understand a single letter, a colon and a slash as a disk specification. I.e.

         ".;C:/projects;d:/modules";

will be processed as ".", "C:\projects" and "D:\modules" under systems using disk specifications.

The current directory is not included in the default path. If this is desired, add it as a single "." entry.

virtual Falcon::ModuleLoader::~ModuleLoader (  )  [virtual]

Member Function Documentation

void Falcon::ModuleLoader::addDirectoryBack ( const String &  directory  )  [inline]

Adds a single path specification to the module loader path, with lower priority.

This method adds a directory with a priority lower than the ones already defined.

Note:
Don't use ";" separated paths here; just call this method once for each path.
Parameters:
directory the directory to be added to the path

void Falcon::ModuleLoader::addDirectoryFront ( const String &  directory  )  [inline]

Adds a single directory to the module loader path, with higher priority.

This method adds a directory with a priority higher than the ones already defined.

Note:
Don't use ";" separated paths here; just call this method once for each path.
Parameters:
directory the directory to be added to the path

void Falcon::ModuleLoader::addFalconPath (  ) 

Add standard system Falcon module paths to the search path of this module loader.

By default, Falcon system module paths are not added to newly created Module Loader. This is because an embedding application may wish to load its own version of the modules from somwhere else.

This method appends the path where Falcon is installed on this system, to the search path of this module loader. The added path will be searched after the ones that have already been added to this loader. To give system Falcon libraries and modules higher priority, call this method before adding your application paths (including ".").

If Falcon is not installed on this system, this method will have no effect.

void Falcon::ModuleLoader::addSearchPath ( const String &  path  ) 

Adds one or more directories to the module loader search path.

This method appends the search specification path passed as a parameter to the search path of those already known. Directory must be expressed in Falcon standard directory notation ( forward slashes to separate subdirectories). If the path contains more than one directory they must be separated with a semicomma; for example:

         modloader.addSearchPath( "../;/my/modules;/other/modules" );

The directories will be added with a priority lower than the currently searched ones; that is, they will be searched after the ones that have been previously added are searched.

See also:
setSearchPath getSearchPath
Parameters:
path the search specification to be added to the path

void Falcon::ModuleLoader::alwaysRecomp ( bool  mode  )  [inline]

bool Falcon::ModuleLoader::alwaysRecomp (  )  const [inline]

Always recompile accessor.

Returns:
true if source modules must always be recompiled before loading.

bool Falcon::ModuleLoader::applyLangTable ( Module *  mod,
const String &  file_path 
) [protected]

Try to load the language table for the given module.

t_filetype Falcon::ModuleLoader::checkForModuleAlreadyThere ( String &  final_name  )  [protected]

virtual ModuleLoader* Falcon::ModuleLoader::clone (  )  const [virtual]

Module* Falcon::ModuleLoader::compile ( const String &  path  )  [protected]

uint32 Falcon::ModuleLoader::compileErrors (  )  const [inline]

return last compile errors.

bool Falcon::ModuleLoader::compileInMemory (  )  const [inline]

void Falcon::ModuleLoader::compileInMemory ( bool  ci  )  [inline]

Compiler& Falcon::ModuleLoader::compiler (  )  [inline]

Return the compiler used by this module loader (non const).

This object can be inspected, or compiler options can be set by the caller.

Returns:
a reference of the compiler used by the loader.

const Compiler& Falcon::ModuleLoader::compiler (  )  const [inline]

Return the compiler used by this module loader.

This object can be inspected, or compiler options can be set by the caller.

Returns:
a reference of the compiler used by the loader.

bool Falcon::ModuleLoader::compileTemplate (  )  const [inline]

void Falcon::ModuleLoader::compileTemplate ( bool  bCompTemplate  )  [inline]

bool Falcon::ModuleLoader::delayRaise (  )  const [inline]

void Falcon::ModuleLoader::delayRaise ( bool  setting  )  [inline]

bool Falcon::ModuleLoader::detectTemplate (  )  const [inline]

void Falcon::ModuleLoader::detectTemplate ( bool  bDetect  )  [inline]

virtual t_filetype Falcon::ModuleLoader::fileType ( const String &  path  )  [protected, virtual]

Determine file types.

This method tries to determine the type of a file given a path.+

This function is meant to allow subclassess to determine file types on their own will; this method tell sources, binary module and Falcon native modules. This basic version of the method will try to open the file for reading to determine their type. It will also close them before returning.

Parameters:
path the file to be tested (absolute / relative to cwd)
Returns:
the type of file or t_none if it can't be determined.

const String& Falcon::ModuleLoader::getLanguage (  )  const [inline]

Returns the translation language that is searched by this module loader.

static void Falcon::ModuleLoader::getModuleName ( const String &  path,
String &  modName 
) [static, protected]

Discovers the module name given a complete file path.

Parameters:
path the path to a possible falcon module
modNmae the possible falcon module name

String Falcon::ModuleLoader::getSearchPath (  )  const [inline]

Get the search path used by this module loader.

Returns:
the search path that is searched by this module loader.

References Falcon::Engine::getSearchPath().

void Falcon::ModuleLoader::getSearchPath ( String &  target  )  const

Get the search path used by this module loader.

Parameters:
target a string where the path will be saved.

void Falcon::ModuleLoader::ignoreSources ( bool  mode  )  [inline]

bool Falcon::ModuleLoader::ignoreSources (  )  const [inline]

Ignore Source accessor.

Returns:
true if the Module Loader must load only pre-compiled modules, false otherwise.

virtual Module* Falcon::ModuleLoader::loadBinaryModule ( const String &  module_path  )  [virtual]

Loads a binary module by realizing a system dynamic file.

The method calls the dll/dynamic object loader associated with this module loader. The dll loader usually loads the dynamic objects and calls the startup routine of the loaded object, which should return a valid Falcon module instance.

This method then fills the module path and logical name accordingly with the given parameter.

Special strategies in opening binary modules may be implemented by subclassing the binary module loader.

This function sets the module name and path accordingly to the file parameter. The caller may know better and reset the module logical name once a valid module is returned.

Note:
This method doesn't set the module language table.
Parameters:
module_path the relative or absolute path.
Returns:
newly allocated module on success.
Exceptions:
Error or appropriate subclass on error.

virtual Module* Falcon::ModuleLoader::loadFile ( const URI &  module_URI,
t_filetype  type = t_none,
bool  scan = false 
) [virtual]

Loads a module by its URI.

See also:
Module *loadFile( const String &module_path, t_filetype type=t_none, bool scan=false );
Parameters:
module_URI the relative or absolute path of the file to load
type the type of the file to be loaded, or t_none to autodetect
scan if module_path is relative, set to true to allow scanning of the modloader path
Returns:
a valid module on success.
Exceptions:
Error or appropriate subclass on error.

virtual Module* Falcon::ModuleLoader::loadFile ( const String &  module_path,
t_filetype  type = t_none,
bool  scan = false 
) [virtual]

Loads a module by its path.

This method loads directly a module. If the scan parameter is given and the path is relative, then the module is searched in the modloader path. Current directory is not explicitly searched unless it is present in the loader search path.

If the path is relative and scan is false, the path will be considered relative to current working directory. If it's true, a relative path would be searched across all the paths in turn, that doesn't necesarily include the current working directory.

If the type of file is not given (set to t_none) the method tries to dentermine the type of the file. If it's given, it will ignore the file type detection and will pass an opened stream directly to the loadSource(), loadModule() or loadBinModule() method.

In case the module is determined to be a source (or an FTD), this method scans for a file in the same directory with a .fam extension, and checks if the module can is newer and can be loaded (unless alwaysRecomp() is true, In this case, if the .fam module fails to load, then the the error is discarded and the program continues trying to compile the original source. If trying to use a .fam is not desired, either set alwaysRecomp() or call directly loadSource().

Conversely, if the file is determined to be a .fam module, a source with the same name but with newer timestamp is searched, and eventually compiled if found. If this is not wanted, either call directly loadModule() or set ignoreSources() to true.

This implementation will raise an error if t_source is explicitly provided as a type or if the target file is detected as a source.

On load, the logical module name will be set to the file part of the path. However, it may be changed after loading.

Note:
on failure, the module loader will post an error to its error handler, if it has been provided.
Parameters:
module_path the relative or absolute path of the file to load. The file is not URI encoded; to load URI encoded filenames, pass directly the URI file.
type the type of the file to be loaded, or t_none to autodetect
scan if module_path is relative, set to true to allow scanning of the modloader path
Returns:
a valid module on success.
Exceptions:
Error or appropriate subclass on error.

bool Falcon::ModuleLoader::loadLanguageTable ( Module *  module,
const String &  language 
)

Load a determined language table directly into the module.

On success, the language table of the module and it's declared language are changed.

Returns:
true on success.

Module* Falcon::ModuleLoader::loadModule ( const String &  file  ) 

Loads a Falcon precompiled native module.

Front end for loadModule(Stream).

This function sets the module name and path accordingly to the file parameter. The caller may know better and reset the module logical name once a valid module is returned.

Note:
This method doesn't set the module language table.
Parameters:
path A path from which to load the module.
Returns:
a newly allocated module on success.
Exceptions:
Error or appropriate subclass on error.

virtual Module* Falcon::ModuleLoader::loadModule ( Stream *  input  )  [virtual]

Loads a Falcon precompiled native module from the input stream.

This function tries to load a Falcon native module. It will detect falcon module mark ('F' and 'M'), and if successful it will recognize the module format, and finally pass the stream to the correct module loader for the version/subversion that has been detected.

On success, a new memory representation of the module, ready for linking, will be returned.

Note:
after loading, the caller must properly set returned module name and path.
Parameters:
input An input stream from which a module can be deserialized.
Returns:
a newly allocated module on success.
Exceptions:
Error or appropriate subclass on error.

Module* Falcon::ModuleLoader::loadModule_select_ver ( Stream *  in  )  [protected]

Module* Falcon::ModuleLoader::loadModule_ver_1_0 ( Stream *  in  )  [protected]

virtual Module* Falcon::ModuleLoader::loadName ( const String &  module_name,
const String &  parent_module = "" 
) [virtual]

Loads a module by its name.

This function scan the directories in the path for a matching module name. The logical module name, which can be logically related with a parent module (as in the case of "load self.submodule") is used to determine possible phisical file names within the given search path and filesystems.

Once a suitable file is found, loadFile() is called with the appriopriate path and type parameters. The loadFile() method has its own precompiled-versus-source resolution logic. As this function is just a front-end to resolve logical name into potential physical names, this function follows the same compile-or-load logic as loadFile().

Note:
On success, the returned module will have its physical name and path set accordingly to the module_name parameter and the path where the module has been found.
If a suitable file is found, but fails to load (beynd the recovery logic as stored in loadFile()), the search is interrupted and an error is raised.

Parameters:
module_name the name of the module to search for
parent_name the name of the module that is asking for this module to be loaded
Returns:
newly allocated module on success.
Exceptions:
Error or appropriate subclass on error.

virtual Module* Falcon::ModuleLoader::loadSource ( Stream *  in,
const String &  uri,
const String &  modname 
) [virtual]

Compile the source from an input stream.

This function sets the module name and path accordingly to the file parameter. The caller may know better and reset the module logical name once a valid module is returned.

Note:
Notice that this function doesn't load the translation table.
Also, this function tries to save the generated module in a .fam file, if saveModules is set to true; if saveMandatory is also true, the function will raise an error if the compiled module can't be properly saved.

Exceptions:
Error or appropriate subclass on error.
Parameters:
in the file from which to load the file.
uri the complete URI of the source file from which the stream is open,
modname logical name of the module.

virtual Module* Falcon::ModuleLoader::loadSource ( const String &  file  )  [virtual]

Load a source.

Tries to load a file that is directly considered a source file. This is just a front-end to loadSource( Stream*,const String &, const String & ).

This function sets the module name and path accordingly to the file parameter. The caller may know better and reset the module logical name once a valid module is returned.

Note:
This method doesn't set the module language table.
Parameters:
file a complete (relative or absolute) path to a source to be compiled.
Returns:
a valid module on success, 0 on failure (with error risen).
Exceptions:
Error or appropriate subclass on error.

virtual Stream* Falcon::ModuleLoader::openResource ( const String &  path,
t_filetype  type = t_none 
) [protected, virtual]

Basic function used to open modules.

This virtual function opens a disk file as given in the path (absolute or relative to Current Working Directory).

By overloading this method, subclasses may create method loaders for non-disk resources (i.e. interface virtual file systems on compressed files or on networks).

The method may invoke the error handler to signal errors, and will return 0 in case the file can't be opened for reading.

An optional file type is provided to give the subclasses an hint on how to configure the stream for the final user.

Parameters:
path the path to file
type the file type that should be opened (t_none meaning unknown / generic).
Returns:
a valid input stream or 0 on error.

void Falcon::ModuleLoader::raiseError ( int  code,
const String &  expl,
int  fsError = 0 
)

void Falcon::ModuleLoader::saveIntTemplates ( bool  mode  )  [inline]

Save international templates for loaded modules.

If this option is set to true, and if the loaded modules have international strings, then a template for the internationalization file will be saved.

bool Falcon::ModuleLoader::saveMandatory (  )  const [inline]

void Falcon::ModuleLoader::saveMandatory ( bool  setting  )  [inline]

bool Falcon::ModuleLoader::saveModules (  )  const [inline]

void Falcon::ModuleLoader::saveModules ( bool  t  )  [inline]

bool Falcon::ModuleLoader::saveRemote (  )  const [inline]

Tells wether this loader tries to save .fam on remote filesystems.

See also:
saveRemote( bool )

void Falcon::ModuleLoader::saveRemote ( bool  brem  )  [inline]

Tells if this modloader should save .fam on remote filesystems.

By default, if a source file is loaded from a remote filesystem, the module loader doesn't try to save a .fam serialized version of the module besides the source.

You can set this to true to force a try to store modules also on remote filesystems.

Parameters:
brem true to try to save .fam files on remote filesystems.

bool Falcon::ModuleLoader::scanForFile ( URI &  origUri,
VFSProvider *  ,
t_filetype &  type,
FileStat &  fs 
) [protected]

Scan for files that may be loaded.

Utility funciton searching for one possible file in a directory.

Tries all the possible system extensions (applied directly on origUri) and searches for a matching file. If one is found, true is returned and type and fs are filled with the item module-type and its data.

Priority is scan file types are ftd, fal, fam and .so/.dll/.dylib.

The function doesn't check for validity of the given file, but only for its existence.

Returns:
on success, returns true.

t_filetype Falcon::ModuleLoader::searchForModule ( String &  final_name  )  [protected]

void Falcon::ModuleLoader::setLanguage ( const String &  langname  )  [inline]

Sets the language required to modules during load.

This informs the module loader that the owner wishes the string table of the loaded module configured for the given language.

If the loaded module doesn't declare itself to be written in the desired language, the module loader will try to load modulename.ftr binary file, get the table for the desired language and change the strings according to the translation table before returning it to the caller.

In case of failure, the original string table will be left untouched.

Language names are the ISO language names in 5 characters: xx_YY.

Setting the language to "" disables this feature.

Parameters:
langname the name of the language that should be loaded.

void Falcon::ModuleLoader::setSearchPath ( const String &  path  ) 

Changes the search path used to load modules by this module loader.

This method changes the search specification path used by this module loader with the one provided the parameter to the search path of those already known. Directory must be expressed in Falcon standard directory notation ( forward slashes to separate subdirectories). If the path contains more than one directory they must be separated with a semicomma; for example:

         modloader.addSearchPath( "../;/my/modules;d:/other/modules" );

See also:
addSearchPath getSearchPath

ModuleLoader

Parameters:
path the new module search path

const String& Falcon::ModuleLoader::sourceEncoding (  )  const [inline]

void Falcon::ModuleLoader::sourceEncoding ( const String &  name  )  [inline]

Member Data Documentation

bool Falcon::ModuleLoader::m_alwaysRecomp [protected]

bool Falcon::ModuleLoader::m_bSaveIntTemplate [protected]

uint32 Falcon::ModuleLoader::m_compileErrors [protected]

Compiler Falcon::ModuleLoader::m_compiler [protected]

bool Falcon::ModuleLoader::m_compMemory [protected]

bool Falcon::ModuleLoader::m_delayRaise [protected]

bool Falcon::ModuleLoader::m_detectTemplate [protected]

bool Falcon::ModuleLoader::m_forceTemplate [protected]

bool Falcon::ModuleLoader::m_ignoreSources [protected]

String Falcon::ModuleLoader::m_language [protected]

Required language during load.

List Falcon::ModuleLoader::m_path [protected]

Path where to search the modules.

Each entry of the list is one single system path encoded in falcon file name format.

bool Falcon::ModuleLoader::m_saveMandatory [protected]

bool Falcon::ModuleLoader::m_saveModule [protected]

bool Falcon::ModuleLoader::m_saveRemote [protected]

String Falcon::ModuleLoader::m_srcEncoding [protected]

The documentation for this class was generated from the following file:
Generated on Mon Oct 19 10:11:39 2009 for Falcon_Core by  doxygen 1.5.8