raze/tools/re2c

re2c
--------------------------------------------------------------------------------


DESCRIPTION
--------------------------------------------------------------------------------
re2c is a tool for generating C-based recognizers from regular expressions.
re2c-based scanners are efficient: for programming languages, given similar
specifications, a re2c-based scanner is typically almost twice as fast as a
flex-based scanner with little or no increase in size (possibly a decrease
on cisc architectures). Indeed, re2c-based scanners are quite competitive with
hand-crafted ones.

Unlike flex, re2c does not generate complete scanners: the user must supply some
interface code.  While this code is not bulky (about 50-100 lines for a
flex-like scanner; see the man page and examples in the distribution) careful
coding is required for efficiency (and correctness). One advantage of this
arrangement is that the generated code is not tied to any particular input
model.
--------------------------------------------------------------------------------


DOWNLOAD
--------------------------------------------------------------------------------
The re2c distribution can be found at:
    https://sourceforge.net/projects/re2c/

Download the latest tarball:
    https://sourceforge.net/projects/re2c/files/latest/download

Clone git repo:
    git clone git://git.code.sf.net/p/re2c/code-git
--------------------------------------------------------------------------------


BUILD
--------------------------------------------------------------------------------
Contents:
    1. simple build
    2. bootstrap
    3. out-of-source build
    4. testing
    5. rebuild documentation
    6. build for windows with mingw
    7. build from git

1. Simplest possible build:
    $ ./configure [--prefix=<prefix>]
    $ make
    $ make install
This will build re2c and install it (binary and man page) to <prefix> (defaults
to /usr/local).

2. Bootstrap and rebuild:
    $ ./configure [--prefix=<prefix>]
    $ make bootstrap
    $ make install
Usual bootstrap procedure: re2c uses re2c to compile its lexer.
1. build lexer (if make finds re2c binary in build directory, it will build lexer
   from source, otherwize it will use prebuilt lexer)
2. build re2c
3. build lexer from source using re2c binary in build directory
4. rebuild re2c

3. Out-of-source build:
    $ mkdir <build-directory>
    $ cd <build-directory>
    $ <path-to-configure>/configure [--prefix=<prefix>]
    $ make
    $ make install

4. Testing:
    $ make check
This will redirect test script output to file. If you want to see progress:
    $ make tests
Testing under valgrind (takes a long time):
    $ make vtests

5. Rebuild documentation (requires rst2man.py):
    $ ./configure --enable-docs [--prefix=<prefix>]
    $ make docs
    $ make install

6. Build for windows using mingw:
    $ ../configure --host i686-w64-mingw32  [--prefix=<prefix>]
    $ make
This will result into an executable re2c.exe, which can be tested with wine:
    $ make wtests

7. If you want to build from git, you'll first need to generate autotools files:
    $ ./autogen.sh
--------------------------------------------------------------------------------


INFO
--------------------------------------------------------------------------------
    $ man re2c

re2c home page:
    re2c.org

re2c manual:
    re2c.org/manual.html

Ulya Trofimovich's blog on re2c:
    skvadrik.github.io/aleph_null/re2c.html

Original paper on re2c: "RE2C: a More Versatile Parser Generator" (1994, Peter
Bumbulis and Donald D. Cowan).

Examples can be found in 'examples' directory.
--------------------------------------------------------------------------------


MAILING LISTS
--------------------------------------------------------------------------------
re2c-general:
    re2c-general@lists.sourceforge.net
re2c-devel:
    re2c-devel@lists.sourceforge.net

You are welcome to ask for help or share your thoughts and ideas about re2c :)
--------------------------------------------------------------------------------


BUGS
--------------------------------------------------------------------------------
Please report any bugs and send feature requests to:
    https://sourceforge.net/p/re2c/_list/tickets
--------------------------------------------------------------------------------


AUTHORS
--------------------------------------------------------------------------------
Originally written by Peter Bumbulis (peter@csg.uwaterloo.ca)
Currently maintained by:
    Ulya Trofimovich <skvadrik@gmail.com>
    Dan Nuffer <nuffer@users.sourceforge.net>
    Marcus Boerger <helly@users.sourceforge.net>
    Hartmut Kaiser <hkaiser@users.sourceforge.net>
--------------------------------------------------------------------------------


LICENSE
--------------------------------------------------------------------------------
re2c is distributed with no warranty whatever. The code is certain to contain
errors. Neither the author nor any contributor takes responsibility for any
consequences of its use.

re2c is in the public domain. The data structures and algorithms used in re2c
are all either taken from documents available to the general public or are
inventions of the authors. Programs generated by re2c may be distributed freely.
re2c itself may be distributed freely, in source or binary, unchanged or
modified. Distributors may charge whatever fees they can obtain for re2c.

If you do make use of re2c, or incorporate it into a larger project an
acknowledgement somewhere (documentation, research report, etc.) would be
appreciated.
--------------------------------------------------------------------------------