#!@PATH_PERL@
eval 'exec @PATH_PERL@ -S $0 ${1+"$@"}'
    if $running_under_some_shell;

##  IPP -- Include Pre-Processor
##  Copyright (c) 1997,1998,1999 Ralf S. Engelschall, All Rights Reserved.
##  Copyright (c) 2000 Denis Barbier, All Rights Reserved.

use strict;
use warnings;

use lib '@INSTALLPRIVLIB@';
use lib '@INSTALLARCHLIB@';
use lib "/usr/share/wml";

use TheWML::Backends::IPP::Main ();

TheWML::Backends::IPP::Main->new( argv => \@ARGV )->main;

##EOF##
__END__

=head1 NAME

ipp - Include Pre-Processor

=head1 SYNOPSIS

B<ipp>
[B<-D> I<name>B<=>I<value>]
[B<-S> I<includedir>]
[B<-I> I<includedir>]
[B<-s> I<includefile>]
[B<-i> I<includefile>]
[B<-M> I<options>]
[B<-P> I<path>]
[B<-m> I<mapfile>]
[B<-N> I<nosynclines>]
[B<-o> I<outputfile>]
[B<-v>]
I<inputfile> ...

=head1 DESCRIPTION

The F<ipp> program reads all I<inputfile>s 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 F<stdout> or to I<outputfile>. The files are searched
according to the following scheme:

=over

=item B<#include 'file'>

The file is searched in the current working directory B<only>. Use
this to force the loading of a local file.

=item B<#include "file">

The file is searched in all directories given by the B<-I> option in the
right-to-left order they are specified on the command line.  Note that
a B<-I .> implicit option is automatically appended to command-line
options, then files are first searched in current directory.

=item B<#include E<lt>fileE<gt>>

First the file is searched in the system wide C<ipp> include directory
specified with the B<-S> option. Second if it was not not found there it is
searched for in all directories given by the B<-I> option.

=back

And it provides eight additional features:

=head2 B<Using Wildcards>

These characters have a special meaning in filenames:

=over 4

=item C<*>   Matches any string, including the null string.

=item C<?>   Matches any single character.

=item C<[...]>  Like bracketed expressions in regexps, matches any of the
             enclosed characters.

=back

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 B<#include 'pattern'> directive:

=over 4

=item C<IPP_SORT=I<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).

=item C<IPP_REVERSE=I<scheme>>  As above, but resulting list of filenames
          is sorted in reverse order.

=item C<IPP_MAX=I<nmax>>        Only I<nmax> files are included.

=back

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

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

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

=over 4

=item C<IPP_THIS>  the full name of the included source file including
                       path and extension

=item C<IPP_PREV>  the full name of the previous included file, unset
                       in the first file

=item C<IPP_NEXT>  the full name of the next included file, unset
                       in the last file

=back

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

=head2 B<Special `Use' Variant>

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

=head2 B<Special `Depends' Variant>

You can easily write fragments of Makefiles with the B<-M> flag (see
below) to keep tracks of which files the output file depends on, When
C<ipp> is invoked as a piece of C<WML>, the final output file may depend
on other files.  You can tell C<ipp> about these hidden dependencies by
using the C<#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.

=head2 B<Input Line Synchronization>

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

=head2 B<Include Variables>

You can add

   name[=value]

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

There are the following forms of the C<$(name)> syntax, similar to the
functionality any Bourne Shell provides:

=over 4

=item o   B<C<$(name)>>

`Use Only Value': The standard interpolation.

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

=item o   B<C<$(name=string)>>

`Assign Value': Set a variable.

 name := string

=item o   B<C<$(name:-string)>>

`Use Default String': The standard interpolation
with a default value.

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

=item o   B<C<$(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

=item o   B<C<$(name:+string)>>

`Use Alternate String'. The replacement interpolation.

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

=item o   B<C<$(name:*string)>>

`Use Negative Alternate String'. The replacement interpolation with negated
logic.

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

=item o   B<C<$(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)

=back

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 C<ipp> treat inner
expressions first.  With this example below

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

Bourne shells will show C<bar> whereas C<ipp> will print C<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)

=head2 B<Implicit IPP Variables>

The strings C<__FILE__> and C<__LINE__> are always substituted by the
currently processed include file and the current line number.

=head2 B<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 (`C<#>') 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 C<\#>, i.e. prefix it with an escaping
backslash.

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

=head2 B<End-Of-Line Continuation>

It removes all occurrences of the pattern

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

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

=head1 OPTIONS

=over

=item B<-D> I<name>B<=>I<value>

Defines a variable the for the initial I<inputfile> the same way you define
ones with the B<#include> for include files.  The variable can be interpolated
via C<$(name)> in all files.

=item B<-S> I<includedir>

Adds a system wide include directory.  You can use this option more than once.
The files are searched in right-to-left order.

=item B<-I> 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.

=item B<-s> I<includefile>

Pre-load a particular include file, i.e. virtually adds a

  #include <includefile>

in front of I<inputfile>. Use this to automatically load default system
include files. You can also use the syntax C<type::category::file>
which leads to a virtually added

  #include <category/file.type>

=item B<-i> I<includefile>

Pre-loads a particular include file, i.e. virtually adds a

  #include "includefile"

in front of I<inputfile>. Use this to automatically load default user include
files.   You can also use the syntax C<type::category::file> which leads to a
virtually added

  #include "category/file.type"

=item B<-M> I<options>

Output a rule suitable for `make' describing the dependencies of each output
file, as `gcc' does. It has only sense when the B<-o> option is used.

The B<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 B<M> flag option deletes the system files from the list of dependencies.

=item B<-P> I<path>

This sets up one or more prolog program I<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.

=item B<-m> I<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]

=item B<-N> I<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.

=item B<-o> I<outputfile>

This redirects the output to I<outputfile>. Usually the output
will be send to C<stdout> if no such option is specified or
I<outputfile> is "C<->".

=item B<-v>

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

=back

=head1 AUTHORS

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

 Denis Barbier
 barbier@engelschall.com

=cut

##EOF##
# vim:ft=perl