diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/tango-weevil/weevinfo.tw |
Initial commit
Diffstat (limited to 'web/tango-weevil/weevinfo.tw')
-rw-r--r-- | web/tango-weevil/weevinfo.tw | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/web/tango-weevil/weevinfo.tw b/web/tango-weevil/weevinfo.tw new file mode 100644 index 0000000000..7f800b4a95 --- /dev/null +++ b/web/tango-weevil/weevinfo.tw @@ -0,0 +1,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 |