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.

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

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

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