org.hsqldb.util.preprocessor

Class Preprocessor

java.lang.Object

org.hsqldb.util.preprocessor.Preprocessor

public class Preprocessor
extends java.lang.Object

Simple text document preprocessor.

Aims specifically at transforming the HSQLDB codebase to one of a small number of specific build targets, while keeping complexity and external dependencies to a minimum, yet providing an environment that is sufficiently powerful to solve most easily imaginable preprocessing scenarios. Supports the following (case-sensitive) directives:

• //#def[ine] IDENT (ASSIGN? (STRING | NUMBER | IDENT) )?
• //#elif BOOLEXPR
• //#elifdef IDENT
• //#elifndef IDENT
• //#else
• //#endif
• //#endinclude
• //#if BOOLEXPR
• //#ifdef IDENT
• //#ifndef IDENT
• //#include FILEPATH
• //#undef[ine] IDENT

where BOOLEXPR is:

 ( IDENT
 | IDENT ( EQ |  LT | LTE | GT | GTE ) VALUE
 | BOOLEXPR { OR | XOR | AND } BOOLEXPR
 | NOT BOOLEXPR
 | LPAREN BOOLEXPR RPAREN )

and VALUE is :

 ( STRING
 | NUMBER
 | IDENT )
 

and lexographic elements are :

 ASSIGN     : '='
 EQ         : '=='
 LT         : '<'
 LTE        : '<='
 GT         : '>'
 GTE        : '>='
 OR         : ('|' | '||')
 XOR        : '^'
 AND        : ('&' | '&&')
 NOT        : '!'
 DQUOTE     : '"'
 LPAREN     : '('
 RPAREN     : ')'
 DOT        : '.'
 DIGIT      : ['0'..'9']
 EOL        : ('\n' | '\r' | '\n\r')
 SPACE      : (' ' | '\t')
 NON_DQUOTE : { ANY_UNICODE_CHARACTER_EXCEPT_DQUOTE_OR_EOL } -- see the unicode spec
 NON_SPACE  : { ANY_UNICODE_CHARACTER_EXCEPT_SPACE_OR_EOL }  -- see the unicode spec
 WS         : { JAVA_WS } -- see java.lang.Character
 NON_WS     : { ANY_UNICODE_CHARACTER_EXCEPT_WS_OR_EOL }
 STRING     : DQUOTE NON_DQUOTE* DQUOTE
 NUMBER     : DIGIT+ (DOT DIGIT*)?
 IDENT      : JAVA_IDENT_START JAVA_IDENT_PART*              -- see java.lang.Character
 FILEPATH   : NON_SPACE (ANY_UNICODE_CHARACTER* NON_WS)?     -- i.e. trailing SPACE elements are ignored
 

The lexographic definitions above use the BNF conventions :

 '?' -> zero or one
 '*' -> zero or more
 '+' -> one or more
 

Directives may be arbitrarily indented; there is an option (INDENT) to set or unset directive indentation on output. There is also an option (FILTER) to remove directive lines from output. See Option for other preprocessor options.

'//#ifxxx' directives may be nested to arbitrary depth, may be chained with an arbitrary number of '//#elifxxx' directives, may be optionally followed by a single '//#else' directive, and must be terminated by a single '//#endif' directive.

Each '//#include' directive must be terminated by an '//#endinclude' directive; lines between '//#include' and '//#endinclude' are replaced by the content retrieved from the specified FILEPATH.

Included files are preprocessed in a nested scope that inherits the defined symbols of the including scope. Directive lines in included files are always excluded from output.

Design Notes

There are many better/more sophisticated preprocessors/templating engines out there. FreeMaker and Velocity come to mind immediately. Another--the NetBeans MIDP preprocessor--was the direct inspiration for this class.

Other options were rejected because the work of creating this class appeared to be less than dealing with the complexity and dependency issues of hooking up to external libraries. The NetBeans preprocessor, in particular, was rejected because it was not immediately evident how to invoke it independently from the IDE, how to make it available to non-MIDP projects from within the IDE or how to isolate the correct OpenIDE jars to allow stand-alone operation.

Since:

1.8.1

Method Summary

Modifier and Type	Method and Description
static void	preprocessBatch(java.io.File sourceDir, java.io.File targetDir, java.lang.String[] fileNames, java.lang.String altExt, java.lang.String encoding, int options, java.lang.String defines, IResolver resolver) Preprocesses the specified list of files.
static void	preprocessFile(java.io.File sourceDir, java.io.File targetDir, java.lang.String fileName, java.lang.String altExt, java.lang.String encoding, int options, java.lang.String defines, IResolver resolver) Preprocesses a single file.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

preprocessBatch

public static void preprocessBatch(java.io.File sourceDir,
                                   java.io.File targetDir,
                                   java.lang.String[] fileNames,
                                   java.lang.String altExt,
                                   java.lang.String encoding,
                                   int options,
                                   java.lang.String defines,
                                   IResolver resolver)
                            throws PreprocessorException

Preprocesses the specified list of files.

Parameters:

sourceDir - under which input files are located

targetDir - under which output files are to be written

fileNames - to be preprocessed

altExt - to use for output file names

encoding - with which to write output files

options - used to control preprocessing

defines - CSV list of symbol definition expressions

resolver - with which to perform property and path expansions

Throws:

PreprocessorException - if an error occurs while loading, preprocessing or saving the result of preprocessing one of the specified input files

preprocessFile

public static void preprocessFile(java.io.File sourceDir,
                                  java.io.File targetDir,
                                  java.lang.String fileName,
                                  java.lang.String altExt,
                                  java.lang.String encoding,
                                  int options,
                                  java.lang.String defines,
                                  IResolver resolver)
                           throws PreprocessorException

Preprocesses a single file.

Parameters:

sourceDir - under which the input file is located

targetDir - under which the output file is to be written

fileName - to be preprocessed

altExt - to use for output file name

encoding - with which to write output file

options - used to control preprocessing

defines - CSV list of symbol definition expressions

resolver - with which to perform property and path expansions

Throws:

PreprocessorException - if an error occurs while loading, preprocessing or saving the result of preprocessing the specified input file