A C++ DAL / ORM code generation framework
Erik Winn 9a614869e9 * fix WSqlDatum data<> methods, do not reuse sstream (it appends data ..) 4 years ago
cmake Added find ctemplate cmake module, changed CMakeLists to use variables for linkage 6 years ago
doc Refactoring accessors, updated docs 5 years ago
examples Formatting and minor adjustments 5 years ago
src * fix WSqlDatum data<> methods, do not reuse sstream (it appends data ..) 4 years ago
CMakeLists.txt * removing boost dependencies 5 years ago
Doxyfile API Refactoring - changed execute() to be query(), use when results expected 7 years ago
LICENSE changed email address 6 years ago
README * README additions for new tags 5 years ago
install_manifest.txt Added install targets and documentation 7 years ago

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