NAME
gpp - Bash-based preprocessor for anything
SYNOPSIS
gpp [-D name[=value]] [-f file | [-i input-file]
[-o output-file]] [-n count] [-s symbol]
[-R macroline-replacement-text] [-u [-u]]
[shell [argument] ...]
ETYMOLOGY
gpp stands for General Preprocessor.
DESCRIPTION
gpp lets a developer embed directives written in GNU
Bash (this can be changed) into any text document.
These directives are used to automate the writting of
parts of the document.
The preprocessing directives start with a symbol
(or text string) specified by the developer. By default
this symbol is @ (at).
Any line starting with @< (where @ is the selected
symbol for preprocessing directives) or @>, or is
between a line starting with @< and a line starting
with @>, is parsed as a line, written in Bash, that
is executed during preprocessing. A @< line must have
an associated @> line somewhere after it, all lines
between them are parsed as preprocessing directives.
A @> does however not need an associated @< line
somewhere before it, making @> suitable for single
line directives.
Preprocessing directives can also be inline. For this,
use @(COMMAND) where COMMAND is the Bash code to run.
Additionally, gpp supports variable substitution.
@{VARIABLE} will be replaces by the value if the
variable (possibility environment variable) VARIABLE.
gpp supports all modifiers thats Bash (or which ever
shell is selected) supports. For example, if you want
the value to be included but uppercase you can write
@{VARIABLE^^}, or @{VARIABLE,,} for lowercase. gpp
also supports mathematical expressions that the via
the shells $((EXPRESSION)) syntax, by using
@((EXPRESSION)).
Everything that is not a preprocessing directive is
echo verbatim, except all @@ are replaced by @.
OPTIONS
-D name=value
Set the environment variable name to hold
the value value.
-D name
Set the environment variable name to hold
the value 1.
-f file
Equivalent to -i FILE -o FILE.
-i input-file
Select file to process. Default value is /dev/stdin.
-n count
Process the file recursively count times.
Default value is 1.
-o output-file
Select output file. Defaults value is /dev/stdout.
-R macroline-replacement-text
Text to replace macrolines with in the output.
You may for example want to use % for TeX files.
Default value is the empty string.
-s symbol
Set the prefix symbol for preprocessor directives.
Default value is @.
-u
Clear the shebang line, remove it if this flag
is used twice. If used twice, an empty line
will be inserted after the new first line.
OPERANDS
shell
The shell to run instead of bash. The shell
must be compatible with POSIX shell.
argument ...
Command line arguments for the shell.
EXAMPLES
Conditional hello world
This example only includes the "Hello world" line if
the environment variable HELLO is defined and is not
empty.
@>if [ -z "$HELLO" ]; the
Hello world
@>fi
Mutliline preprocessor directive
This example creates the function uppercase() that
convert lower case ASCII leters to uper case.
@<uppercase () {
lower=qwertyuiopasdfghjklzxcvbnm
upper=QWERTYUIOPASDFGHJKLZXCVBNM
sed y/$lower/$upper/ <<<"$*"
@>}
Inline directives
This example uses the uppercase() function above to
convert the user's username to upper case. If the user's
username is john, the code will expand to You are logged
in as JOHN.
You are logged in as @(uppercase $USER).
Variable expansions
In this example, if the user's username john, the code
will expand to You are logged in as john.
You are logged in as @{USER}.
Variable expansion with substitution
This example uses a substitution mechanism in Bash to
convert the first letter in a variable to upper case.
In this example, if the user's username john, the code
will expand to You are logged in as John.
You are logged in as @{USER^}.
RATIONALE
Programmers need more automation when we write software
and documentation. An unrestricted preprocessor lets
you automate just about anything. Of course, it can be
used for anything, must just writing software and
documentation. Preprocessing can be used for more than
automation, it can also be used to increase the flexibility
of the work.
C is one of the few languages that includes a preprocessor,
some times it is not enough; and all languages need
preprocessors.
SEE ALSO
bash(1), jpp(1), cpp(1), env(1)
