packages icon



 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



 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.





                                    - 1 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



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




                                    - 2 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      -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



                                    - 3 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



           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



                                    - 4 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



           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



                                    - 5 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



           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



                                    - 6 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



           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



                                    - 7 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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 "Feb 27 2007".

      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 "2007-02-27".

      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 "20:02:16".

      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:





                                    - 8 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



 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




                                    - 9 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



        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.





                                   - 10 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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.



                                   - 11 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



 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.





                                   - 12 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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.





                                   - 13 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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.



                                   - 14 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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



                                   - 15 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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.




                                   - 16 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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__).




                                   - 17 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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.






                                   - 18 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



 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.




                                   - 19 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



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





                                   - 20 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



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





                                   - 21 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



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





                                   - 22 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



      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!




                                   - 23 -       Formatted:  October 20, 2018






 FILEPP(1)                     Version: 1.8.0                      FILEPP(1)
                                 Feb 27 2007



 BUGS
      filepp has no known bugs, only "features".  If you find any
      "features", please report them to the author.

 COPYING
      Copyright (C) 2000-2007 Darren Miller

      filepp is free software; you can redistribute it and/or modify it
      under the terms of the GNU General Public License as published by the
      Free Software Foundation; either version 2 of the License, or (at your
      option) any later version.

      This program is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.

      You should have received a copy of the GNU General Public License
      along with this program; see the file COPYING.  If not, write to the
      Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

 SEE ALSO
      cpp(1), perl(1)

 AUTHOR
      Darren Miller <darren@cabaret.demon.co.uk>.




























                                   - 24 -       Formatted:  October 20, 2018