1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
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)
|
