-
Notifications
You must be signed in to change notification settings - Fork 0
/
nanabozo.1
250 lines (247 loc) · 6.59 KB
/
nanabozo.1
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
245
246
247
248
249
.TH NANABOZO 1 2020-03-26 "version 0.1-alpha" "User Commands"
.SH NAME
nanabozo \- tool for CHTML script\-coding
.SH SYNOPSIS
\f[B]nanabozo\f[] [\f[I]OPTIONS\f[]...] [(\f[I]inputfile\f[]|\-) [(\f[I]outputfile\f[]|\-)]]
.SH DESCRIPTION
\f[B]nanabozo\f[] is a command\-line application that translates \f[I]CHTML
scripts\f[] into pure C code. In other terms, it lets you mix HTML (or
equivalent) with C/C++, like you would with PHP.
.SH OPTIONS
.TP
\f[B]\-m\f[], \f[B]\-\-main\f[]
Turn input into the body of an implicit main function.
.TP
\f[B]-t\f[], \f[B]\-\-html\f[]
Print content-type header (text/html, charset utf-8).
.TP
\f[B]-n\f[], \f[B]\-\-no\-comments\f[]
Omit all begin/end comments in output.
.TP
\f[B]\-c\f[] \f[I]<comment>\f[], \f[B]\-\-comment\f[]=\f[I]<comment>\f[]
Override top comment (generated by).
Pass an empty string to omit comment header.
.TP
\f[B]\-a\f[] \f[I]<prefix>\f[], \f[B]\-\-prepend\f[]=\f[I]<prefix>\f[]
String (prefix) to prepend.
Useful to pass some extra code at the beginning, eg: (bash):
\-a "$(cat myfile.h myfile.c)"
.TP
\f[B]\-z\f[] \f[I]<suffix>\f[], \f[B]\-\-append\f[]=\f[I]<suffix>\f[]
String (suffix) to append.
Useful to pass some extra code at the end, eg. (bash):
\-z $'return 0;\\n}'
.TP
\f[B]\-p\f[] \f[I]<func>\f[], \f[B]\-\-print\f[]=\f[I]<func>\f[]
Override the name of function 'print(x)'.
By default, 'print(x)' is a macro for 'fputs(x, stdout)'.
.TP
\f[B]\-f\f[] \f[I]<func>\f[], \f[B]\-\-printf\f[]=\f[I]<func>\f[]
Override the name of function 'printf(x, ...)'.
.TP
\f[B]\-v\f[], \f[B]\-\-version\f[]
Print version information and exit.
.TP
\f[B]\-h\f[], \f[B]\-\-help\f[]
Print usage information and exit.
.SH ARGUMENTS
.TP
.B inputfile
Input file ('\-' for stdin, default). Also known as "the script".
.TP
.B outputfile
Output file ('\-' for stdout, default). Should somehow be compilable.
.SH USAGE
.PP
Here is a simple CGI example:
.IP
.nf
<?
#define PAGE_TITLE "Hello World Example"
int main(void) {
char *world = "World";
/* Headers */
print("Content\-Type: text/html; charset=utf\-8\\n\\n");
?>
<html>
<head>
<title><?= PAGE_TITLE ?></title>
</head>
<body>
<h1><?% "Hello %s!", world ?></h1>
</body>
</html>
<?
return 0;
} // end main()
?>
.fi
.PP
Let's put that snippet in a file called helloworld.php (why not),
then execute nanabozo like this:
.IP
.nf
nanabozo helloworld.php helloworld.c
.fi
.PP
Now let's examine what hellowrld.c looks like.
.IP
.nf
/*
* Generated by nanabozo (do not edit)
* Sun Jan 14 11:08:12 CET 2018
*/
.fi
.PP
That is an informational, self\-explanatory comment.
You can disable that comment header with \f[I]the option \-c\f[], passing it
an empty string (\-c ""), or have your own comment instead if you want
(\-c "$(cat license.txt)").
.IP
.nf
#include <stdio.h>
#define print(x) fputs(x, stdout)
.fi
.PP
By default, stdio.h is included, and the function print defined.
As you can see, stdout is the file we are sending our text to, just like
another CGI application.
.IP
.nf
/* BEGIN C (line 1) */
#define PAGE_TITLE "Hello World Example"
int main(void) {
char *world = "World";
/* Headers */
print("Content\-Type: text/html; charset utf\-8\\n\\n");
/* END C (line 8) */
.fi
.PP
Enclosed by begin/end comments, the first part of our C code is given here,
as it was in the first file.
You can omit those comments with \f[I]the option \-n\f[] if you want, but they are
useful for debugging purposes.
.PP
Nothing special here, our CGI needs a main() function.
Note that the function print is used to send the usual mandatory headers.
.IP
.nf
print("<html>\\n"
"<head>\\n"
"<title>");
.fi
.PP
Our HTML script begins. The function print is used to pass it to stdout.
.IP
.nf
/* BEGIN C= (line 11) */
print( PAGE_TITLE );
/* END C= (line 11) */
.fi
.PP
The C code that was in between the tags <?= and ?> is given as argument to
the function print.
.PP
Another HTML part follows:
.IP
.nf
print("</title>\\n"
"</head>\\n"
"<body>\\n"
"<h1>");
.fi
.PP
Then, what was in between the tags <?% and ?> is passed as arguments to
the function printf:
.IP
.nf
/* BEGIN C% (line 14) */
print( "Hello %s!", world );
/* END C% (line 14) */
.fi
.PP
Finally, the rest of the HTML and the end of the main() function:
.IP
.nf
print("</h1>\\n"
"</body>\\n"
"</html>\\n");
/* BEGIN C (line 17) */
return 0;
} // end main()
/* END C (line 20) */
.fi
.PP
You can compile helloworld.c and your CGI application is ready.
In a hurry, you can try something like:
.IP
.nf
nanabozo helloworld.php | gcc \-x c \-o helloworld.cgi \-
.fi
.SS More options
.PP
nanabozo has options to accomodate for different workflows.
.PP
\f[I]The option \-m\f[] can be used to include a basic, main function
definition wrapping around your script.
.PP
\f[I]The option \-t\f[] can be used to send a basic Content\-Type header
(text/html, charset UTF\-8) before any other output.
.PP
\f[I]The option \-a\f[] can be used to pass a string to prepend to the
content of the script.
.PP
\f[I]The option \-z\f[] can be used to pass a string to append to the
content of the script.
.PP
Our simple example could be rewritten without the definition of the
main() function. In bash, you could:
.IP
.nf
nanabozo \-a $'int main(void) {\\n' \-z $'\\n\\treturn 0;\\n}' helloworld.php helloworld.c
# note that is equivalent to:
nanabozo \-\-main helloworld.php helloworld.c
.fi
.PP
You could however make things even worse:
.IP
.nf
< helloworld.php nanabozo \-a "$(cat myfile .h myfile.c)" > helloworld.c
.fi
.PP
\f[I]The option \-p\f[] can be used to pass an alternative function name to
replace the print function.
.PP
\f[I]The option \-f\f[] can be used to pass an alternative function name to
replace the printf function.
.PP
And if you replace both print and printf, stdio.h will not be included.
A command such as:
.IP
.nf
nanabozo \-p print \-f printf helloworld.php helloworld.c
.fi
.PP
will not have stdio.h included, nor print defined. You have to take care of
them on your side.
.PP
\f[I]The option \-v\f[] prints version information and exits.
.PP
\f[I]The option \-h\f[] prints usage information and exits.
.SH LIMITATIONS
If your script file has lines longer than 512 characters (the humanly
acceptable), you can recompile with INPUTSIZE defined with a higher value.
.SH BUGS
See GitHub issues: <https://github.com/astrorigin/nanabozo/issues>
.SH LICENSE
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.PP
See the GNU General Public License for more details.
.SH AUTHOR
Written by Stanislas Marquis <[email protected]>
.SH SEE ALSO
fputs(3), printf(3)