summaryrefslogtreecommitdiff
path: root/web/tango-weevil/weevinfo.tw
blob: 7f800b4a9509a74d05b439cd755e0d7503af142b (plain)
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
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
%
%   Tango/Weevil - A WEB Tangler and Weaver
%    Copyright (C) 1995 Corey Minyard
%
%    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 2 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program; if not, write to the Free Software
%    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%
%    Corey Minyard - minyard@metronet.com
%
\section{Weevil Information Include Introduction}

This file contains the information used by weevil and the language and
output handlers that interface to weevil.

@code <*>
#ifdef __cplusplus__
extern "C"
{
#endif

@<Defines>
@<Structures>
@<C Language Routines>
@<LaTeX Routines>

#ifdef __cplusplus__
}
#endif
@endcode

\section{Interfacing Languages to Weevil}

A language definition requires two simple procedure calls.  A
character handler handles all code a character at a time.  It's job is
to tell weevil how to handle the character.  It is passed the standard
weevil data, a character, and the next character in the sequence.  It
returns the following codes:

\begin{description}
\item[PROCESS\_CHAR\_NORMALLY] This is a standard character that
should be handled normally by weevil.
\item[PROCESS\_CHAR\_INSTRING] This character is in a string or
comment, it should not be scanned for special weevil characters.
\item[PROCESS\_CHAR\_SKIPNEXT] This character and the following
character should be skipped without being scanned for special weevil
characters.
\end{description}

The other procedure is an initialization handler, which may initialize
the language handler.

\section{Interfacing Output Types to Weevil}

An output type requires a lot of function calls but is conceptually
simple.  Each function call output a certain portion of the output,
just provide the proper output mechanism, add all the functions to the
list of output modes, and it's done.  Section~\ref{weevinfo-defines}
has the typedefs and descriptions for all the functions.

\begin{sloppypar}
Weevil has a number of output modes.  Documentation modes is the mode
weevil starts in, it will just output everything as-is until it finds
a code chunk (marked by \verb|@code|).  Then it switches to code mode
after calling \verb|begin_macro_handler|.  Code mode calls the
language character handler on each character to find out if it is in a
string, comment, etc.  It will output characters normally until it
sees an \verb|@| (unless in a string or comment).  If it sees an
\verb|@@|, it will output a single \verb|@|.  If it sees a
\verb|@<name>|, it will call \verb|output_macro_use_handler| with the
name.  It will \emph{not} output the \verb|@<name>|.  At the end of
the code chunk, \verb|end_macro_handler| will be called.  At the
beginning of each line, \verb|output_linenum_handler| will be called.
\end{sloppypar}

After a code chunk has been output, if cross references for any
variable uses exist for the code chunk then uses mode will be entered,
where each variable used by the code chunk will be output.  A begin
handler is called, then for each cross reference the name handle is
called and a handler is called for each place where the name is
declared is given.  Then an end name handler is called.  After all
uses have been output, an end handler is called.

If declaration cross references exist, they are output next.  A begin
handler is called, then a handler for each variable name, then an end
handler for the declaration list.

If any cross references were output, a handler is called after all
cross references have been output.  Then documentation mode is entered
again.

\section{Defines}
\label{weevinfo-defines}
The following code chunk has miscellaneous definitions and the
typedefs for all the language-specific and output-specific procedures
used by weevil.  Each procedure is also described in detail in the
comment before it.

@code <Defines>
#define MAXLINESIZE 200

#define TRUE    1
#define FALSE   0
typedef int bool;


/* Is the processor processing stuff between @code and @endcode or
   is is processing documentation?  Used by the codestate
   variable. */
#define IN_CODE         1
#define NOT_IN_CODE     2


#define PROCESS_CHAR_NORMALLY   0
#define PROCESS_CHAR_INSTRING   1
#define PROCESS_CHAR_SKIPNEXT   2

struct s_lpweevildat;

/****************************************************************
**
** These are for languages.
**
****************************************************************/

/*
 * Process the code a character at a time.  The current and next
 * character are provided.  Return PROCESS_CHAR_NORMALLY for
 * standard output, PROCESS_CHAR_INSTRING if in a string or
 * comment, or PROCESS_CHAR_SKIPNEXT if the current and next
 * character should not be processed (just output).
 */
typedef int (*char_handler)(struct s_lpweevildat *lpwd,
                            char                 c,
                            char                 next_c);

/*
 * Initialize the language handler.  This may use the
 * language-specific pointer in lpwd to store info for
 * itself.
 */
typedef void (*handler_init)(struct s_lpweevildat *lpwd);


/****************************************************************
**
** These are for documentation output.
**
****************************************************************/

/*
 * Initialize the mode handler.  This may use the mode-specific
 * pointer in lpwd to store info for itself.
 */
typedef void (*mode_init)(struct s_lpweevildat *lpwd);

/*
 * Handle the beginning of a code chunk.  The name of the code
 * chunk is passed in.
 */
typedef void (*begin_macro_handler)(struct s_lpweevildat *lpwd,
                                    char          *name);

/*
 * Handle the end of a code chunk.
 */
typedef void (*end_macro_handler)(struct s_lpweevildat *lpwd);

/*
 * Handle the end after all cross references and everything.
 */
typedef void (*finalend_chunk_handler)(struct s_lpweevildat *lpwd);

/*
 * Output the use of a code chunk in some code.  The name of
 * the code chunk is given.
 */
typedef void
(*output_macro_use_handler)(struct s_lpweevildat *lpwd,
                            char          *macro_name);

/*
 * Output the line number at the beginning of the code chunk.
 */
typedef void
(*output_linenum_handler)(struct s_lpweevildat *lpwd);

/*
 * Output a single normal character.
 */
typedef void
(*output_char_handler)(struct s_lpweevildat *lpwd,
                       char                 c);

/*
 * Handle the beginning of a list of uses cross-references.
 */
typedef void
(*output_begin_uses_handler)(struct s_lpweevildat *lpwd);

/*
 * Handle the end of a list of uses cross-references.
 */
typedef void
(*output_end_uses_handler)(struct s_lpweevildat *lpwd);

/*
 * Handle the start of a single use cross reference.  The name of
 * the variable is given.
 */
typedef void
(*output_use_start_handler)(struct s_lpweevildat *lpwd,
                            char                 *name);

/*
 * Handle the end of a single use cross reference.  The name of
 * the variable is given.
 */
typedef void
(*output_use_end_handler)(struct s_lpweevildat *lpwd,
                          char                 *name);

/*
 * Output a use cross reference location.  The file and macro
 * of the declaration is given.  The name being cross-referenced
 * is also given.
 */
typedef void
(*output_use_ref_handler)(struct s_lpweevildat *lpwd,
                          char                 *file,
                          char                 *macro,
                          char                 *name);

/*
 * Handle between each use of a cross reference.
 */
typedef void
(*output_between_use_refs_handler)(struct s_lpweevildat *lpwd,
                                   char                 *name);

/*
 * Handle the beginning of a list of declares cross-references.
 */
typedef void
(*output_begin_decls_handler)(struct s_lpweevildat *lpwd);

/*
 * Handle the end of a list of declares cross-references.
 */
typedef void
(*output_end_decls_handler)(struct s_lpweevildat *lpwd);

/*
 * Handle the output of a single declaration.
 */
typedef void
(*output_decl_handler)(struct s_lpweevildat *lpwd,
                       char                 *name);

/*
 * Handle the end of cross references.  This is only called if
 * cross-references were created.
 */
typedef void
(*output_after_xrefs_handler)(struct s_lpweevildat *lpwd);
@endcode

\section{Structures}
Various structures used by weevil are put here.

@code <Structures>
@<xreflist>
@<lpweevildat>
@endcode

\subsection{xreflist}
This list contains list of cross references and information on where
they are declared.

@code <xreflist>
typedef struct s_xreflist
{
   struct s_xreflist *next;
   char *file;
   char *macro;
   char *name;
} xreflist;
@endcode

\subsection{lpweevildat}
This large structure contains everything there is to know about what
weevil is doing.

@code <lpweevildat>
typedef struct s_lpweevildat
{
   FILE *infile;                /* File to get input from. */
   FILE *outfile;               /* File to send output. */
   char line[MAXLINESIZE];      /* Current input line. */

   int codestate;               /* Current output state. */
   char *curr_filename;         /* Name of the input file being
                                   processed. */
   char *curr_macro;            /* Current macro being input. */
   int maxlinesize;             /* Maximum size of an input line. */
   int curr_lineno;             /* Current input line number. */
   int code_lineno;             /* Current code output line number. */

   int retcode;                 /* Program return code. */

   void *lang_data;             /* Data for language mode. */
   void *mode_data;             /* Data for output mode. */

   xreflist *pounddefs;         /* List of #defines. */
   xreflist *vardefs;           /* List of variable defines. */
   xreflist *uses;              /* List of variable uses. */

   xreflist *includes;		/* List of places to look for
				   .xfr files. */

   /* Routine to scan code in a language-specific way. */
   char_handler handle_char;

   /* Routines to output data for the output mode. */
   begin_macro_handler begin_macro;
   end_macro_handler end_macro;
   finalend_chunk_handler finalend_chunk;
   output_macro_use_handler output_macro_use;
   output_linenum_handler output_linenum;
   output_char_handler output_char;
   output_begin_uses_handler output_begin_uses;
   output_end_uses_handler output_end_uses;
   output_use_start_handler output_use_start;
   output_use_end_handler output_use_end;
   output_use_ref_handler output_use_ref;
   output_between_use_refs_handler output_between_use_refs;
   output_begin_decls_handler output_begin_decls;
   output_end_decls_handler output_end_decls;
   output_decl_handler output_decl;
   output_after_xrefs_handler output_after_xrefs;
} t_lpweevildat;
@endcode

\section{Language Dependent Routines}
Here are forward-declared all the routines for the various languages
handled by weevil.

\subsection{C}

@code <C Language Routines>
int c_handle_char(t_lpweevildat *lpwd,
                  char         c,
                  char         next_c);

void init_c_lang(t_lpweevildat *lpwd);
@endcode

\section{Output Mode Routines}
Here are forward-declared all the routines for the various output modes
handled by weevil.

\subsection{\LaTeX}

@code <LaTeX Routines>
void latex_mode_init(t_lpweevildat *lpwd);

void latex_begin_macro(t_lpweevildat *lpwd,
                       char          *name);

void latex_end_macro(t_lpweevildat *lpwd);

void latex_finalend_chunk(t_lpweevildat *lpwd);

void latex_output_macro_use(t_lpweevildat *lpwd,
                            char          *macro_name);

void latex_output_linenum(t_lpweevildat *lpwd);

void latex_output_char(t_lpweevildat *lpwd,
                       char          c);

void latex_output_begin_uses(t_lpweevildat *lpwd);

void latex_output_end_uses(t_lpweevildat *lpwd);

void latex_output_use_start(t_lpweevildat *lpwd,
                            char          *name);

void latex_output_use_end(t_lpweevildat *lpwd,
                          char          *name);

void latex_output_use_ref(t_lpweevildat *lpwd,
                          char          *file,
                          char          *macro,
                          char          *name);

void latex_output_between_use_refs(t_lpweevildat *lpwd,
                                   char          *name);

void latex_output_begin_decls(t_lpweevildat *lpwd);

void latex_output_end_decls(t_lpweevildat *lpwd);

void latex_output_decl(t_lpweevildat *lpwd,
                       char          *name);

void latex_output_after_xrefs(t_lpweevildat *lpwd);
@endcode