path: root/gpp.1

.TH GPP 1 gpp
.SH NAME
gpp - Bash-based preprocessor for anything

.SH SYNOPSIS
.B gpp
[-D
.IR name [= value ]]
[-f
.I file
| [-i
.IR input-file ]
[-o
.IR output-file ]]
[-n
.IR count ]
[-R
.IR macroline-replacement-text ]
[-s
.IR symbol ]
[-u [-u]]
.RI [ shell
.RI [ argument ]\ ...]

.SH ETYMOLOGY
gpp stands for General Preprocessor.

.SH DESCRIPTION
.B 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.
.PP
The preprocessing directives start with a symbol (or
text string) specified by the developer. By default
this symbol is
.B @
(at).
.PP
Any line starting with 
.B @<
(where
.B @
is the selected symbol for preprocessing directives) or
.BR @> ,
or is between a line starting with
.B @
and a line starting with
.BR @> ,
is parsed as a line, written in
.BR bash (1),
that is executed during preprocessing. A
.B @<
line must have an associated
.B @>
line somewhere after it, all lines between them are
parsed as preprocessing directives. A
.B @>
does however not need an associated
.B @<
line somewhere before it, making
.B @>
suitable for single line directives.
.PP
Preprocessing directives can also be inline. For this, use
.BI @( COMMAND )
where
.I COMMAND
is the
.BR bash (1)
code to run. Additionally,
.B gpp
supports variable substitution.
.BI @{ VARIABLE }
will be replaces by the value if the variable
(possibility environment variable)
.IR VARIABLE .
.B gpp
supports all modifiers that
.BR bash (1)
(or which ever
.I shell
is selected) supports. For example, if you want the
value to be included but uppercase you can write
.BR @{ \fIVARIABLE\fP ^^} ,
or
.BI @{ VARIABLE ,,}
for lowercase.
.B gpp
also supports mathematical expressions that the via
the shells
.BI $(( EXPRESSION ))
syntax, by using
.BR @(( \fIEXPRESSION\fP )) .
.PP
Everything that is not a preprocessing directive is
echo verbatim, except all
.B @@
are replaced by
.BR @ .

.SH OPTIONS
The
.B gpp
utility conforms to the Base Definitions volume of POSIX.1-2017,
.IR "Section 12.2" ,
.IR "Utility Syntax Guidelines" .
.PP
The following option is supported:
.TP
.BR \-D\  \fIname\fP\fB=\fP\fIvalue\fP
Set the environment variable \fIname\fP to hold
the value \fIvalue\fP.
.TP
.BR \-D\  \fIname\fP
Set the environment variable \fIname\fP to hold
the value 1.
.TP
.BI \-f\  file
Equivalent to \-i
.I file
\-o
.IR file .
.TP
.BI \-i\  input-file
Select file to process. If
.B -
is specified, /dev/stdin will be used.
Default value is /dev/stdin.
.TP
.BI \-n\  n
Process the file recursively
.I n
times. Default value is 1.
.TP
.BI \-o\  output-file
Select output file. If
.B -
is specified, /dev/stdout will be used.
Default value is /dev/stdout.
.TP
.BI \-R\  macroline-replacement-text
Text to replace macrolines with in the output.
You may for example want to use
.B %
for TeX files.
Default value is the empty string.
.TP
.BI \-s\  symbol
Set the prefix symbol for preprocessor directives.
Default value is
.BR @ .
.TP
.B \-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.

.SH OPERANDS
The following operands are supported:
.TP
.I shell
The shell to run instead of
.BR bash .
The
.I shell
must be compatible with POSIX shell.
.TP
.IR argument \ ...
Command line arguments for the shell.

.SH STDIN
The
.B gpp
utility does not use the standard input.

.SH INPUT FILES
The input file may be of any type, except it may not be a directory.

.SH ENVIRONMENT VARIABLES
The following environment variables affects the execution of
.BR gpp :
.TP
.B PATH
Default. See to the Base Definitions volume of POSIX.1-2017, Section 8.3, Other Environment Variables.
.PP
.B gpp
will set the environment variable
.B _GPP
to the zeroth argument
.B gpp
was execute with (the name of the command or path to the command).

.SH ASYNCHRONOUS EVENTS
Default.

.SH STDOUT
The
.B gpp
utility does not use the standard output.

.SH STDERR
The standard error is only used for diagnostic messages.

.SH OUTPUT FILES
The output file may be of any type, except it may not be a directory.

.SH EXTENDED DESCRIPTION
None.

.SH EXIT STATUS
.TP
0
Successful completion.
.TP
1
An error occurred.

.SH CONSEQUENCES OF ERRORS
Default.

.SH APPLICATION USAGE
None.

.SH EXAMPLES
.SS Conditional hello world
This example only includes the
.RB \(dq "Hello world" \(dq
line if the environment variable
.B HELLO
is defined and is not empty.
.PP
.nf
@>if [ -z "$HELLO" ]; the
Hello world
@>fi
.fi

.SS Mutliline preprocessor directive
This example creates the function
.BR uppercase ()
that convert lower case ASCII leters to uper case.
.PP
.nf
@<uppercase () {
	lower=qwertyuiopasdfghjklzxcvbnm
	upper=QWERTYUIOPASDFGHJKLZXCVBNM
	sed y/$lower/$upper/ <<<"$*"
@>}
.fi

.SS Inline directives
This example uses the
.BR uppercase ()
function above to convert the user's username
to upper case. If the user's username is
.BR john ,
the code will expand to
.B You are logged in as JOHN.
.PP
.nf
You are logged in as @(uppercase $USER).
.fi

.SS Variable expansions
In this example, if the user's username
.BR john ,
the code will expand to
.B You are logged in as john.
.PP
.nf
You are logged in as @{USER}.
.fi

.SS 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
.BR john ,
the code will expand to
.B You are logged in as John.
.PP
.nf
You are logged in as @{USER^}.
.fi

.SS Include paths
This example lets the user define a colon-separated
list of paths, in the
.B INCLUDEPATH
environment variable, in which to look for files to
either include directly into the source that is being
preprocessed, using the
.BR include_verbatim ()
function, directly into the preprocessor, using the
.BR include ()
function, or into the source that is being processed
but after preprocessing it with
.BR gpp ,
using the
.BR include_verbatim ()
and piping it into
.BR gpp .
.PP
.nf
locate () (
	IFS=:
	for d in $INCLUDEPATH; do
		if [ -f \(dq$d/$1\(dq ]; then
			printf \(aq%s\en\(aq \(dq$d/$1\(dq
			exit 0
		fi
	done
	printf \(aqCannot locate %s\en\(aq \(dq$1\(dq >&2
	exit 1
)

locatex () {
	local method
	local file
	set -e
	method=\(dq$1\(dq
	file=\(dq$2\(dq
	test -n \(dq$method\(dq
	test -n \(dq$file\(dq
	shift 2
	$method -- \(dq$(locate \(dq$file\(dq)\(dq \(dq$@\(dq
}

include () {
	locatex . \(dq$@\(dq
}

include_verbatim () {
	locatex cat \(dq$@\(dq
}
.fi

.SH 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.
.PP
C is one of the few languages that includes a preprocessor,
some times it is not enough; and all languages need
preprocessors.

.SH NOTES
None.

.SH BUGS
None.

.SH FUTURE DIRECTIONS
None.

.SH SEE ALSO
.BR bash (1),
.BR jpp (1),
.BR cpp (1),
.BR env (1)