cxxparse Files

Introduction
============
Right now, cxxparse is little more than a flex wrapper (flexx) plus some bison
skeleton files (v3c_bison.m4, *.m4).
Right now I'm switching from nasm to GNU as via gcc.
Eventually bisonx will be able to generate a regular source file for
compilation as the C preprocessor isn't as clever as nasm or GNU is!

Ultimately cxxparse will provide an alternative to bison, but that's for later.
Not because it's a fun thing to do, but because of the limitations inherent in
existing GLR parser generators.
No, I don't expect it will be any faster, just that it will be able to parse
c++. Otherwise having a BNF specification of the c++ language is a bit
pointless.

What you get now is a cornerstone of the finished product - lexers and parsers
that are battle-ready for large scale tasks like a compiler.

To make the transition clearer I've included the calc++ example, along with it's
cxxparse version under flexx/tests.

How it does it
--------------
In a nutshell, the location information and the semantic value are part of the
same object (think debugging information), and these objects are handled through
smart pointers.

cxxparse eliminates the need for...
 1. Unions
 2. Printer functions
 3. destructors
 4. #define clashes that are waiting to happen with existing bison generated
    code.
...and provides
 1. A token base class generated by the grammar to be inherited by the scanner
 2. The ability to have multiple parsers and scanners in the same program.

Directory layout
================
cxxparse (you are here)
 |-build (everything created goes here, as far as the tools will allow)
 |  \-v3c
 |     |-calc++     The bison c++ example (generated code)
 |     |-flexx      A flex wrapper (generated code)
 |     |  \-tests   The bison c++ example, flexxed (generated code)
 |     \-parse      bisonx (generated code)
 |        \-tests   The bison c++ example, flexxed and bisonxed (generated code)
 \-v3c (the source)
    |-calc++     The bison c++ example
    |-flexx      A flex wrapper
    |  \-tests   The bison c++ example, flexxed.
    \-parse      bisonx
       \-tests   The bison c++ example, flexxed and bisonxed

I'm using v3c as the name of the source directory as this is a v3c sub-project,
and the source files include header files through <v3c/...>, so adding the
root directory to the system include path (-isystem) solves that rather neatly.

As a sub-project it can have it's own release schedule and only needs to keep
in step with v3c when it requires some feature of the latest version - not very
often. Otherwise it can grow at it's own pace.

Requirements
============
This is a sub-project of v3c so you'll need that.
cxxparse needs bison and flex.

Debian/Ubuntu packages
======================
If you run
    make debian
the build system will compile and test v3c/cxxparse before creating a .tar.gz
tar ball.
This tar ball is then used by the build system to build the debian packages
    cxxparse*-1_amd64.deb
    cxxparse-dev_*-1_amd64.deb
    cxxparse-doc_*-1_all.deb
You will need a gpg public/private key pair to sign these packages - more info
can be found in the "maint-guide" debian package.

doxygen
=======
To build the documentation you'll need v3c.
I've cobbled together a doxygen "documentation chain" so that other projects can
layer their doxygen documentation on top easily.

Then to install the documentation
    make <flags> doxygen-doc && sudo make install-doxygen-doc

v3c
===
v3c provides basic build/compile/runtime functionality used by cxxparse.
Once v3c is installed, cxxparse can use the v3c "build boilerplate" as follows

Symbolic links:
doxygen.am -> /usr/include/v3c/doxygen.am

/usr/include/v3c/v3c.mak and /usr/include/v3c/v3c_mak.sh are used through their
"make" path - v3c/v3c.mak. Why can't regular paths work that way?

I tried to find a way to avoid symbolic links - automake etc. didn't like it.

At least this way, updates to the v3c build system get incorporated
automatically.

Feedback
========
All feedback should be through this projects support web page
    http://sourceforge.net/projects/cxxparse/support.
I've added a help, open discussion and a mantis bug tracker there.

Finally, do send me an email to let me know what your thoughts are on
cxxparse!