Prep

This documents prep version 0.87 By Kevin T. Seghetti, last updated 06/27/2003

Overview

Prep is a general (not language specific) text file pre-processor. Its primary function is to provide macro replacement and conditionals to any text file. There are no assumptions made about what text means, for example, quotation marks mean nothing special to prep. Currently there are two types of commands, '#' commands, which must go at the beginning of a line, and '@' commands, which can occur anywhere in a line. Eventually I intend all commands to work anywhere in a line.

See also PrepDesignGoals.

Beginning of line Commands

!#include: Include a text file.

Inserts file in output. Note there are no quotes around the file name. Example

    #include foo.txt
    

##: Insert single #.

Allows insertion of single '#' in output at beginning of line. Example

    ##define foo bar
    

will produce:

    #define foo bar
    

in the output.

!#if: Conditional output.

Not working. Currently always returns false, so can be used to comment out several lines of input. Conditionals may be nested.

!#ifdef: Conditional output.

Checks if macro is defined. If it is, following lines (up to #endif) are output, otherwise they are not. Example:

    #define foo
    #ifdef foo
    this line will be output
    #endif
    #ifdef bar
    this line will not be output
    #endif
    

!#ifndef: Conditional output.

Checks if macro is not defined. If it is, following lines (up to #endif) are not output, otherwise they are. Example:

    #define foo
    #ifndef foo
    this line will be not be output
    #endif
    #ifndef bar
    this line will be output
    #endif
    

!#endif: Conditional output.

Ends a conditional section.

!#*: Comment entire line.

Entire line is not output. Example

    #* this line is a comment
    

---

Inline Commands

@define: Define a macro.

Used to define a macro. Example: @define foo(a,fred) this is a macro fred
(a & fred will get replaced with whatever string is passed in). Any macro parameters may have a default : @define foo(a=10,b=john,c)
Macro invocation: to call a macro just give the macro name followed by an open parenthesis, any parameters, and a close parenthesis: foo(10,fred,3). Default Parameters are used by providing an empty parameter: foo(10,,3) (b will be john in this example). Macro parameters may also be specified by name instead of position: foo(c=>5). The 2 styles may also be mixed: foo(5,c=>5). If a parameter is specified more then once (either by name or position), the first defintion will be used: foo(c=>10,5,fred,15) c will be 10, 15 will be ignored.

@redefine: Redefine a macro

Used to overwrite a macro with a new definition. Example: @redefine foo this will overwrite foo

@definem: Define a multiline macro.

Used to define a multi-line macro Must be terminated with @t. Example: @define foo(a,b) this is a macro b
more of macro b@t

@e(: Force immediate evaluation of text(only used inside of define command).

Used to force a sub-string of macro currently being defined to have macro substitution occur. Ended with matching ). Example: @define foo(a,b) this is a macro b @e( this portion will have immediate substitution done)

@t: Terminate macro definition.

Used to terminate a macro definition. Example: @define this is a test@t this is not part of the macro definition

@undef: Delete a macro.

Used to delete a macro. Example: @undef foo

@if(cond)(body): conditional output.

Output body if cond evaluates to true . Example: @define count 5@t @if(@=(count>0)(var = count)

@while(cond)(body): Loop Until condition false.

Output body repeatedly until cond evaluates to false . Example: @define count 5@t @while(@=(count>0)(@define count @e(count-1)@t

@n: Insert a newline.

Add a new line to the output.

@c: Concatenate next line.

Current line and next line are concatenated. Example: @c

@-: Concatenation backward operator.

Eats white space immediately preceding the @-, back to non-white space character.

@+: Concatenation forward operator.

Eats white space immediately following the @+, up to non-white space character.

@\: End of line continuation operator

Causes next line to parsed as part of this line. Allows multi-line macros to be defined.

@*: Comment to end of line.

Cause rest of line to not be output.

@search(match)(body): Regular expression search. Returns 1 if found, 0 if not

.

@replace(match)(replace)(body): Regular expression replace.

.

@={fihd}(: Evaluate expression.

Scan forward to matching ), and evaluate string as an expression, defaults to returning int, formatting characters go between @ and (. f override causes result to be float (I supported for int as well, h sets output to hex, d to decimal)

---

Known Problems

Recursive macros not detected: If you define foo this is a foo, or pass in a macro parameter which leads to the same condition, the stack will overflow. Two forms of nesting are used: parenthesis (/) and @?/@t, should be consolidated into one