root/libcrash/trunk/README

INTRODUCTION
-------------------------------------
libCrash is a library of handy functions and classes for day to day use.

But it's a bit more than that. It also has the facility to extract the source 
of specific classes and functions into your own source tree. While this may 
sound a bit odd, I find it exceptionally useful for the kind of functions that 
libCrash contains.

libCrash consists of three seperate portions. 

The first is the source code, which is installed in a system wide directory. 
The module map is generated from this source code after it is installed.

crash-module is the second part, it is the means by which the modules can be 
queried and extracted. In addition to using crash-module to extract modules 
from libCrash, maps can be generated from arbitrary code. To do this, you can 
either insert //<module ...> tags into the source code manually or use the 
--auto parameter of crash-module to automatically generate a map from the 
source code. eg. 

        crash-module --source *.cc *.h --auto --module=module.map

The third and final part is crash-config. This lets you use libCrash as a 
standard, linkable, library. It has similar functionality to gtk-config or 
other scripts of that nature. For example, to link a test program to libCrash:

        gcc test.c `crash-config --cflags --libs` -o test

WHY?
-------------------------------------
I write a lot of programs. I write small utilities to help me in day to day 
use of the system and to help me in programming, as well as projects that 
aren't quite so small. libCrash is my way of making the task a bit easier.

The notion of a normal library is that it encapsulates functions that are 
used by other programs, so that they don't have to duplicate the 
functionality. This is a Good Thing.

However, there is also the case where a program only needs to use a very small 
subset of the required functionality of a library. Requiring that the user of 
a program have this library on their system just to run your little utility 
might be asking a bit much, which could lead to the person not using your 
program. How many times have you gone to freshmeat and seen a program that 
took your fancy only to find, upon further investigation, that it requires you 
to install 8 other libraries?

For an example of this, I'm going to use a program that I've developed myself. 
This program is called 'todo' and allows programmers to tag directories with 
a heirarchical list of outstanding tasks. Now this is not a complex program, 
however, I wanted to use XML to store the database of tasks and the program 
itself performed a large amount of string manipulation. Now for the first 
option I could have used something like libxml from the Gnome project, for 
the second I would have had to use various different libraries. By Using 
libCrash this is a non-issue. It has a basic XML parser built in as well as a 
large number of useful string manipulation functions. So all I had to do was 
this:

        crash-module --extract --module XML String --trim

This generated eight source files. Eh? Well, this is because the XML module 
relies on another module called Lexer (which, as the name suggests, is a 
lexical analyser). Lexer, in turn, relies on the module Regex (which is a 
C++ wrapper around the regexp library). So that gives us the eight source 
files:

        XML.cc XML.h
        Lexer.cc Lexer.h
        Regex.cc Regex.h
        String.cc String.h


HOW?
-------------------------------------
libCrash uses tags inside comments to define where modules are and what they 
require. 

When parsing an input file, the logic is as follows:

For each source file, extract and store all lines of the form #include <....>. 
Any headers included with this form are automatically included in source code 
generated from modules. Headers of the form #include "..." are ignored. This 
is because they are assumed to be other modules which will be automatically 
included by a 'requires' attribute.

If a line of the form //<module ...> is encountered, the source between it and 
the corresponding //</module> line is added to the list of source segments in 
that module. This allows multiple segments (possibly from seperate source 
files) to be merged to make one module.

Any modules listed in the 'requires=...' attribute for a module are added as 
#include lines when generating output. So if you had requires=Lexer, that 
would end up being #include "Lexer.h".

Modules have to have a 'name=...' attribute to determine what name to give the 
generated output source files.

Another attribute, but one that is optional, is the 'description=...' one. It 
lets you give a human readable description of the modules functionality. This 
can be displayed by passing the --verbose option to crash-module.

The optional attribute 'include=...' is used to force inclusion of headers 
that are only used for one module, but not others in the same source file. 
This is handy if you have one input source file with a whole lot of functions 
but wish to seperate the individual functions into seperate modules.

The last attribute is the 'optional' attribute, which lets certain 'required' 
modules be excluded if their use is optional. The XML module is one that uses 
this functionality. It can optionally use the Signal module to allow callbacks 
to user programs. However, if this functionality is not required, crash-module 
can be passed the parameter --exclude when extracting modules. This is 
handled in the module source code by using #ifdef's. Each module defines a 
macro of the form CRASH_<module>. So in the case of the XML module it would 
have '#ifdef CRASH_SIGNAL' around any code that uses Signal functionality.

Taking the above example further, the following example shows a snippet of 
the XML module.

XML.h
-----
#ifndef CRASH_XML
#define CRASH_XML

#include "Lexer.h"

//<module name=XML requires=Lexer optional=Signal description='XML parser'>
class XML {
        ...
#ifdef CRASH_SIGNAL
        Signal1<string const &> onElementEnd;
#endif
        ...
};
//<module>

#endif

XML.cc
------
#include "XML.h"

//<module name=XML>
XML::XML() {
}

XML::~XML() {
}

...
..
.
//</module>