WORM - DAL / ORM code generation framework

Copyright (C) 2011  Erik Winn (erikwinnmail at yahoo dot com)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

2011-11-18 - Version 0.2 UNSTABLE

WORM is a Data Abstraction Layer for access to database servers and an
Object Relational Mapping system.  It consists of libraries providing a
generic API for database access and database metadata mapping of schema
structure. On top of this there is a tool to generate C++ class files for a
given arbitrary database schema - "wormgen".  wormgen accepts a few
arguments setting the database to use and optionally username, password,
output directory, etc. - "wormgen -h" shows usage. See below for more information.

At this writing the framework only supports SQlite3 and MySQL databases.
and the default output supports Wt's (Web Toolkit http://webtoolkit.eu) Dbo
library.  It generates header files that (with a little adjustment sometimes)
will work with Wt::Dbo for existing database schemata.

The output is configurable using the WORM template system which uses
google's ctemplate for output templating.

Additionally the libraries provide a general API for basic database access
including query execution with structured result sets and runtime metadata
including column information such as name, data type, defaults, extras, etc.

NOTE: This API is not fully stable! I expect there to be some changes and
do not yet recommend building off the API for anything serious.  wormgen
is functional (if simple) and changes there should not cause problems but
the libraries are under heavy development.  There may be modifications
and these should be expected until this message is removed.
You have been warned :).

NOTE: THIS IS UNTESTED ON WINDOWS or MAC AND NOT LIKELY TO WORK CURRENTLY..
linux or Unices should be ok.

Requirements:

* cmake, make, gcc, libstdc++, stl
* Boost - basic, header only (algorithm/string, lexical_cast)
* SQlite3 libraries - you may comment out the sqlite driver in src/CMakeLists.txt
if you don't want SQlite3 support
* libmysqlclient - same applies, you may comment this out
* ctemplate 1.0; libctemplate (currently the no threads version - this can be changed in the cmake files)

Build Instructions:
You can either clone the repository with git:

git clone https://github.com/erikwinn/worm.git
 - which will create a directory named "worm" in your current working directory.

Or, download a tar.gz and do(the number corresponds to the current version):
tar xzvf erikwinn-worm-79a2021.tar.gz
mv erikwinn-worm-79a2021 worm
cd worm
cd ./build && cmake ../
make

This will build the libraries and wormgen under build/src. By default the static
library is built - uncomment the shared library in src/CMakeLists.txt and
comment out the static to change this (todo: add a configure script ..)

libraries: libworm.so libworm.a
binary: wormgen

 Installation(optional):
You must be root to install.

 make install  (OR) sudo make install
 ldconfig

 * This will install the libraries to /usr/local/lib/libworm.* and the
 * binary to /usr/local/bin/wormgen.  Code generation templates will
 * be installed to /usr/local/share/worm/

NOTE: You can also use wormgen without installing by doing something like this if
it was built with the shared libraries:
(use a full path to work outside this directory):

export LD_LIBRARY_PATH=./build/src
./build/src/wormgen

 Uninstall:
  rm /usr/local/bin/wormgen
  rm /usr/local/lib/libworm*
  rm -rf /usr/local/share/worm
Alternately you can do:
  cat install_manifest.txt | xargs rm

***************  USING WORM  *******************
wormgen Usage:
wormgen -h gives help on usage.

The database argument is the only required argument - you must have
a database already set up and access to it.  By default it assumes the username
is root with no password - for an SQlite3 database pass the filename as the
argument for -d database; eg.:

wormgen -d ./examples/blog.db

This will generate files in the current directory - to specify a different output
directory use -o /path/to/output

Other commandline arguments include:
-D driver ([default]mysql or sqlite)
-t template directory (default ./src/orm/templates)
-u username
-p password
-h help - use this to see all the arguments ..

Output:
The output can be configured by editing or creating new template files
in the template directory - any files in this directory are assumed to be
templates to use. These are the supported template types:

base class header - generates FooBase.h:
ClassDeclarationBase,               //class_declaration_base.tpl
base class source - generates FooBase.cpp:
ClassDefinitionBase,                  //class_definition_base.tpl
class header - generates Foo.h:
ClassDeclaration,                       //class_declaration.tpl
class source - generates Foo.cpp:
ClassDefinition,                          //class_definition.tpl

These are not yet implemented but will be soon:

EditViewDeclarationBase,       //edit_view_declaration_base.tpl
EditViewDeclaration,                //edit_view_declaration.tpl
EditViewDefinitionBase,          //edit_view_definition_base.tpl
EditViewDefinition,                  //edit_view_definition.tpl
ListViewDeclarationBase,       //list_view_declaration_base.tpl
ListViewDeclaration,               //list_view_declaration.tpl
ListViewDefinitionBase,          //list_view_definition_base.tpl
ListViewDefinition                   //list_view_definition.tpl

Database and class naming conventions:
 A table in the database should be named in lowercase with underscores
for best results (Note: this is optional but will avoid naming conflicts - wormgen
will still generate files for camel case naming schema). Ex: some_persons will
be transformed to a class SomePerson.  Columns like first_name will transform
to firstName.  Underscores for private variables, accessors, etc can be established
in the templates. Table names should be plural and will be transformed to singular.

Templates:
The templates use ctemplate and currently support only the tags in the default
template (which generates Wt::Dbo object headers). A decent introduction to
ctemplate syntax is available at the ctemplate website. The supported tags are
quite simple and self-explanatory - see the default template for more.

Library Usage and Documentation:

There are some small example programs under examples/ - I recommend
starting with these.  Also, the code is heavily commented - and there are copious
amounts of HTML formatted documentation under doc/html..

Enjoy!