Loading a preprocessor depends on the embedding application. To load an internal preprocessor the function ipreproc_LoadInternalPreprocessor is called (implemented in the file `ipreproc.c').
This function gets the name of an external preprocessor to load. The function searches the configuration information for the named preprocessor, loads the DLL/SO and invokes the initiation function of the preprocessor.
int ipreproc_LoadInternalPreprocessor(pPreprocObject pPre,
char *pszPreprocessorName);
The first argument is the pointer to the ScriptBasic preprocessor object to access the configuration information and the list of loaded preprocessors to put the actual one on the list.
The second argument is the name of the preprocessor as named in the configuration file, for example
preproc (
internal (
sample "C:\\ScriptBasic\\bin\\samplepreprocessor.dll"
)
The return value is zero or the error code.
(Note that this documentation may not be up-to date about the precise functioning of this function. For most up-to date information see the source documentation that is extracted from the source comment using the tool `esd2html.pl'.)
In the code base of ScriptBasic this function is called by the reader `reader.c' in the function reader_LoadPreprocessors. This is called automatically when the source is read and include files were also included. This function (reader_LoadPreprocessors) goes through all the lines and searches for lines that start with the word preprocess and name a preprocessor. The function loads the preprocessor and deletes the source line.
The function ipreproc_LoadInternalPreprocessor is also called from the function scriba_LoadInternalPreprocessor in source file `scriba.c'
This function can and should be used by the embedding programs to load all internal preprocessors that are to be loaded based on some external conditions. For example the VARIATION STANDARD of ScriptBasic (aka. the command line embedding variation) loads all internal preprocessors that were named after the command line option `-i'.
Other embedding application may get the information of desired preprocessors from different sources, like environment variables, configuration files and so on.
Note that internal preprocessors are not used whenever an already compiled version of the program is executing. If there is a preprocess line in the source code and the program has generated a cache or any other binary format BASIC program and that file is used to execute the program the preprocessor will no effect. The interpreter will not load the preprocessor and thus it will act as it did not exist.
There are two kind of preprocessors:
The "altering" preprocessors act as conventional preprocessor altering the source code and/or altering the compilation environment during compilation that results finally a binary BASIC file. These preprocessors ask the ScriptBasic interpreter to unload the preprocessor before the actual execution of the program starts as they have nothing to do with the actual, executed program.
Debugger preprocessor collects symbolic information during the compilation phase and alters the hook functions HOOK_ExecBefore, HOOK_ExecAfter, HOOK_ExecCall, HOOK_ExecReturn.
During execution these "preprocessors" remain in the process and execute the functions that the altered hook pointers point to performing debugging, profiling or some other development support features.
The sample preprocessor dbg does this implementing a command line debugger.
It is possible, though I see no reason to write a preprocessor that belongs to both categories above.
Altering preprocessors are BASIC program specific and are usually invoked because the program contains a line preprocess.
Debugger type preprocessors are loaded the way of the execution of the program requests it. For example the user uses the option `-i'. In this case the command line version of ScriptBasic does not use cache file to ensure that the program really does using the preprocessor and starts the debugger, for example.