To invoke the preprocessor use:
((w)perl) preprocessor.pl CommentCharacter JobFile
Eg: wperl preprocessor.pl %% Path\to\preprocessor.pp
The JobFile can contain anything, only the lines will be processed that correspond the syntax: <newline><comment character><hashmark><keyword><semicolon> etc. described below:
The order of the entries is arbitrary, they will be processed in the following order anyway: UPDATEON, UPDATE, WRITEPP
Italics mean optional parameters. In the examples below % will be the comment character.
JobFile entry: %#UPDATEON: COMPUTERNAME "Path\to\file" >>> post-preprocess command to the system
After backing up to Path\to\filename.ext.ppbckp, this will rewrite the original file on the given computer, but only if it differs from the one identified by COMPUTERNAME. The COMPUTERNAME record will be also overwritten in the JobFile with the name of the current computer. This ensures that the file will be updated only once every time it is being processed on an other computer. The file to be processed can contain the following entries:
%#VAR_1 = ""This can be a long-long multiline expression with environmental variables, etc., see below...""
%#DEFON137 = ""s⁄replace this⁄for this⁄imsxoge"" See Perl Quick Reference on the usage of the s⁄⁄⁄ and tr⁄⁄⁄ operators.
All the substitutions defined with the DEFON statements will be applied to the document. In these statements, you can use all the variables defined within the same file, all the environmental variables and also $SPC_PATH. It is a good practice to use markers with the same label, like %#M137 to make matching easier and clearer!
JobFile entry: %#UPDATE: "Path\to\file" >>> post-preprocess command to the system
UPDATE works the same way as UPDATEON, with a few differences: this carries out the replacements every time regardless of the COMPUTERNAME, and overwrites the document if and only if the replacements eventually change the content of the file. It compiles every DEF*** commands except those which begin with DEFON***.
JobFile entry: %#WRITEPP: "Path\to\file"
Where file contains definition of variables at the beginning of new lines, like:
%#VAR_eXamPle1 = "" some stuff, where you need to put \\ backslash before any \' apostrophe, and \\ backslash, like: \\\' ""
... and references to these variables anywhere in the file: $VAR_eXamPle1. On each and every call, the preprocessor will replace $VAR_eXamPle1 to its value, and write the resulting file into a new file: Path\to\filename_pp.ext, which has to be included in any further compilation, etc... The original file won't be affected.
On VARiables:
- Definition: <newline><comment character>#VAR_some_CaSe_sensitive_alphanumeric_plus_underscore_ID optional spaces = optional spaces ""value that can also contain new lines,
%but than you need to begin them with the <comment character, eg. %>. Don\'t forget to use backslash, when: \\ or \'! This was written on $ENV_COMPUTERNAME to a file on the path $SPC_PATH.""
- You can use two special kind of variables in any VARiable, substitution⁄translation DEFinition or jobfile entry: $SPC_PATH returns the Path of the jobfile (without the last backslash), and $ENV_SOMETHING returns the current value of the environmental variable SOMETHING on the given computer. However, if you make a reference to an ordinary VARiable in an other VARiable, it won't be evaluated.
- The order and positioning of defining the VARiables within a file is arbitrary. VARiables have to be references by $VAR_ID.
- If in an expression a variable is followed directly by something else, starting with an alphanumeric or underscore character, which would change the name of the variable, like "$VAR_NAMEsomething else", then use backslash: "$VAR_NAME\something else"!
On DEFinitions:
- Definition: <newline><comment character>#DEF any label for the user to remember = optional spaces ""a single line expression with Perl's tr⁄⁄⁄ or s⁄⁄⁄ operators, and with any of these: $VAR_***, $ENV_*** and $SPC_***."" The same applies to DEF when UPDATE, and to DEFON when UPDATEON. DEFON is no DEF! Every definition, beginning with DEFON will be processed only by UPDATEON, but eg. DEFoN only by UPDATE.
- The order and positioning of making DEFinitions within a file is arbitrary. DEFinitions are not referenced directly, but the regular expression has to match the part of the file where the DEFinition has to be applied. To facilitate this, you are encouraged to use markers in preceding lines, or at the end of the lines, like %#M1, which will then be included in the matching expression.
Beware of the following:
- \w does not contain any letters with accents. If needed, use eg. [\wáéíóöõúüû] instead.
- In Perl, matching is greedy by default! To match the shortest expression, use question mark, eg. .*? instead of just .* .
- Be extra cautious when using the s⁄⁄⁄sg operator with the given switches! If you are not absolutely sure what you are doing and familiar with Perl Regular Expressions, then better use WRITEPP! Otherwise UPDATE is quicker and doesn't need the inclusion of an extra _pp file. However in some cases exactly the ⁄sg modifiers are needed. In such cases you will need a special character, which is not there in the expression to be matched, eg. &: see the Examples with chapter1.