filepp - Online in the Cloud

PROGRAM:

NAME

filepp - A generic file preprocessor

SYNOPSIS

filepp [options] filename(s)

DESCRIPTION

filepp is a generic file preprocessor designed to allow the functionality provided by the
C preprocessor cpp(1) to be used with any file type. filepp is designed to be easily
customised and extended.

OPTIONS

filepp accepts the following command line options:

-b Suppress blank lines originating from include files (this has no effect on the top-
level file).

-c Read input from STDIN instead of a file. Note: if both -c and input files are
specified, both are used as inputs in the order given.

-Dmacro
Predefine macro to have a definition of `1'.

-Dmacro=defn
Predefine macro to have a definition of defn.

-d Output debugging information.

-dd Output verbose debugging information. This option shows all normal debugging
information, plus the full list of defined macros every time the list changes.

-dl Output light debugging information. This option shows minimal debugging
information.

-dprechar
Prefix all debugging information with char (can be character or string), can be
used to make debugging easier to read.

-dpostchar
Postfix all debugging information with char (can be character or string), this
defaults to a newline. If char does not contain a newline, then no newline will be
printed after debugging messages. (Newlines can be put in char using the
__NEWLINE__ macro.)

-ds Print debugging info on stdout rather than stderr.

-e Define all environment variables as macros with prefix envchar.

-ec char
Set envchar (prefix of environment variables defined as macros) to char, defaults
to $. (Note: this option only takes effect at the time the environment variables
are converted to macros).

-ecn Set envchar (prefix of environment variables defined as macros) to nothing (no
prefix).

-h Show summary of options.

-Idir Append directory dir to the list of directories searched for include files.

-imacros file
Reads in macros from file, but discards everything else in the file.

-k Turn off parsing of all keywords. This is useful if you just want to use the macro
expansion facilities of filepp. With this option all keywords found will be
ignored, filepp will just replace any macros specified with the -Dmacro=defn
option.

-kc char
Set keyword prefix character to char (can also be a string). All filepp keywords
are prefixed with the character # by default. This option allows the prefix to be
changed to something else.

-lc char
Set line continuation character to char (can also be a string). When the line
continuation character is found with a newline following it, it and the newline are
replaced by the line continuation replacement character. Default is (cpp(1)
style).

-lec char
Set optional keyword line end character to char (can also be a string). This
allows extra characters to be placed at the end of a line containing a keyword.
The extra characters will be ignored. This is useful if keywords are to be
embedded in HTML or C style comments. For example, to embed keywords in an HTML
comment the keyword prefix character could be set to <--!# and the optional keyword
line end character set to -->. An example keyword would then be:

<!--#include "header.h" -->

In the case the optional keyword line end characters --> would be ignored.

-lr char
Set line continuation replacement character to char (can also be a string).
Default is a null string (cpp(1) style).

-lrn Set line continuation replacement character to be a newline.

-m module.pm
Load module module.pm. module.pm is a perl(1) module which can be used to extend
or modify the behaviour of filepp. See section FILEPP MODULES for details of
modules included with filepp and FILEPP MODULE API for details on how to write your
own modules.

-Mdir Append directory dir to the list of directories searched for filepp modules. This
list defaults to the directory the filepp modules are installed (if any) plus the
default Perl module paths. (Note: this adds the directory to the Perl @INC list.)

-mp char
Prefix all macros with char. Macros are defined in the normal way, but will only
be replaced when found prefixed with char. For example, filepp macros will behave
similar to Bourne shell (sh(1)) variables if char is set to $.

-mpnk Turns off macro prefixes within keywords. When using a macro prefix character this
option allows macros to be used without the prefix in keyword processing. For
example, if the macro prefix is $ then and #if would be written as:

#if $MACRO == 1

Using the mpnk option allows the #if to be written as:

#if MACRO == 1

-o name
Write output to name instead of STDOUT. If there is only one input file and it has
the same name as the output file, the original input file will be backed-up as
name~.

-ov Overwrite mode, causes the output file to overwrite the input file. Useful when
modifying a large number of files at once, eg:

filepp -ov -DTHIS=THAT *

The original input file(s) will be backed-up as name~.

-ovc IN=OUT
Similar to overwrite mode, the difference is the output filename is input filename
with IN part converted to OUT. For example, to process a set of files all ending
with .in and have the output files all ending in .out do:

filepp -ovc .in=.out *.in

In this case a file called test.in will be processed and the output file will be
test.out. Note: if the input file does not contain IN then the output file will
have the same name as the input file and the original input file(s) will be backed-
up as name~!

-pb Preserve blank lines. Using this option attempts to keep as many lines in the
output file as are in the input file, so all blank lines which normally would not
get printed are printed. Useful when comparing intput file with output.

-re Treat keyword and macro prefix characters and line continuation character as Perl
regular expressions instead of normal strings.

-s Run filepp in safe mode. This turns off the pragma keyword.

-Umacro
Undefine previously defined macro.

-u Undefine all currently defined macros, including predefined ones.

-v Show version of program.

-w Turn on word boundaries when replacing macros. When word boundaries are on, macros
will only be replaced if the macro appears in the text as a word. For example, by
default macro would be replaced in both cases of the following text:

macro as word, macroNOTaword

but only the first occurrence would be replaced with the -w option.

With this option enabled filepp will only replace macros which contain alphanumeric
characters. International (non-ASCII) character sets can be supported using Perl's
locale handling.

KEYWORDS

filepp supports the following keywords:

#include <FILE>
Include a file in the file being processed. This variant is used for "system"
include files. It searches for a file named FILE in a list of directories
specified by you. Directories are specified with the command option `-I'. filepp
does not predefine any system directories in which to search for files.

#include "FILE"
Include a file in the file being processed. This variant is used for include files
of your own project. It searches for a file named FILE first in the current
directory, then in the list of directories specified with the command option `-I'.
The current directory is the directory the base input file is in.

#define macro
Define the macro macro to have a definition of `1'. macro can then be used with
the keywords #ifdef and #ifndef.

#define macro defn
Define the macro macro to have the value defn. macro can then be used with the
keywords #ifdef and #ifndef. Also, all instances of macro following the #define
statement will be replaced with the string defn. The string defn is taken to be
all the characters on the line following macro.

#define macro(arg1, arg2, ...) defn
Define the macro macro to have the value defn with arguments (arg1, arg2, ...).
macro can be used as follows:

#define macro(foo) defn with foo in

Now when replacing occurs:

macro(bar)

will become:

defn with bar in

Macros can have any number of comma separated arguments.

Macros can also have variable numbers of arguments if the final macro ends in ...,
for example:

#define error(string, args...) fprintf(stderr, string, args);

Here the first argument given becomes string and all other arguments will become
args. If called as: error("%d,%s", i, string) it will give

fprintf(stderr, "%d,%s", i, string);

Also, if a macro with a variable number of arguments is passed no arguments for the
variable argument, then commas can be optionally removed from the definition by
preceding the definition with "##". For example:

#define error(string, args...) fprintf(stderr, string, ##args);

If this is called as: error("empty") then result will be:

fprintf(stderr, "empty");

The comma immediately before ##args has been removed.

#if expr
A conditional statement, expr will be evaluated to true (1) or false (0). If expr
evaluates to true, the text between the #if and the next #else or #endif will be
included. If expr evaluates to false, the text between the #if and the next #else
or #endif will be ignored. expr can use all the usual cpp style comparisons (==,
!=, <, >, etc.). Multiple comparisons can be combined with and (&&) and or (||).
The defined keyword can also be used to check if macros are defined. For example:

#if defined macro && macro == defn

Note: filepp's #if does not work in exactly the same way as cpp(1)'s #if. cpp(1)'s
#if only does numerical style comparisons. Filepp's #if statement can also compare
strings and regular expressions using perl(1)'s full range of comaprison
operations. For example, to test if two strings are exactly equal use:

#if "MACRO" eq "string"

To test if strings are not equal use ne instead of eq. Regular expressions can
also be tested, for example to test if a macro has any whitespace in it use:

#if "MACRO" =~ /\s/

To test if a macro does not have any whitespace in it =~ can be replaced with !~.

Perl experts: #if works by first parsing expr for the defined keyword and checking
if the macro it refers to is defined, replacing it with 1 if it is and 0 if it
isn't. It then checks expr for any other macros and replaces them with their
definition. Finally it passes expr through Perl's eval function, which returns
true or false.

#elif expr
#elif stands for "else if". Like #else, it goes in the middle of a
#if[n][def]-#endif pair and subdivides it; it does not require a matching #endif of
its own. Like #if, the #elif directive includes an expression to be tested.

#ifdef macro
A conditional statement, if macro has been defined the text between the #ifdef and
the next #else or #endif will be included. If macro has not been defined the text
between the #ifdef and the next #else or #endif will be ignored.

#ifndef macro
The reverse case of the #ifdef conditional.

#else The #else directive can be added to a conditional to provide alternative text to be
used if the condition is false.

#endif Used to terminate a conditional statement. Normal processing resumes following the
#endif.

#undef macro
Undefine a previously defined macro.

#error mesg
Causes filepp to exit with the error message mesg.

#warning mesg
Causes filepp to issue the warning message mesg.

#comment mesg
As filepp is supposed to be a generic file preprocessor, it cannot support any
known comment styles, therefore it defines its own with this keyword. All lines
starting with #comment are treated as comments and removed by filepp.

#pragma filepp function arg1, arg2, ...
The #pragma keyword immediately followed by the word filepp allows the user to
execute a Perl function during parsing. The word immediately following filepp is
taken as the name of the function and the remainder of the line is taken to be a
comma separated list of arguments to the function. Any of the filepp internal
functions (see section FILEPP MODULE API) can be called with the #pragma keyword.

Warning: There are obvious security risks with allowing arbitrary functions to be
run, so the -s (safe mode) command line option has been added which turns the
#pragma keyword off.

PREDEFINED MACROS

filepp supports a set of predefined macros. All the predefined macros are of the form
__MACRO__, where MACRO is:

FILE This macro expands to the name of the current input file.

LINE This macro expands to the current input line number.

DATE This macro expands to a string that describes the date on which the preprocessor is
being run. The string contains eleven characters and looks like "Oct 29 2012".

ISO_DATE
This macro expands to a string that describes the date on which the preprocessor is
being run. The string is in the format specified by ISO 8601 (YYYY-MM-DD) and
looks like "2012-10-29".

TIME This macro expands to a string that describes the time at which the preprocessor is
being run. The string contains eight characters and looks like "02:35:47".

BASE_FILE
This macro expands to the name of the main input file.

INCLUDE_LEVEL
This macro expands to a decimal integer constant that represents the depth of
nesting in include files. The value of this macro is incremented on every #include
directive and decremented at every end of file.

NEWLINE
This macro expands to a newline.

TAB This macro expands to a tab.

NULL This macro expands to nothing. It is useful if you want to define something to be
nothing.

VERSION
This macro expands to a string constant which describes the version number of
filepp. The string is a sequence of decimal numbers separated by periods and looks
like "1.8.0".

FILEPP_INPUT
This macro expands to a string constant which says the file was generated
automatically from the current BASE_FILE and looks like "Generated automatically
from ./filepp.1.in by filepp".

FILEPP MODULES

The following modules are included with the main filepp distribution:

FOR MODULE - for.pm

The for module implements a simple for loop. Its file name is for.pm.

The for loop is similar in functionality to that of other programming languages such as
Perl or or C. It has a single variable (a filepp macro) which is assigned a numerical
value. This numerical value changes by a set increment on each iteration through the
loop. The loop termiates when the value no longer passes a comparison test.

The for module implements the following keywords:

#for macro start compare end increment
The #for keyword is functionally equivalent to the following Perl or C style loop:

for(macro=start; macro compare end; macro+=increment)

The #for keyword requires the following space separated parameters:

macro : The name of the macro to which the for loop should assign its numerical
value.

start : The value macro should be assigned at the start of the loop. start should
be a numerical value.

compare : The comparison to make between the current value of macro and the value
end to determine when the loop should terminate. Valid values for compare are <,
>, >=, <=.

end : the for loop will terminate when the test

macro compare end

fails. end should be a numerical value.

increment : The value to increment macro on each iteration of the loop. At the end
of each iteration the value of increment is added to the current value of macro.
increment should be a numerical value.

#endfor
The #endfor keyword is used to signify the end of the loop. Everything within the
opening #for and the closing #endfor will be processed on each iteration of the
loop.

Example usage:

#for COUNTER 10 > 1 -2.5

COUNTER

#endfor

In the above example COUNTER will be defined to have values 10, 7.5, 5 and 2.5 for each
successive iteration through the loop.

Nested loops are also possible, as is changing the value of the macro within the loop.
start, end and increment should all be numerical values, however it is possible to use
macros instead provided the macros are defined to have numerical values.

FOREACH MODULE - foreach.pm

The foreach module implements a simple foreach loop. Its file name is foreach.pm.

The foreach loop is similar in functionality to that of other programming languages such
as Perl. It takes a list of values separated by a user definable delimiter (',' by
default). It then iterates through all values in the list, defining a macro to be each
individual value for each iteration of the loop. The loop terminates when all values have
been used.

The foreach module implements the following keywords:

#foreach macro list
The #foreach keyword is functionally equivalent to the following Perl style loop:

foreach macro (split(/delim/, list))

The #foreach keyword requires the following space separated parameters:

macro : The name of the macro to which the foreach loop should assign the current
list value.

list : The list of values, separated by delim (see #foreachdelim keyword for how to
set delim). list can also be a macro or contain macros.

The loop will run from the #foreach keyword to the next #endforeach keyword.

#endforeach
The #endforeach keyword is used to signify the end of the loop. Everything within
the opening #foreach and the closing #endforeach will be processed on each
iteration of the loop.

Example usage:

#foreach VALUE one, two, three, four

VALUE

#endforeach

In the above example VALUE will be defined to have values one, two, three and four for
each successive iteration through the loop.

Nested loops are also possible.

#foreachdelim /delim/
The #foreachdelim keyword is used to set the delimiter used in each list. The
delimiter can be any character, string or regular expression. The delimiter should
be enclosed in forward slashes, in the same style as Perl regular expressions.
The default value for delim is ','. To set the delimiter to be a single space do:

#foreachdelim / /

To set delim to be any amount of white space do:

#foreachdelim /\s+/

See the Perl documentation on regular expressions for more advanced uses.

LITERAL MODULE - literal.pm

The literal module prevents macros appearing in literal strings from being replaced. A
literal string is defined as having the form:

"literal string with macro in"

In the above example, macro will not be replaced.

The behaviour of the literal module can be reveresed by defining the macro LITERAL_REVERSE
before loading the module, for example:

filepp -DLITERAL_REVERSE -m literal.pm <files>

This has the effect of only replacing macros which appear in strings.

TOUPPER MODULE - toupper.pm

The toupper module converts all lowercase letters to uppercase.

TOLOWER MODULE - tolower.pm

The tolower module converts all uppercase letters to lowercase.

C/C++ COMMENT MODULE - c-comment.pm

The c-comment module removes all C style:

/* comment */

and C++ style:

// comment

comments from a file. C and C++ comments are removed after keywords have been processed.
If you wish to remove C and C++ comments before keywords are processed, define the macro
REMOVE_C_COMMENTS_FIRST before loading the module, eg:

filepp -DREMOVE_C_COMMENTS_FIRST -m c-comment.pm

HASH COMMENT MODULE - hash-comment.pm

The hash-comment module removes all comments of the style:

# comment

from a file. This is the commenting style used by Perl, Bourne Shell, C Shell and many
other programs and configuration files. Hash comments are removed after keywords have
been processed. If you wish to remove hash comments before keywords are processed, define
the macro REMOVE_HASH_COMMENTS_FIRST before loading the module (Note: if you do this and
also use # as the keyword character then the keywords will be removed BEFORE they are
processed).

FUNCTION MODULE - function.pm

The function module allows the user write macros which call Perl functions. Its file name
is function.pm.

The function module allows macros of the form:

macro(arg1, arg2, arg3, ...)

to be added to a file. When the macro is found, it will run a function from a Perl
module, with arguments arg1, arg2, arg3, ... passed to the function. The function must
return a string. The returned string will replace the call to the function in the output.
The function can have any number of arguments. If the function has no arguments it should
be called with an empty argument list:

macro()

If the word macro is found in the input file without being followed by a ( it will be
ignored.

To use the function module, the user must provide a Perl function which optionally takes
in arguments and returns a string. The function can either be one of filepp's internal
functions or one of the user's own provided in a Perl module. The function can be added
in two ways. The first way is through the function keyword:

#function macro function
macro is the name of the macro which is used to signify a call to the function in
the input file and function is the name of the function to be called.

The second method of adding a function is to call the Perl function:

Function::AddFunction($macro,$function)
which has the same inputs as the function keyword.

Functions can be removed either through the keyword:

#rmfunction macro
or through the Perl function

Function::RemoveFunction($macro)

MATHS MODULE - maths.pm

The module provides a set of macros which perform mathematical operations. When the
macros are encoutered in an input file, they are evaluated and the result is returned in
the output.

The maths module includes the following macros:

add(a, b, c, ...)
Takes in any number of arguments and returns their sum: (a + b + c + ...)

sub(a, b)
Returns a minus b: (a - b)

mul(a, b, c, ...)
Takes in any number of arguments and returns their product: (a * b * c * ...)

div(a, b)
Returns a over b: (a / b)

abs(a) Returns the absoulte value of a.

atan2(a, b)
Returns the arctangent of a/b in the range -pi to pi.

cos(a) Returns the cosine of a in radians.

exp(a) Returns the e to the power of a.

int(a) Returns the integer portion of a.

log(a) Returns the natural logarithm (base e) of a.

rand(a)
Returns a random fractional number between the range 0 and a. If a is omitted,
returns a value between 0 and 1.

sin(a) Returns the sine of a in radians.

sqrt(a)
Returns the square root of a.

srand(a)
Sets the random number seed for rand().

The maths module also defines pi as M_PI as e as M_E.

The maths macros are implemented using the function.pm module. Nested macros are allowed,
as is passing other macros with numerical defintions as arguments.

FORMAT MODULE - format.pm

This module provides a set of macros for formating strings and numbers.

The format module provides the following macros:

printf(format, arg1, arg2, ...)
The printf macro behaves in the same way as the Perl/C function printf. It takes
in a format string followed by a list of arguments to print. See the printf(3) man
page or Perl documentation for full details of the printf function.

toupper(string)
Converts input string to upper case.

toupperfirst(string)
Converts first character of input string to upper case.

tolower(string)
Converts input string to lower case.

tolowerfirst(string)
Converts first character of input string to lower case.

substr(string, offset, length)
Extracts a substring from input string. substr behaves in the same way as the Perl
substr function. offset is used to specifiy the first character of the string to
output (negative for offset from end of string), length is the length of the string
to output. If length is omitted everything from the offset is returned. For
further information on substr see the Perl documentation.

The format macros are implemented using the function.pm module.

BIGDEF MODULE - bigdef.pm

The bigdef module allows easy definition of multi-line macros. Its file name is bigdef.pm.

A multi-line macro is a macro which has a definition which spans more than one line. The
normal way to define these is to place a line continuation character at the end of each
line in the definition. However, this can be annoying and unreadable for large multi-line
macros. The bigdef module tries to improve on this by providing two keywords:

#bigdef macro definition...
The #bigdef keyword has the same syntax as #define, the only difference being the
macro definition is everything following the macro name including all following
lines up to the next #endbigdef keyword.

#endbigdef
Ends a bigdef. Everything between this keyword and the last preceding #bigdef is
included in the macro.

Any keywords found in the definition will be evaluated as normal AT THE TIME THE MACRO IS
DEFINED and any output from these will be included in the definition.

Note: The difference between bigfunc and bigdef is the time keywords in the definition are
evaluated. Bigdef evaluates them as the macro is DEFINED, bigfunc evaluates them whenever
the macro is REPLACED.

BIGFUNC MODULE - bigfunc.pm

The bigfunc module allows easy definition of multi-line macros. Its file name is
bigfunc.pm.

A multi-line macro is a macro which has a definition which spans more than one line. The
normal way to define these is to place a line continuation character at the end of each
line in the definition. However, this can be annoying and unreadable for large multi-line
macros. The bigfunc module tries to improve on this by providing two keywords:

#bigfunc macro definition...
The #bigfunc keyword has the same syntax as #define, the only difference being the
macro definition is everything following the macro name including all following
lines up to the next #endbigfunc keyword.

#endbigfunc
Ends a bigfunc. Everything between this keyword and the last preceding #bigfunc is
included in the macro.

Any keywords found in the definition will be evaluated as normal AT THE TIME THE MACRO IS
REPLACED and any output from these will be included in the definition.

Note: The difference between bigfunc and bigdef is the time keywords in the definition are
evaluated. Bigdef evaluates them as the macro is DEFINED, bigfunc evaluates them whenever
the macro is REPLACED.

DEFPLUS MODULE - defplus.pm

The defplus module allows extra information to be appended to an existing macro. Its file
name is defplus.pm.

The defplus module allows further things to be appended to existing macros. The module
implements one keyword:

#defplus macro definition...
The #defplus keyword has the same syntax as #define, the only difference being if
the macro is already defined then definition is appended to the existing definition
of the macro. If the macro is undefined then #defplus behaves in exactly the same
way as #define.

REGEXP MODULE - regexp.pm

The regexp module allows Perl regular expression replacement to be done with filepp. Its
file name is regexp.pm.

Perl regular expression replacement allows a regular expression to be searched for and
replaced with something else. Regular expressions are defined as follows:

#regexp /regexp/replacement/
It is very similar to the Perl syntax and the following Perl code will be executed
on each line of the input file:

$line =~ s/regexp/replacement/g
For users who don't understand Perl, this means replace all occurrences of regexp
in the current line with replacement.

A full description of regular expressions and possible replacements is beyond the scope of
this man page. More information can be found in the Perl documentation using the command:

perldoc perlre

Any number of regular expressions can be defined. Each regular expression is evaluated
once for each line of the input file. Regular expressions are evaluated in the order they
are defined.

Regular expressions can be undefined in the following way:

#rmregexp /regexp/replacement/
This will remove the specified regular expression.

In debugging mode the current list of regular expressions can be viewed using the pragma
keyword:

#pragma filepp ShowRegexp
When not in debugging mode, this will produce no output.

A single regular expression can also be defined on the command line using the REGEXP
macro, for example:

filepp -DREGEXP=/regexp/replacement/ -m regexp.pm inputfile

Note: the REGEXP macro must be defined BEFORE the regexp module is loaded, putting
-DREGEXP... after -m regexp.pm will not work. When using the command line approach, if
the REGEXP macro is successfully parsed as a regular expression it will be undefined from
the normal filepp macro list before processing starts. Care should obviously be taken
when escaping special characters in the shell with command line regexps.

BLC MODULE - blc.pm

The Bracket Line Continuation module causes lines to be continued if they have more open
brackets: "(" than close brackets: ")" on a line. The line will be continued until an
equal number of open and close brackets are found.

Brackets can be prevented from being counted for line continuation by escaping them with a
backslash: "\(" and "\)". Any brackets found with a preceding backslash will be ignored
when deciding if line continuation should be done and then have the backslash removed once
the full line has been found.

C MACROS MODULE - cmacros.pm

The cmacros module causes the definition of the following predefined macros to be quoted:
DATE, TIME, VERSION, BASE_FILE, FILE, (note: predefined macros are written as __MACRO__).

This makes the macros more "C" like, as the C preprocessor also puts quotes around these
macros.

C MACROS MODULE - cpp.pm

The cpp makes filepp behave in a similar manner to a C preprocessor cpp(1).

DISCLAIMER: filepp is not meant to be a drop in replacement for a C preprocessor even with
this module. I would not recommend using filepp as a C preprocessor unless you fully
understand how it differs from a real C preprocessor. The output from filepp with the cpp
module will not be the same as a real C preprocessor.

GRAB MODULE - grab.pm

The grab module is used to grab input before processing. Its file name is grab.pm.

The grab module is mainly for use in other modules, such as for.pm and bigfunc.pm. It
grabs all input from a file before any processing is done on it. This allows other
modules to do processing on the original input data before the main processing is done.
For example, the for module will store the original input inside a loop and re-use it each
time the loop is processed.

#grab macro definition...
The grab module will start grabbing of all input from the grab keyword, onwards.

#endgrab
Ends a grab. Everything between this keyword and the last preceding #grab will be
grabbed and stored for use in other modules.

Grabs can be nested if required.

When calling grab from another module, use the following functions:

Grab::StartGrab($startkeyword,$endkeyword)
$startkeyword is the keyword that StartGrab is called from. $endkeyword is the
keyword that grabbing should stop at.

@List=Grab::GetInput()
Returns a Perl list containing all input grabbed from when grab was last run.

$line=Grab::GetInputLine()
Returns the line number of the input file where grabbing last started.

FILEPP MODULE API

The behaviour of filepp can be modified or extended through the use of modules. filepp
modules are in fact perl(1) modules, and the rest of this section assumes the reader has a
knowledge of Perl.

filepp modules are perl(1) modules which extend or modify filepp's behaviour by either
calling or replacing filepp's internal functions. filepp has the Perl package name Filepp
so its internal functions can be called within modules either as Filepp::function() or
just function(). Any of filepp's internal functions can be called or replaced from within
a filepp module, the most useful ones are:

Debug($string,$number)
Print $string as debugging information if debugging is enabled. $number is
optional and can be used to set the debugging level at which $string should be
printed, lower numbers being higher priority. Command line option d prints all
debugging info for 2 and below, option dd prints all debugging information for 3
and below and option dl prints all debugging information for 1 and below. If
$number is not provided, defaults to 1.

AddProcessor($function,$pos,$type)
Allows the module to add a function named $function to filepp's processing chain.
The processing chain is a set of functions which are run on each line of a file as
it is processed. The default functions in the processing chain are ParseKeywords
which does keyword parsing and ReplaceDefines which does macro replacement.
Further functions can be added to the chain, with each function taking a string
(the current line) as input and returning the processed string as output.

By default, or if $pos is set to 0, the processor is added to the end of the
processing chain. If $pos is set to 1 the processor is added to the start of the
processing chain.

$type controls what the processor is run on. There are three options for this, 0
(default): the processor runs on everything passed to the processing chain; 1: the
processor runs on full lines only; 2: the processor runs on part lines only (a part
line is the text following a keyword such as if which needs to be parsed for
macros).

Both $pos and $type are optional parameters.

AddProcessorAfter($function,$existing,$type)
Adds function $function to the processing chain directly after existing processor
$existing. If $existing is not found then $function is added to the end of the
processing chain. Regular expression matching is used to compare $existing with
the names of the functions in the processing chain.

$type is optional.

AddProcessorBefore($function,$existing,$type)
Adds function $function to the processing chain directly before existing processor
$existing. If $existing is not found then $function is added to the start of the
processing chain. Regular expression matching is used to compare $existing with
the names of the functions in the processing chain.

$type is optional.

RemoveProcessor($function)
Removes the processor function $function from the processing chain.

$string=ReplaceDefines($string)
Replaces all macros in $string with their definitions and returns the processed
string.

AddKeyword($string,$function)
Add the keyword named $string. When the keyword is found in text processing the
function named $function will be run with everything following the keyword passed
as a single argument.

RemoveKeyword($string)
Removes the keyword named $string.

RemoveAllKeywords()
Removes all the keywords currently defined for filepp (used for the -k command line
option).

AddIfword($string)
Adds keyword named $string to Ifword list. An Ifword takes in the string following
the keyword and optionally parses it, returning a 1 if the string parses to true
and 0 for false. The default Ifwords are if, ifdef and ifndef.

RemoveIfword($string)
Removes keyword named $string from Ifword list (note: this does NOT remove the
keyword, use RemoveKeyword for that).

AddElseword($string)
Adds keyword named $string to Elseword list. An Elseword takes in the string
following the keyword and optionally parses it, returning a 1 if the string parses
to true and 0 for false. The default Elsewords are else and elif.

RemoveElseword($string)
Removes keyword named $string from Elseword list.

AddEndifword($string)
Adds keyword named $string to Endifword list. An Endifword should return a 1 to
indicate successful termination of the if block. If the Endifword returns 0 the
Endifword is ignored and filepp assumes the current if block carries on after the
Endifword. The default Endifword is endif.

RemoveEndifword($string)
Removes keyword named $string from Endifword list.

AddIncludePath($string)
Adds the include path $string to the list of directories to search for include
files (used for the -I command line option).

AddModulePath($string)
Adds the path $string to the list of directories to search for filepp modules (used
for the -M command line option).

AddOpenInputFunc($function)
Adds a $function to a list of functions to be run each time a new base input file
is opened.

AddCloseInputFunc($function)
Adds a $function to a list of functions to be run each time a new base input file
is closed.

AddOpenOutputFunc($function)
Adds a $function to a list of functions to be run each time an output file is
opened.

AddCloseOutputFunc($function)
Adds a $function to a list of functions to be run each time an output file is
closed.

AddInputFile($string)
Adds another input file to the list of files to be processed (used for adding input
files at the command line).

ChangeOutputFile($string)
Closes the current output file and attempts to open a new one named $string.

SetKeywordchar($string)
Set the initial keyword char to $string (used for the -kc command line option).

SetContchar($string)
Set the line continuation char to $string (used for the -lc command line option).

SetContrepchar($string)
Set the line continuation replacement char to $string (used for the -lr command
line option).

SetOptLineEndchar($string)
Set the optional keyword line end character to $string (used for the -lec command
line option).

SetBlankSupp(1/0)
Turns blank-line suppression on/off (1 = suppress, 0 = don't suppress). When
blank-line suppression is on, blank lines in input files will not be copied to the
output. Unlike the corresponding command-line option (-b), this function can also
have effect in the top-level file. The setting of blank-line suppression applies
to the current file being processed and all files included in the current file.

ResetBlankSupp()
Resets blank-line suppression to the command-line specified value. This only
affects the output of blank lines from the current file being processed and all
files included in the current file. In the top-level file, this always turns
blank-line suppression off.

SetEatTrail($string)
If $string is a macro, whenever the macro is replaced all blank space between the
macro's replacement and the next character on the line will be eaten. For example,
if macro foo is defined to bar and foo has been set to have it's trail eaten, the
following:

eat my foo trail

is replaced with

eat my bartrail

CheckEatTrail($string)
Returns 1 if macro $string will have it's tail eaten, 0 otherwise.

SetEnvchar($string)
Set the prefix of environment variables converted to macros (envchar) to $string
(used for -ec and -ecn command line options).

DefineEnv()
Define all environment variables as macros with prefix envchar (used for -e command
line option).

SetOutput(1/0)
Turns writing of parsed input file to output file on/off. This takes either 1
(output on) or 0 (output off) as input. When the output is turned off, the only
output produced from filepp will be that generated by modules.

SetWordBoundaries(1/0)
Turns on(1) or off(0) word boundary checking when replacing macros (used for the -w
command line option).

SetCharPerlre(1/0)
Turns on(1) or off(0) allowing of keyword prefix char and line continuation char to
be Perl regular expressions (used for the -re command line option).

UndefAll()
Undefines all currently defined macros, including predefined ones (used for the -u
command line option).

UseModule($string)
Loads a perl(1) module named $string using the Perl command require (used for the
-m command line option).

SetParseLineEnd($function)
Sets the function to determine if line continuation should be done on current line
to $function.

$string=GetNextLine()
Returns the next line (after line continuation has been dealt with) of the input
file currently being processed. Returns NULL for end of file.

Write($string)
Writes $string to the current output file.

Output($string)
Conditionally writes $string to the current output file. If output is turned on
then writes $string. Output is toggled off/on using SetOutput function.

In addition all the standard filepp keywords have equivalent functions which optionally
take a single argument. The functions have the same name as the keyword, only with a
capital first letter (eg: #define string calls the function Define(string)).

A full description of the Parse function and all the other filepp internal functions is
beyond the scope of this man page. The filepp script is well commented and hopefully
readable by a Perl programmer, so use the source Luke!

Use filepp online using onworks.net services