ipp - Include Pre-Processor

ipp [-D name=value] [-S includedir] [-I includedir] [-s includefile] [-i includefile] [-M options] [-P path] [-m mapfile] [-N nosynclines] [-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:

#include 'file'

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

These characters have a special meaning in filenames:

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:

If you want to include the 5 newest include files of the news directory with file names like CW20000131.inc, you may write:

  #include 'news/*.inc' IPP_REVERSE IPP_MAX=5

In the files included with the CW#include 'pattern' directive, the following variables are set and can be read using CW$(name):

Keep in mind that a directive without wildcards does not set these variables.

In analogon to Perl's CWuse statement, ipp provides a special variant of CW#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 CW#include's and only once from the CW#use directives.

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 CWipp is invoked as a piece of CWWML, the final output file may depend on other files. You can tell CWipp about these hidden dependencies by using the CW#depends variant , e.g.

  #depends 'foo.dat'
  #depends "*/*.dat"
  #depends <file>

The contents of the file is not inserted, only informations about dependencies are updated.

All include commands insert some special stuff to help CWWML keeping track of input line numbers. This feature may be disabled by appending the string CWIPP_NOSYNCLINES to the CW#include (or its variants) command. See also the CW-N flag.

You can add

   name[=value]

pairs at the end of CW#include (and CW#use) directives to let CW$(name) interpolate to CWvalue (or CW1 if CW=value is missing) in this include file and all its recursively included files.

There are the following forms of the CW$(name) syntax, similar to the functionality any Bourne Shell provides: `Use Only Value': The standard interpolation.

 if (exists(n)) 
     expandto(valueof(n))
 else 
     expandto("")

 name := string

 if (exists(n)) 
     expandto(valueof(n))
 else 
     expandto(string)

 if (exists(n)) 
     expandto(valueof(n))
 else 
     expandto(string)
     name := string

 if (exists(n)) 
     expandto(string)
 else 
     expandto("")

 if (exists(n))
     expandto("")
 else 
     expandto(string)

 if (exists(n))
     expandto(valueof(n))
 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 CWipp treat inner expressions first. With this example below

  $(foo=bar)
  $(foo:-$(foo=quux))

Bourne shells will show CWbar whereas CWipp will print CWquux.

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)

The strings CW__FILE__ and CW__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 (`CW#') 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 CW\#, i.e. prefix it with an escaping backslash.

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 CW__END__ in constructs like CW$(SHORTENING:+__END__), so that the processing is only stopped when the variable SHORTENING is set.

It removes all occurences of the pattern

  \<whitespace>*<newline><whitespace>*

Use this to let one or more lines to be concatenated.

-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 CW$(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 CWtype::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 CWtype::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 CWstdout if no such option is specified or outputfile is "CW-".

-v

This sets verbose mode where some processing information will be given on the console.

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

 Denis Barbier
 barbier@engelschall.com