HyperSQL Database 2.7.4 · org.hsqldb.util.preprocessor.Preprocessor

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 lexicographic 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 lexicographic 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.

Field Summary

Modifier and Type	Field and Description
pack-priv static final int	CONDITION_ARMED
pack-priv static final int	CONDITION_IN_TRUE
pack-priv static final int	CONDITION_NONE
pack-priv static final int	CONDITION_TRIGGERED
private final Defines	defines
private final Document	document
private final String	documentPath
private final String	encoding
private final int	options
private final IResolver	resolver
private final Stack<E>	stack
private int	state
pack-priv static final Integer[]	STATES

Constructor Summary

Access	Constructor and Description
private	Preprocessor(String documentPath, String encoding, int options, IResolver resolver, String predefined)
private	Preprocessor(Preprocessor other, Document include)

Method Summary

Modifier and Type	Method and Description
private boolean	isHidingLines()
private void	loadDocument()
private Document	loadInclude(String path)
private static void	log(Object toLog)
private boolean	preprocess()
public static void	preprocessBatch(File under which input files are located sourceDir, File under which output files are to be written targetDir, String[] to be preprocessed fileNames, String to use for output file names altExt, String with which to write output files encoding, int used to control preprocessing options, String CSV list of symbol definition expressions defines, IResolver with which to perform property and path expansions resolver) Preprocesses the specified list of files.
public static void	preprocessFile(File under which the input file is located sourceDir, File under which the output file is to be written targetDir, String to be preprocessed fileName, String to use for output file name altExt, String with which to write output file encoding, int used to control preprocessing options, String CSV list of symbol definition expressions defines, IResolver with which to perform property and path expansions resolver) Preprocesses a single file.
private void	preprocessImpl()
private void	processDirective(Line line)
private void	processElse()
private void	processElseIf(boolean condition)
private void	processEndIf()
private void	processIf(boolean condition)
private int	processInclude(int lineCount, Line line)
private Line	resolveLine(String line)
private String	resolvePath(String path)
private void	saveDocument(Object target)
private void	statePop()
private void	statePush()
private File	toCanonicalOrAbsoluteFile(String path)
private String	toSourceLine(final Line line)
private static String	translateFileExtension(String fileName, String ext)
private static String	translatePath(File dir, String fileName, String ext)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CONDITION_ARMED	back to summary
pack-priv static final int CONDITION_ARMED

CONDITION_IN_TRUE	back to summary
pack-priv static final int CONDITION_IN_TRUE

CONDITION_NONE	back to summary
pack-priv static final int CONDITION_NONE

CONDITION_TRIGGERED	back to summary
pack-priv static final int CONDITION_TRIGGERED

defines	back to summary
private final Defines defines

document	back to summary
private final Document document

documentPath	back to summary
private final String documentPath

encoding	back to summary
private final String encoding

options	back to summary
private final int options

resolver	back to summary
private final IResolver resolver

stack	back to summary
private final Stack<E> stack

state	back to summary
private int state

STATES	back to summary
pack-priv static final Integer[] STATES Annotations @SuppressWarnings:UnnecessaryBoxing

Constructor Detail

Preprocessor	back to summary
private Preprocessor(String documentPath, String encoding, int options, IResolver resolver, String predefined) throws PreprocessorException

Preprocessor	back to summary
private Preprocessor(Preprocessor other, Document include)

Method Detail

isHidingLines	back to summary
private boolean isHidingLines()

loadDocument	back to summary
private void loadDocument() throws PreprocessorException

loadInclude	back to summary
private Document loadInclude(String path) throws PreprocessorException

log	back to summary
private static void log(Object toLog)

preprocess	back to summary
private boolean preprocess() throws PreprocessorException

preprocessBatch	back to summary
public static void preprocessBatch(File sourceDir, File targetDir, String[] fileNames, String altExt, String encoding, int options, String defines, IResolver resolver) throws PreprocessorException Preprocesses the specified list of files. Parameters sourceDir:File under which input files are located targetDir:File under which output files are to be written fileNames:String[] to be preprocessed altExt:String to use for output file names encoding:String with which to write output files options:int used to control preprocessing defines:String CSV list of symbol definition expressions resolver:IResolver with which to perform property and path expansions Exceptions PreprocessorException: if an error occurs while loading, preprocessing or saving the result of preprocessing one of the specified input files

preprocessBatch

back to summary

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

Preprocesses the specified list of files.

Parameters

sourceDir:File: under which input files are located
targetDir:File: under which output files are to be written
fileNames:String[]: to be preprocessed
altExt:String: to use for output file names
encoding:String: with which to write output files
options:int: used to control preprocessing
defines:String: CSV list of symbol definition expressions
resolver:IResolver: with which to perform property and path expansions

Exceptions

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

preprocessFile	back to summary
public static void preprocessFile(File sourceDir, File targetDir, String fileName, String altExt, String encoding, int options, String defines, IResolver resolver) throws PreprocessorException Preprocesses a single file. Parameters sourceDir:File under which the input file is located targetDir:File under which the output file is to be written fileName:String to be preprocessed altExt:String to use for output file name encoding:String with which to write output file options:int used to control preprocessing defines:String CSV list of symbol definition expressions resolver:IResolver with which to perform property and path expansions Exceptions PreprocessorException: if an error occurs while loading, preprocessing or saving the result of preprocessing the specified input file

preprocessFile