aboutsummaryrefslogtreecommitdiffstats
path: root/info/gpp.texinfo
blob: e39156bf252b9b027ec7180c4e90767fe0018c82 (plain) (blame)
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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
\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 formated, 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. (Default: UTF-8)

@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 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

will after preprocessing say

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



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

@bye