worm/README

WORM - DAL / ORM code generation framework

Copyright (C) 2011  Erik Winn (sidewalksoftware at gmail 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.

2013: Version 0.2.1

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 "USING WORM" 
below for more information.

Why "Yet Another ORM" - simple: I could not find a C++ ORM class 
generator for linux that would take the schema from an existing
database and generate the ORM layer. Everything I found did things
like force one to create an XML description of the schema from which
both SQL and C++ would be generated. Or do the database in C++
classes first (with some special syntax or #pragmas) .. I like SQL - it is
a good language for design, I frequently do the schema (aka "Model")
first when I am designing and then derive the architecture from that.
I didn't want to be forced to do that in OO - just a personal design
preference (aka "Model Driven Architecture"). Erm, plus I happened
to _have_ an existing database and wanted to port an app from PHP
to C++ ..  why do what you could do manually in 3 days by hand
when you can spend a month automating it? Really - which is going
to be more fun, huh?

Hence, libworm and wormgen.

At this writing the framework only supports SQLite3 and MySQL 
databases. and the default output supports Wt's Dbo library.  
(Web Toolkit http://webtoolkit.eu) It generates header files that 
(with a little adjustment sometimes) will work with Wt::Dbo for 
existing database schemata. There are also example templates that 
generate *.h/*.cpp pairs containing CRUD methods for Qt and 
generic C++ with SQL (See below under "Templates")

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 still under 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
* 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 - you can 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:

wormgen -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 (read someday..):

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). 
Eg: 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 class names - 
eg. users table becomes class User. Wormgen tries to be clever about
irregulars (eg. fly -> flies) - but isn't yet brilliant and only speaks english, 
so ..

***************  USING WORM TEMPLATES  *******************
Templates:
(examples are under <worm_directory_where_ever>/src/orm/templates.)

The templates use ctemplate and currently support the following tags: 

******* Top Level ********
(These may be used at any level)
"CLASS_NAME"
"TABLE_NAME"

 ****** Sections (lists) *******
"BELONGS_TO"   = appears when a class has a many to one relationship with another class
"COLUMNS"   = contains a list of COLUMN dictionaries
"HAS_MANY"   = appears when a class has a one to many relationship with another class
"INCLUDES"   = #include <string>, #include "footableclass.h", etc. (hopefully correctly ..)
"FORWARD_DECLARATIONS"  = forward declarations when there are pointers in a header
"PK_SECTION"  = appears when a table has an  identifiable primary key. Note: compound keys are not handled - wormgen will simply generate multiple versions of the section and you will have to select/edit as needed 
"UNSUPPORTED"  = appears when an unsupported variable type is encountered (eg. BLOB)

******* List Items ***********
  In COLUMNS:
    "CURRENT_COLUMN_NUMBER" = the current column number (0...COLUMN_COUNT - 1)
    "COLUMN_COUNT"  = number of colums found in table. This also holds CURRENT_COLUMN_NUMBER + 1 during COLUMNS loops 
    "COLUMN_NAME"  = eg. "user_name"
    "COLUMNS_separator"   = Actually a section - strings inside will be repeated for every column except the last.
    "DATATYPE"   = int, char, short, std::string, etc.
    "FOREIGNKEY_CLASSNAME"   = eg. Session (foreign key in users table) -- one to many; HAS_MANY section
    "FOREIGNKEY_CLASS_PLURAL"  = eg. Sessions
    "REFERENCED_CLASSNAME"  = eg. UserType (foreign key to user in user_type table) -- many to one; BELONGS_TO section
    "REFERENCED_TABLENAME"  = eg. "user_type"  -- many to one; BELONGS_TO section
	"REFERENCED_VARIABLE_NAME" = eg. "userTypeId" - the foreign key variable  -- many to one; BELONGS_TO section
    "VARIABLE_NAME"  = eg. userName
    "VARIABLE_GETTOR"   = eg. getUserName
    "VARIABLE_SETTOR"   = eg setUserName
    "UNSIGNED"  = Actually a section, appears if variable is unsigned ..
  
  In INCLUDES:
    "INCLUDE"  = eg. "#include usertype.h"
  
  In PK_SECTION:
    "PK_VARIABLE_NAME"  = the class member that represents the primary key column, eg. userName or userId
    "PK_COLUMN_NAME"  = the database name the primary key column, eg. user_name or user_id
Note that multi column keys will generate duplicate sections for each key - edit/select as needed in the generated classes (or don't use multi column keys)
	
There are several example templates under: 
<worm_directory_where_ever>/src/orm/templates.

These show some tag usage possibilities - Note however that the templates 
probably won't work "out of the box".  They will do most of the heavy lifting 
of ORM boilerplate but the generated classes will likely need at least some 
tweaking to work, YMMV. However, since the output _is_ templated it is of 
course possible to tweak the templates themselves or create new ones - maybe 
even a perfect "out of the box" example (which would be a welcome 
contribution). 
The out put is not restricted to C++ (except that currently wormgen will 
create std::string variables for VARCHAR - this may change to be more 
flexible in future).

The current default template generates Wt::Dbo object headers. 

 A more thorough introduction to ctemplate syntax is available at the 
ctemplate website ( http://ctemplate.googlecode.com ). 

***************  USING WORM LIBRARY (libworm) *******************
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. 
Although wormgen itself is now pretty stable the library is still mostly a 
Pull model and needs more work to be useful in a general sense - still you 
may find use for it. Documentation for library usage will probably appear 
sometime after the library itself is more complete.

peace,
-e