IPP(1)

📦
version 2.32.0 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing

💖 IPP(1) — like, the Include Pre-Processor bestie 💖

EN Tools · section 1, the manual pages

okay so. you know how you have a million little files and you want them to become, like, one big file? that's this. it's the Include Pre-Processor and it's genuinely iconic. let's get into it 💅

✨ NAME ✨

ipp — Include Pre-Processor. yeah that's it. that's the whole name. short king energy 👑

✨ 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 ✨

so ipp reads all your *inputfile*s and recursively expands every single one of these directives:

#include 'file'
#include "file"
#include <file>

basically it swaps the directive out for the actual contents of the file. the output goes to stdout or to outputfile, whichever you picked. and the way it hunts down those files? here's the scheme, no cap:

  • #include 'file' — the file is searched in the current working directory only. use this when you want to force the loading of a local file. no wandering off, periodt.
  • #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. and heads up: a -I . implicit option is automatically appended to command-line options, so files get searched in the current directory first.
  • #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 (yes, the double negative is in the original, i'm just the messenger 😭), it is searched for in all directories given by the -I option.

and it provides eight additional features. eight!! an overachiever fr fr 🎀

🌸 Using Wildcards 🌸

these characters have a special meaning in filenames, bestie:

  • * — 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 the 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. like, at all. don't come for me, it's just how it is 😭

🦋 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. the #use girlies are efficient like that 💅

🌈 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. it's giving "i know her but i'm not inviting her to the party" 🙈

✨ Input Line Synchronization ✨

all include commands insert some special stuff to help "WML" keep 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. it's giving inheritance, main character energy 👑

there are the following forms of the $(name) syntax, similar to the functionality any Bourne Shell provides:

  • $(name) — Use Only Value: the standard interpolation.
if (exists(name))
    expandto(valueof(name))
else
    expandto("")
  • $(name=string) — Assign Value: set a variable.
name := string
  • $(name:-string) — Use Default String: the standard interpolation with a default value.
if (exists(name))
    expandto(valueof(name))
else
    expandto(string)
  • $(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
  • $(name:+string) — Use Alternate String. the replacement interpolation.
if (exists(name))
    expandto(string)
else
    expandto("")
  • $(name:*string) — Use Negative Alternate String. the replacement interpolation with negated logic.
if (exists(name))
    expandto("")
else
    expandto(string)
  • $(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". so like, don't assume. they're different girlies.

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. free variables, no setup required, we love a no-effort win 🫶

🍓 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. conditional stopping, we stan a flexible queen ✨

⭐ 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. gluing lines together like it's nothing 💅

✨ OPTIONS ✨

okay bestie, this is the part where we get to the good stuff 💅 every single flag, no skips, no cap.

  • -D name=value — defines a variable for the initial inputfile, exactly the same way you'd define one with the #include for include files. then you can interpolate it anywhere with $(name) in all the files 🫶
  • -S includedir — adds a system-wide include directory. you can totally use this option more than once, and the files get searched in right-to-left order. noted. 📝
  • -I includedir — adds an entry to the include path, which is where include files get searched for. yes, you can use this more than once too. also searched in right-to-left order. and here's the little plot twist: the current working directory is always appended as the last directory to this list, so it ends up being searched first. iconic behavior tbh 🌈
  • -s includefile — pre-loads a particular include file, aka it virtually adds
#include <includefile>

in front of inputfile. use this to automatically load default system include files. bonus: 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, aka virtually adds
#include "includefile"

in front of inputfile. use this to automatically load default user include files. and yeah, same deal with the syntax: type::category::file leads to a virtually added

#include "category/file.type"
  • -M options — outputs a rule suitable for make describing the dependencies of each output file, just like gcc does. it only has sense when the -o option is used, so don't skip that part bestie 😭

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 — sets up one or more prolog program path, which get 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 — 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 that whole feature. bye bestie 👋
  • -o outputfile — redirects the output to outputfile. usually the output will be sent to stdout if no such option is specified, or if outputfile is "-". lowkey the most-used flag in the group chat fr fr 💖
  • -v — sets verbose mode, where some processing information will be given on the console. she's chatty and we love that for her 🎀

👑 AUTHORS 👑

the legends who made this happen, show them some respect:

  • Ralf S. Engelschall rse@engelschall.com www.engelschall.com
  • Denis Barbier barbier@engelschall.com

and that's a wrap, bestie 🦋 this page is from EN Tools, dated 2020-11-29, and lives at IPP(1). go forth and preprocess slayfully ✨💅

📦 where this page comes from