diff options
Diffstat (limited to 'gpp.1')
| -rw-r--r-- | gpp.1 | 197 |
1 files changed, 197 insertions, 0 deletions
@@ -0,0 +1,197 @@ +.TH GPP 1 gpp +.SH NAME +gpp - Bash-based preprocessor for anything + +.SH SYNOPSIS +.R gpp +.RI [ OPTION ]... + +.SH ETYMOLOGY +gpp stands for General Preprocessor. + +.SH DESCRIPTION +.B gpp +lets a developer embed directives written in +.B GNU Bash +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) +supports. For example, if you want the value to be +included but uppercase you can write +.BR @{ \fIVARIABLE\fP ^^} , +or +.BI @{ VARIABLE ,,} +for lowercase. +.PP +Everything that is not a preprocessing directive is +echo verbatim. + +.SH OPTIONS +.TP +.BR \-s ,\ \-\-symbol \ \fISYMBOL\fP +Set the prefix symbol for preprocessor directives. +Defaults to @ (at). +.TP +.BR \-e ,\ \-\-encoding \ \fIENCODING\fP +Specifies the encoding of the file. +.TP +.BR \-n ,\ \-\-iterations \ \fIN\fP +Process the file recursively \fIN\fP times. Defaults to 1 time. +.TP +.BR \-u ,\ \-\-unshebang +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. +.TP +.BR \-i ,\ \-\-input \ \fIFILE\fP +Select file to process. Defaults to /dev/stdin. +.TP +.BR \-o ,\ \-\-output \ \fIFILE\fP +Select output file. Defaults to /dev/stdout. +.TP +.BR \-f ,\ \-\-file \ \fIFILE\fP +Equivalent to \-i \fIFILE\fP \-o \fIFILE\fP. +.TP +.BR \-D ,\ \-\-export \ \fINAME\fP=\fIVALUE\fP +Set the environment variable \fINAME\fP to hold +the value \fIVALUE\fP. +.TP +.BR \-D ,\ \-\-export \ \fINAME\fP +Set the environment variable \fINAME\fP to hold +the value 1. +.TP +.BR \-v ,\ \-\-version +Print program name and version and exit. +.TP +.BR \-c ,\ \-\-copying +Print copyright notice and exit. +.PP +Short options must be joined. The value of a flag must +be in a separate argument from the flag itself. + +.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 + +.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 "SEE ALSO" +.BR bash (1), +.BR jpp (1), +.BR cpp (1), +.BR env (1) |