fructose_gen.py
===============

Quick Start
-----------

`fructose_gen.py` is a Python script for auto-generatng the `main()` function
for the C++ testing framework [Fructose][1].

Sample usage:

    $ python fructose_gen.py [options] test1.h test2.h ... testN.h > main.cpp

In this example, `fructose_gen.py` will read the Fructose test files `test1.h`
through `testN.h` and produce on standard output C++ code with a generated
`main()` function. This auto-generated code will instantiate all the test
instances, register the appropriate tests with each instance, and then execute
each test in turn.

To see usage information and a list of options:

    $ python fructose_gen.py --help


Code Generation Styles
----------------------

`fructose_gen.py` supports two styles of code generation, described below.

### xUnit Style ###

The default style is xUnit style. In this form, `fructose_gen.py` will scan
C++ code looking for classes or structs that inherit from `fructose::test_base<>`.
Inside those classes or structs, member functions that match the following
pattern are assumed to be test functions:

      void testXXXX(const std::string&)

Upon finding such a function, `fructose_gen.py` will register that member
function as a test with the name "testXXXX". 


### Generator Style ###

To remain backward compatible with the `generator` program that ships with
Fructose, invoke `fructose_gen.py` with a `-g` or `--generator` option flag.

In this style, `fructose_gen.py` will scan files for the `FRUCTOSE_CLASS`,
`FRUCTOSE_STRUCT` and `FRUCTOSE_TEST` macros. See the Fructose documentation
for more information.


Caveats
-------

`fructose_gen.py` is not a true C++ code parser, and in fact is quite simple
in how it operates. This is sufficient for most cases, but please be aware of
the following limitations.

1. Ensure your class (or struct) definition is all on one line:

         class my_unit_test : public fructose::test_base<my_unit_test>

   If you split the above across multiple lines `fructose_gen.py` will not
   recognize your class and will not generate a test instance for it.

2. `fructose_gen.py` does not understand C-style comments or the preprocessor.
   To comment out a test, you can either use C++ comments, or change the function
   name slightly to ensure it won't be recognized. Examples:

          /*
          ** void test_is_sorted(const std::string& name)  // this won't work
          */

          #if 0
          void test_is_sorted(const std::string& name)   // this won't work
          #endif

          void not_a_test_is_sorted(const std::string& name) // this works
          // void test_is_sorted(const std::string& name)    // this works
          // FRUCTOSE_TEST(is_sorted)                        // this works

   The above also applies to commenting out test classes.


Support
-------
See the [fructose_gen support site][2] hosted at [bitbucket.org][3].


[1]: http://fructose.sourceforge.net/
[2]: https://bitbucket.org/bgneal/fructose_gen
[3]: https://bitbucket.org