ipp - Include Pre-Processor ipp [-D name=value] [-S includedir] [-I includedir] [-s includefile] [-i includefile] [-P path] [-m mapfile] [-o outputfile] [-v] inputfile ... The ipp program reads all inputfiles and recursively expands all #include 'file' #include "file" #include <file> directives by substituting the directive with the contents of the file. The output is send to stdout or to outputfile. The files are searched according to the following scheme: The file is searched in the current working directory only. Use this to force the loading of a local file. The file is searched in all directories given by the -I option in the right-to-left order they are specified on the command line. First the file is searched in the system wide ipp include directory specified with the -S option. Second if it was not not found there it is searched for in all directories given by the -I option. And it provides six additional features:

Special `Use' Variant
In analogon to Perl's use statement, ipp provides a special variant of #include: #use type::category::file This internally is equivalent to the directive #include <category/file.type> plus the special semantic that the include file is included (=used) only once, i.e. multiple inclusion is automatically avoided. In other words #include 'file' #include 'file' #use 'file' #use 'file' results in three inclusions of 'file'. Two from the #include's and only once from the #use directives.

Include Variables
You can add name[=value] pairs at the end of #include (and #use) directives to let $(name) interpolate to value (or 1 if =value is missing) in this include file and all its recursively included files. There are the following forms of the $(name) syntax, similar to the functionality any Bourne Shell provides: `Use Only Value': The standard interpolation. if (exists(name)) expandto(valueof(name)) else expandto("") `Use Default String': The standard interpolation with a default value. if (exists(name)) expandto(valueof(name)) else expandto(string) `Use Default String and Assign': The standard interpolation with a default value and additional assignment for later use. if (exists(name)) expandto(valueof(name)) else expandto(string) name := string `Use Alternate String'. The replacement interpolation. if (exists(name)) expandto(string) else expandto("") `Use Negative Alternate String'. The replacement interpolation with negated logic. if (exists(name)) expandto("") else expandto(string) `Indicate Error If Unset'. The error message interpolation. This can also be used in conjunction with the above variants. if (exists(name)) expandto(valueof(name)) else Error(string) Notice the possibility to do simple non-nestable If-Then-Else constructs: $(foo:+string_when_set)$(foo:*string_when_not_set) This is equivalent to the following pseudo-code: if (exists(foo)) expandto(string_when_set) else expandto(string_when_not_set)

Implicit IPP Variables
The strings __FILE__ and __LINE__ are always substituted by the currently processed include file and the current line number.

Comments
IPP provides support for two types of comments: This type of comment is like the one found in Bourne-Shell or Perl, i.e. any line which starts with a sharp symbol (`#') is entirely (i.e. including the newline at the end) removed from the input. Additionally these lines can have whitespaces in front of the sharp symbol. When you really need a sharp symbol at the start of a line you can use \#, i.e. prefix it with an escaping backslash. This type of comment is like the one found in the C programming language, i.e. any characters between the start delimiter `/*' and the end delimiter `*/' are removed from the input. These block comments can be nested. The parser used to strip these comments dramatically increase compilation time (up to 50%!), so use them only for debugging purpose.

End-Of-File Stopping
It stops processing the current include file when a line containing just __END__ occurs. Use this to append POD documents to include files for documentation purposes as in Perl.

End-Of-Line Continuation
It removes all occurences of the pattern \<whitespace>*<newline><whitespace>* Use this to let one or more lines to be concatenated. Defines a variable the for the initial inputfile the same way you define ones with the #include for include files. The variable can be interpolated via $(name) in all files. Adds a system wide include directory. You can use this option more than once. The files are searched in left-to-right order. This adds an entry to the include path where include files are searched for. You can use this option more than once. The files are searched in left-to-right order. The current working directory is always appended as the last directory to this list. Pre-load a particular include file, i.e. virtually adds a #include <includefile> in front of inputfile. Use this to automatically load default system include files. You can also use the syntax type::category::file which leads to a virtually added #include <category/file.type> Pre-loads a particular include file, i.e. virtually adds a #include "includefile" in front of inputfile. Use this to automatically load default user include files. You can also use the syntax type::category::file which leads to a virtually added #include "category/file.type" This sets up one or more prolog program path which are applied to each single input file just before real processing starts. Use this to pre-process the data. The program gets the input filename to process as its first argument. When it wants to filter it it has to overwrite the file. This adds an entry to the list of mapfiles where a mapping between obsolete include file names and current ones can be found. You can use this option more than once. The mapfiles can contain the following lines: # comment line <blank line> <oldname>[,<oldname>] <newname> \[S|W|E: <text>\] Example: <std/headfoot.wml>,wml::std::headfoot wml::OBSOLETE::std::headfoot [S] This redirects the output to outputfile. Usually the output will be send to stdout if no such option is specified or outputfile is "-". This sets verbose mode where some processing information will be given on the console. Ralf S. Engelschall rse@engelschall.com www.engelschall.com