RPA Toolkit
Work on documentation.
[rpatk.git] / rex / doc / rexcc.txt
1 /** \page rexcc REX C code generator.
2 rexcc is a code generator for C language. It generates C code from regular expressions and 
3 initializes Deterministic Finite Automata(DFA) rexdfa_t object. The rexcc program reads
4 user specified input file, for a description of the code to generate. It will produce a
5 C file or it will output the generated code to the standard output.
6
7 <h2>Input file format</h2>
8 The rexcc input file consists of three sections, separated by a line containing only `%%'.
9
10 @verbatim
11 C code prolog
12 %%
13 regular expressions
14 %%
15 C code epilog
16 @endverbatim
17
18
19 <h3>C code prolog</h3>
20 This section is used to include any header files or definitions that are required by the rest of the C code.
21
22 <h3>regular expressions</h3>
23 This section is used to specify the regular expressions that will be used to generate and initialize the
24 Deterministic Finite Automata (DFA). This section contain series of regular expression definitions of the form:
25
26 @verbatim
27 userdata        regex
28 @endverbatim
29
30 where userdata must be a user defined data of type @ref rexuserdata_t and regex must be a regular expression. 
31 Both must be separated by space or tab.
32
33 <h3>C code epilog</h3>
34 This section is used to add any C code that uses the @ref rexdfa_t object generated from the rules specified in
35 the previous section. The name of the generated variable of type @ref rexdfa_t is always `ccdfa' and it is declared
36 as static. If you need to access it outside of the generated file you should add code in this section that will
37 make such access possible. For example:
38
39 @verbatim
40 rexdfa_t *mydfa = &ccdfa;
41 @endverbatim
42
43 Or using accessor function:
44 @verbatim
45 rexdfa_t *GetMyDfaPtr()
46 {
47         return &ccdfa;
48
49 @endverbatim
50
51 <h2>Example</h2>
52
53 @code
54 #include "mydefinitions.h"
55 #define IDENTIFIER 257
56
57 %%
58 IDENTIFIER      [A-Za-z_][A-Za-z_0-9]*
59 "keyword"       while|do
60 256             [ \n\r\t]
61 %%
62
63 /* All userdata used in the previous section, can be cast to rexuserdata_t. */
64
65 rexdfa_t *get_simple_dfa()
66 {
67         return &ccdfa;
68 }
69
70 @endcode
71
72 The userdata specified for eache regular expression is used to identify that regular expression when the
73 automata arrives at an accepting state. 
74
75 @section build_rexcc_code Building the generated code
76 The code generated with rexcc doesn't require to be linked with the REX library, but it includes the header file @ref rexdfa.h. 
77 This file provides the definitions of the DFA related structures used by the generated code and it also provides macros for
78 accessing the states and substates of the DFA. You must add the path to the @ref rexdfa.h header file to your default search path.
79
80 List of macros:
81         - @ref REX_DFA_NEXT - Get the next state in the DFA for the specified input.
82         - @ref REX_DFA_STATE - Get a pointer to @ref rexdfa_t state.
83         - @ref REX_DFA_TRANSITION - Get a pointer to @ref rexdft_t transition.
84         - @ref REX_DFA_SUBSTATE - Get a pointer to @ref rexdfss_t substate. This works only if rexcc is instructed to generate the substates.
85         - @ref REX_DFA_ACCSUBSTATE - Get a pointer to @ref rexdfss_t accepting substate.
86          
87
88
89 <h2>Example</h2>
90         - @ref tokenjs.rexcc - JavaScript tokenizer.
91
92 @section rexcc_command_line rexcc parameters
93 @verbatim
94 # rexcc [OPTIONS] <filename>
95  OPTIONS:
96         -o <cfile>               Output .c file.
97         -d                       Dump regular expressions.
98         -D                       Dump DFA states.
99         -N                       Dump NFA states.
100         -s                       Include substates.
101         -t                       Display statistics.
102         -v                       Display version information.
103         -h, --help               Display this help.
104 @endverbatim
105
106 @example tokenjs.rexcc
107
108
109
110  
111 */