The module that implements the external preprocessor handling is coded in the C source file `epreproc.c' (Note that there is a file `ipreproc.c' that handles internal preprocessors.) The sole function in this file is named epreproc. This is quite a complex function that gets a lot of arguments listing all the preprocessors that have to be executed one after the other on the source file or if not the first one then on the file created by the previous one. The function gets a series of preprocessors to be executed in the command line but in case there is no preprocessor defined in the arguments it executes the preprocessors that have to be executed due to the BASIC program file name extension.
Only the preprocessors that are configured can be executed. Each preprocessor has a symbolic name that is used to name it in the configuration file or on the command line using the option `-p'
An external preprocessor is a program that reads a text file and produces a text file. ScriptBasic executes the external preprocessor in a separate process and supplies it with the input and the output file name on the command line. For example the `scriba.conf.lsp' configuration file may contain the following lines
preproc (
extensions (
heb "heb"
)
external (
heb (
executable "/usr/bin/scriba /usr/share/scriba/source/heber.bas"
directory "/var/cache/scriba/hebtemp/"
)
)
)
The key executable defines the executable image of the preprocessor. In this case because the HEB preprocessor is written in BASIC this is an executable image and an argument. The other arguments, namely the input file name and the output file name is appended after this string separated by space. When the preprocessor is executed the actual command line is
/usr/bin/scriba /usr/share/scriba/source/heber.bas myprog.heb /var/cache/scriba/hebtemp/ADBKPLNBDELMMNKGNBBLHAHGBKKJFIMN
The final argument is a file name that is automatically generated by ScriptBasic using MD5 calculation of the input file name full path (may and presumably should not be correct in this example above as I just typed some random 32 characters). The preprocessor should read the file myprog.heb and should generate /var/ca@dots{MN} (forgive me for not typing that long file name again).
If there are more preprocessor to be executed on the generated result then the next is executed on the generated file as input file and another output file is generated.
The preprocessor program should gracefully exit the process it runs in and exit with the code 0. Any other process exit code is treated as error and the further processing of the BASIC program is aborted.