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
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:
- #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 <file>
- 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 <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.
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 <file>
The contents of the file is not inserted, only information about dependencies
are updated.
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.
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 occurences of the pattern
\<whitespace>*<newline><whitespace>*
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 <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>
- -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
<blank line>
<oldname>[,<oldname>] <newname> \[S|W|E: <text>\]
Example:
<std/headfoot.wml>,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