path: root/doc/info/gpp.texinfo

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename gpp.info
@settitle ?{GPP}
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Development
@direntry
* ?{GPP}: (?{GPP}).          Bash-based preprocessor for anything
@end direntry


@copying
Copyright @copyright{} 2013, 2015 Mattias Andrée

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@ifnottex
@node Top
@top gpp -- Bash-based preprocessor for anything
@insertcopying
@end ifnottex

@titlepage
@title gpp
@subtitle Bash-based preprocessor for anything
@author by Mattias Andrée (maandree)

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                        Brief overview of @command{?{GPP}}.
* Invoking::                        Invoking @command{?{GPP}}.
* Syntax::                          Syntax of @command{?{GPP}}.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

General Preprocessor (gpp) is a preprocessor
based on GNU Bash that can be used for anything.

By default an at-sign (@@) is used as prefix
for preprocessor directives, but any single
single character can be used. If the prefix
symbol is directly followed by itself it results
to the symbol itself rather than a preprocessor
directive.

A file written with gpp contains, text that
can be in any format, gpp does not care how
it is formatted, and lines written in GNU Bash
that are executed and termine which part of
the text should be keept and how it should
be repeated. A line can also be partially
written in GNU Bash to modify it. Each line
that is not in GNU Bash as actually treated
as a echo instruction.

The preprocessor will try to keep the lines in
the output files in the same position as in
the source files. This will however stop to
work if the processor directives includes
loops or instructions that returns multiple
lines.



@node Invoking
@chapter Invoking

Syntax for invoking @command{?{GPP}}:
@command{?{GPP} [options...]}

Short options must not be joined and
the value for a flag must be in a
separate argument from the flag itself.

For example, @option{--symbol=X} is not allowed,
but @option{--symbol X} is.

@table @option
@item -s
@itemx --symbol
Set the prefix symbol for preprocessor directives. (Default: @@)

@item -e
@itemx --encoding
Set the encoding of file.

@item -n
@itemx --iterations
Number of iterations to run the preprocessing in. (Default: 1)

@item -u
@itemx --unshebang
Blank out the shebang line. Notice that the line is not removed,
it is just cleared. You can use a shebang line make to gpp
preprocess the file when executed.

If @option{--unshebang} is used twice, the second line in the
file will be moved up to the top of the file and the initial
shebang line will be removed. A blank line will be inserted
after the new top line will be added to keep the line numbers
in the output file as near as possible to the line numbers
in the input file. The intension of this option is that you
can have two shebang lines, one on the first line for preprocessing
when the file is executed, and one shebang line on the second
line for output file.

@item -i
@itemx --input
Set the input file. (Default: /dev/stdin)

@item -o
@itemx --output
Set the output file. (Default: /dev/stdout)

@item -f
@itemx --file
Set both input file and output file.

@item -D
@itemx --export
Declare a environment variable. The syntax
@code{NAME=VALUE} is used for the argument,
but if the argument does not include an
equals sign the value 1 will be used.

@item -v
@itemx --version
Print program name and version and exit.

@item -c
@itemx --copying
Print copyright notice and exit.

@end table



@node Syntax
@chapter Syntax

To create a preprocess directive, begin the
line with @code{@@>}. For example, the follow
code will only keep the `Hello world' line
if the environment variable @var{HELLO} is
defined and is not empty.

@example
@@>[ -z "$HELLO" ] &&
Hello world
@end example

If you want to write a mutliline preprocessor
directive you can begin the first line with
@code{@@<} and begin the last line with
@code{@@>}, instead of having each line start
with @code{@@>}. For example, if you want
to create a preprocess function to make a
ASCII text uppercase you can write:

@example
@@<uppercase () @{
    lower=qwertyuiopasdfghjklzxcvbnm
    upper=QWERTYUIOPASDFGHJKLZXCVBNM
    sed y/$lower/$upper/ <<<"$*"
@@>@}
@end example

Now assume that you have this @command{uppercase}
preprocessor function defined on the top of a
document. Also assume that you are logged in
as the user `twilight' and therefor have the
environment variable @var{USER} set to `twilight'.

If you in the document, below the definition
of @command{uppercase}, insert the line

@example
Your are logged in as @@(uppercase $USER).
@end example

After preprocessing it will say

@example
Your are logged in as TWILIGHT.
@end example

@@(...) can be used inline. It executes a
command that can either be defined as a
preprocessor function or be an external program.
Preprocossor directives cannot be used inside
it, everything in it is in GNU Bash.

@@@{...@} is another inline preprocessor directive,
you can put the name of a preprocessor variable
or environment variable inside it to get the
variable's value. For example, if you are
logged in as `twilight'

@example
Your are logged in as @@@{USER@}.
@end example

@noindent
will after preprocessing say

@example
Your are logged in as twilight.
@end example

@noindent
@command{gpp} supports all modifications to the
result that Bash does. For example, if you want
the value to be uppercased you can write

@example
Your are logged in as @@@{USER^^@}.
@end example



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye