PRE.DOC Page 1




PRE - Preprocessor Version 2.22 copyright (C) 1988-89 by Gary Crouse.

A preprocessor for Clipper and other dBase style source code.

This program is similar in function to the preprocessor in C and
other language compilers.

Features:
Constant and simple function substitution (#DEFINE).
Include files (#INCLUDE).
Include blocks of source code (#LIBRARY,#).
Conditional compilation or processing (#IFDEF,#IFNDEF,#IGNORE).
IF the program terminates with an error (usually a file not found),
DOS errorlevel is set to 1.

Usage: PRE [] [

] [[/|-]switches]

If no filenames are specified on command line, a help screen is displayed.
Prompts for input filename if not given on command line.
If no extension is given, then .pre is assumed.
Prompts for output filename if not given on command line.
If no extension is given, then .prg is assumed.
Input and output filenames must be different.
Pressing the enter key alone at a prompt will terminate the program.

Switches:
Command line switches may be preceeded with "-" or "/" and may appear
anywhere on command line and in any order.
Switches may be used in any of these formats:
/q /d
/qd
-q /d
All switches except /N and /P are toggles, i.e. they change the current
default. Invoking a switch twice on the command line is the same as not
invoking it at all.


/B - Blank lines and comments are copied.
ON is the same as #BLANK, OFF the same as #XBLANK.
Default is ON.

/C - Case sensitivity for #DEFINE identifiers.
Turning case sensitivity off will cause slower processing.
Default is ON.

/D - Danger (Existing output file deleted without warning).
If /D is off and the output file already exists, a warning
prompt appears.
Default is OFF.

/H, /? - Help.
Displays a help screen and then terminates the program.




PRE.DOC Page 2


/L - List.
Directives are copied as comments.
ON is the same as #LIST, OFF the same as #XLIST.
Default is ON.

/N - Library file name.
The default name is "LIBRARY.SRC".
See #LIBRARY.

/P - Path for includes and library.
Same as #PATH

/Q - Quiet.
No Display of filenames or line numbers.
Default is OFF.

/S - Show Defines.
After all other processing is done, displays a list
of all the #DEFINES encountered.
Default is OFF.

/T - Test Date.
Process only if the input file date and time is later
than the output file date and time.
Default is OFF.

/U - Update default switches.
Used in conjunction with the other switches to change
the program defaults. If used with versions of DOS
older than 3.0, "PRE.EXE" must be in the current directory.


Directives:

#DEFINE []
An identifier consists of letters,numbers, or underscore up to
a maximum length of 32.
A function is an identifier with a set of parentheses containing
optional replaceable parameters. Function invocations may be nested.
The will be used by the preprocessor to
replace any occurences of the in the source
code. The maximum length of a is 128.
Replacements will not be done within comments, quotes (single or
double), text blocks, or #IGNORE blocks.
The constant may be a previously defined identifier or function.
The constant is optional (see #IFDEF,#IFNDEF).
#DEFINE's may be stacked (#DEFINE the same identifier multiple times)
and then unstacked one at a time with #UNDEF (useful for creating
"local" #DEFINE's).

Examples:

#define esc 27
Any occurence of 'esc' will be replaced with '27'




PRE.DOC Page 3


#define zips esc
Assuming that 'esc' was previously defined as '27', any
occurence of 'zips' will be replaced with 27

#define zips Hotsy Totsy
'zips' has been stacked and will now produce 'Hotsy Totsy'

#undef zips
'zips' will produce '27'

#undef zips
'zips' will now produce 'zips'

#define inc(x) x = x + 1
Any occurence of the pattern 'inc(something)' will be replaced
by 'something = something + 1'

#define keypress(c) keyboard(chr(c))
Assuming the previous definitions, 'keypress(esc)' will be
translated to 'keyboard(chr(27))'

#define max(i,j) if(i>j,i,j)
At least one bizzare example is required - 'max(max(A,B),C)'
will produce 'if(if(A>B,A,B) >C,if(A>B,A,B) ,C)'


#UNDEF
Undefines a previous #DEFINE.
See #DEFINE.


#INCLUDE
The file specified by will be processed and
incorporated into the output file. The filename may include
drive and path. #INCLUDE's may be nested (i.e. an included
file may include another file, etc.) but beware of the snake
eating its tail.


#LIBRARY
The filename (may include path) of a source code library.
Overrides /N.
The default filename is 'LIBRARY.SRC'.
A source code library is a file with blocks of code in the
following format:

note
*
.
.
source code
.
.

A block ends at the next line that starts with 'note' or *eof.



PRE.DOC Page 4


The library format is blatantly stolen without apology, and
therefore compatible with the SourceView library format used
in dBRIEF (trademark of Global Technologies Corp).
The has the same format as directive
identifiers.


#PATH
If #INCLUDE or #LIBRARY filenames are given without a drivespec
or path, the preprocessor looks for the file first in the default
directory, then in the #PATH path. #PATH will override /P.


#IFDEF [ . . . [#ELSE]] . . . #ENDIF
If defined . . .
Blocks of code may be included or ignored depending on
whether or not has been defined. The second
parameter of the #DEFINE statement is ignored in this context.
#IFDEF without an identifier will effectively comment out a block
of code.
Example:
#define debug
#ifdef debug
? 'Debugging'
#endif


#IFNDEF . . . [#ELSE] . . . #ENDIF
If not defined . . .
See #IFDEF.


#LIST (#XLIST)
Directives are (are not) copied to the output file as comments
(preceded by '*').
Overrides /L.
To force the line numbers of the output file to correspond with
the line numbers of the input file, turn #LIST on in the input
file and off in any #INCLUDE files.
The default is #LIST.


#BLANK (#XBLANK)
Blank lines and comments are (are not) copied to the output file.
Overrides /B.
To keep output file line numbers aligned with input file
line numbers, leave #BLANK on and #LIST on (see #LIST).
Default is #BLANK.


#* []
Preprocessor comment line.





PRE.DOC Page 5



#IGNORE (#XIGNORE)
Copy (do not copy) following lines to output file but do not process.
(Lines beginning with '#' are not copied).
Default is #XIGNORE.

#
Include a source code block.
See #LIBRARY.


Limits:
Number of Defines : Available memory
(about 2000 with 425k available)
Size of directive identifier : 32
Size of defined constant or expression: 128
Line length : 255
File length : None
Include nesting : Available memory.



This software is distributed FREE, and is not to be sold,
however, contributions (in multiples of $1000 only), comments,
and corrections will be welcomed by:

Gary Crouse
4629 S. Xavier Street
Denver, CO 80236
(303) 795-6719
(compuserve: 71525,1417)