--- name: "wml_p1_ipp" section: "1" platform: "linux" package: "wml" version: "2.32.0~ds1-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/wml_p1_ipp" --- # wml\_p1\_ipp(1) Include Pre-Processor ## NAME ipp - Include Pre-Processor ## SYNOPSIS **ipp** \[**-D** *name***=***value*\] \[**-S** *includedir*\] \[**-I** *includedir*\] \[**-s** *includefile*\] \[**-i** *includefile*\] \[**-M** *options*\] \[**-P** *path*\] \[**-m** *mapfile*\] \[**-N** *nosynclines*\] \[**-o** *outputfile*\] \[**-v**\] *inputfile* ... ## DESCRIPTION The *ipp* program reads all *inputfile*s and recursively expands all ``` #include 'file' #include "file" #include ``` 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: - **#include 'file'** The file is searched in the current working directory **only**. Use this to force the loading of a local file. - **#include "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. Note that a **-I .** implicit option is automatically appended to command-line options, then files are first searched in current directory. - **#include \** 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 eight additional features: ### Using Wildcards These characters have a special meaning in filenames: - "\*" Matches any string, including the null string. - "?" Matches any single character. - "\[...\]" Like bracketed expressions in regexps, matches any of the enclosed characters. If you want to include all your templates, you may write ``` #include "*.tmpl" ``` With the following parameters you can control the order and the number of included files using the **#include 'pattern'** directive: - "IPP\_SORT=*scheme*" Specify a sort criterion to include files. There are actually 3 different criteria : date (files are sorted according to their last modification time), name (this is the default) and numeric (filenames are sorted numerically). - "IPP\_REVERSE=*scheme*" As above, but resulting list of filenames is sorted in reverse order. - "IPP\_MAX=*nmax*" Only *nmax* files are included. If you want to include the 5 newest include files of the news directory with file names like `"20000131.inc"`, you may write: ``` #include 'news/*.inc' IPP_REVERSE IPP_MAX=5 ``` In the files included with the `"#include 'pattern'"` directive, the following variables are set and can be read using `"$(name)"`: - "IPP\_THIS" the full name of the included source file including path and extension - "IPP\_PREV" the full name of the previous included file, unset in the first file - "IPP\_NEXT" the full name of the next included file, unset in the last file Keep in mind that a directive without wildcards does not set these variables. ### 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 ``` 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. ### Special \`Depends' Variant You can easily write fragments of Makefiles with the **-M** flag (see below) to keep tracks of which files the output file depends on, When `"ipp"` is invoked as a piece of `"WML"`, the final output file may depend on other files. You can tell `"ipp"` about these hidden dependencies by using the `"#depends"` variant , e.g. ``` #depends 'foo.dat' #depends "*/*.dat" #depends ``` The contents of the file is not inserted, only information about dependencies are updated. ### Input Line Synchronization All include commands insert some special stuff to help `"WML"` keeping track of input line numbers. This feature may be disabled by appending the string `"IPP_NOSYNCLINES"` to the `"#include"` (or its variants) command. See also the `"-N"` flag. ### 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: - o **"$(name)"** \`Use Only Value': The standard interpolation. ``` if (exists(name)) expandto(valueof(name)) else expandto("") ``` - o **"$(name=string)"** \`Assign Value': Set a variable. ``` name := string ``` - o **"$(name:-string)"** \`Use Default String': The standard interpolation with a default value. ``` if (exists(name)) expandto(valueof(name)) else expandto(string) ``` - o **"$(name:=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 ``` - o **"$(name:+string)"** \`Use Alternate String'. The replacement interpolation. ``` if (exists(name)) expandto(string) else expandto("") ``` - o **"$(name:\*string)"** \`Use Negative Alternate String'. The replacement interpolation with negated logic. ``` if (exists(name)) expandto("") else expandto(string) ``` - o **"$(name:?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) ``` Previous constructs may be nested when variable expansion contains no parenthesis. You may for instance need these forms: \`Set a variable if unset'. ``` $(var=$(var:-string)) ``` \`Redefine a variable if it is already set.' ``` $(var=$(var:+string)) ``` Notice that nested expressions are not handled as shells do. In shells expressions are treated from left to right, whereas `"ipp"` treat inner expressions first. With this example below ``` $(foo=bar) $(foo:-$(foo=quux)) ``` Bourne shells will show `"bar"` whereas `"ipp"` will print `"quux"`. It is also possible to undefine a variable. To do so, assign an empty value to this variable, e.g. ``` $(foo=) ``` Notice the possibility to do simple 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 up-to-end-of-line 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. ### 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. You can use `"__END__"` in constructs like `"$(SHORTENING:+__END__)"`, so that the processing is only stopped when the variable SHORTENING is set. ### End-Of-Line Continuation It removes all occurrences of the pattern ``` \** ``` Use this to let one or more lines to be concatenated. ## OPTIONS - **-D** *name***=***value* 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. - **-S** *includedir* Adds a system wide include directory. You can use this option more than once. The files are searched in right-to-left order. - **-I** *includedir* 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 right-to-left order. The current working directory is always appended as the last directory to this list, and so is searched first. - **-s** *includefile* Pre-load a particular include file, i.e. virtually adds a ``` #include ``` 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 ``` - **-i** *includefile* 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" ``` - **-M** *options* Output a rule suitable for \`make' describing the dependencies of each output file, as \`gcc' does. It has only sense when the **-o** option is used. The **D** flag option writes the rule to a dependency file. The name of this file is obtained by replacing the suffix of the output file by ".d". The **M** flag option deletes the system files from the list of dependencies. - **-P** *path* 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. Each program receives the data to act on as STDIN and has to produce the filtered data on STDOUT. - **-m** *mapfile* 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 [,] \[S|W|E: \] ``` Example: ``` ,wml::std::headfoot wml::OBSOLETE::std::headfoot [S] ``` - **-N** *nosynclines* By default, WML inserts some instructions to synchronize line numbers, which are then interpreted in passes 2 and 3. This option disables this feature. - **-o** *outputfile* This redirects the output to *outputfile*. Usually the output will be send to `"stdout"` if no such option is specified or *outputfile* is "`"-"`". - **-v** This sets verbose mode where some processing information will be given on the console. ## AUTHORS ``` Ralf S. Engelschall rse@engelschall.com www.engelschall.com Denis Barbier barbier@engelschall.com ```