README
1re2c Version 0.12.3
2------------------
3
4Originally written by Peter Bumbulis (peter@csg.uwaterloo.ca)
5
6Currently maintained by:
7 Dan Nuffer <nuffer at users.sourceforge.net>
8 Marcus Boerger <helly at users.sourceforge.net>
9 Hartmut Kaiser <hkaiser at users.sourceforge.net>
10
11The re2c distribution can be found at:
12
13 http://sourceforge.net/projects/re2c/
14
15re2c has been developed and tested with the following compilers on various
16platforms in 32 bit and 64 bit mode:
17- GCC 3.3 ... 4.1
18- Microsoft VC 7, 7.1, 8
19- Intel 9.0
20- Sun C++ 5.8 (CXXFLAGS='-library=stlport4')
21- MIPSpro Compilers: Version 7.4.4m
22
23GCC 2.x and Microsoft VC 6 are not capable of compiling re2c.
24
25Building re2c on unix like platforms requires autoconf 2.57 and bison (tested
26with 1.875 and later). Under windows you don't need autoconf or bison
27and can use the pregenerated files.
28
29You can build this software by simply typing the following commands:
30 ./configure
31 make
32
33The above version will be based on the pregenerated scanner.cc file.
34If you want to build that file yourself (recommended when installing
35re2c) you need the following steps:
36 ./configure
37 make
38 rm -f scanner.cc
39 make install
40
41Or you can create a rpm package and install it by the following commands:
42 ./configure
43 make rpm
44 rpm -Uhv <packagedir>/re2c-0.12.3-1.rpm
45
46If you want to build from CVS then the first thing you should do is
47regenerating all build files using the following command:
48 ./autogen.sh
49and then continue with one of the above described build methods. Or if you
50need to generate RPM packages for cvs builds use these commands:
51 ./autogen.sh
52 ./configure
53 ./makerpm <release>
54 rpm -Uhv <packagedir>/re2c-0.12.3-<release>.rpm
55
56Here <realease> should be a number like 1. And <packagedir> must equal
57the directory where the makerpm step has written the generated rpm to.
58
59If you are on a debian system you can use the tool 'alien' to convert rpms
60to debian packages.
61
62When building with native SUN compilers you need to set the following compiler
63flags: CXXFLAGS='-g -compat5 -library=stlport4'.
64
65If you want to build re2c on a windows system you can either use cygwin and one
66of the methods described above or use Microsoft Visual C .NET 2002 or later
67with the solution files provided (re2c.sln for 2002/2003 and re2c-2005.sln for
68version 2005). re2c cannot be built with Microsoft Visual C 6.0 or earlier.
69
70re2c is a great tool for writing fast and flexible lexers. It has
71served many people well for many years. re2c is on the order of 2-3
72times faster than a flex based scanner, and its input model is much
73more flexible.
74
75For an introduction to re2c refer to the lessons sub directory.
76
77Peter's original version 0.5 ANNOUNCE and README follows.
78
79--
80
81re2c is a tool for generating C-based recognizers from regular
82expressions. re2c-based scanners are efficient: for programming
83languages, given similar specifications, an re2c-based scanner is
84typically almost twice as fast as a flex-based scanner with little or no
85increase in size (possibly a decrease on cisc architectures). Indeed,
86re2c-based scanners are quite competitive with hand-crafted ones.
87
88Unlike flex, re2c does not generate complete scanners: the user must
89supply some interface code. While this code is not bulky (about 50-100
90lines for a flex-like scanner; see the man page and examples in the
91distribution) careful coding is required for efficiency (and
92correctness). One advantage of this arrangement is that the generated
93code is not tied to any particular input model. For example, re2c
94generated code can be used to scan data from a null-byte terminated
95buffer as illustrated below.
96
97Given the following source
98
99 #define NULL ((char*) 0)
100 char *scan(char *p)
101 {
102 #define YYCTYPE char
103 #define YYCURSOR p
104 #define YYLIMIT p
105 #define YYFILL(n)
106 /*!re2c
107 [0-9]+ {return YYCURSOR;}
108 [\000-\377] {return NULL;}
109 */
110 }
111
112re2c will generate
113
114 /* Generated by re2c on Sat Apr 16 11:40:58 1994 */
115 #line 1 "simple.re"
116 #define NULL ((char*) 0)
117 char *scan(char *p)
118 {
119 #define YYCTYPE char
120 #define YYCURSOR p
121 #define YYLIMIT p
122 #define YYFILL(n)
123 {
124 YYCTYPE yych;
125 unsigned int yyaccept;
126
127 if((YYLIMIT - YYCURSOR) < 2) YYFILL(2);
128 yych = *YYCURSOR;
129 if(yych <= '/') goto yy4;
130 if(yych >= ':') goto yy4;
131 yy2: yych = *++YYCURSOR;
132 goto yy7;
133 yy3:
134 #line 9
135 {return YYCURSOR;}
136 yy4: yych = *++YYCURSOR;
137 yy5:
138 #line 10
139 {return NULL;}
140 yy6: ++YYCURSOR;
141 if(YYLIMIT == YYCURSOR) YYFILL(1);
142 yych = *YYCURSOR;
143 yy7: if(yych <= '/') goto yy3;
144 if(yych <= '9') goto yy6;
145 goto yy3;
146 }
147 #line 11
148
149 }
150
151Note that most compilers will perform dead-code elimination to remove
152all YYCURSOR, YYLIMIT comparisions.
153
154re2c was developed for a particular project (constructing a fast REXX
155scanner of all things!) and so while it has some rough edges, it should
156be quite usable. More information about re2c can be found in the
157(admittedly skimpy) man page; the algorithms and heuristics used are
158described in an upcoming LOPLAS article (included in the distribution).
159Probably the best way to find out more about re2c is to try the supplied
160examples. re2c is written in C++, and is currently being developed
161under Linux using gcc 2.5.8.
162
163Peter
164
165--
166
167re2c is distributed with no warranty whatever. The code is certain to
168contain errors. Neither the author nor any contributor takes
169responsibility for any consequences of its use.
170
171re2c is in the public domain. The data structures and algorithms used
172in re2c are all either taken from documents available to the general
173public or are inventions of the author. Programs generated by re2c may
174be distributed freely. re2c itself may be distributed freely, in source
175or binary, unchanged or modified. Distributors may charge whatever fees
176they can obtain for re2c.
177
178If you do make use of re2c, or incorporate it into a larger project an
179acknowledgement somewhere (documentation, research report, etc.) would
180be appreciated.
181
182Please send bug reports and feedback (including suggestions for
183improving the distribution) to
184
185 peter@csg.uwaterloo.ca
186
187Include a small example and the banner from parser.y with bug reports.
188
189