Project: Charter, Tiny Java Code Generator from Statecharts
Release: charter-0-01

     Copyright (C) 2003 Andrzej Wasowski
               (C) 2003 Jorgen Stensgaard-Madsen
     
     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 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

MANUAL,v 1.1 2003/09/15 22:44:11 wasowski Exp




CONTENT

1. About this document
2. Credits & License
3. About CHARTER
4. Installation Note
4.1. File list
5. Usage
6. Input File Format



1. ABOUT

This file attempts to give an overview of CHARTER tool, its purpose, usage and
installation. 



2. CREDITS & LICENSE 

You should have received a LICENSE file bundled together with this
distribution. Please, refer to it for details on possible use and
distribution.

This little tool has been designed and implemented using DULCE interpreter
framework written by Jorgen Stensgaard-Madsen from Technical University of
Denmark.  Implemented by Andrzej Wasowski, It-University of Copenhagen and
Jorgen Stensgaard-Madsen, Technical University of Denmark.

This software was produced using (or incorporates parts of) VIM, emacs,
Mozilla, Sun Java, DULCE and numerous GNU tools.  It was developed working
under Linux/GNU operating system, however it should run on any operating
system supporting the above mentioned tools (including Microsoft Windows).




3. ABOUT CHARTER

CHARTER is an offspring of code generation project for embedded systems.
It is probably the smallest code generator ever implemented for Statecharts. 
The code of the actual code generator takes around 300 lines. The tarball
containing a complete tool is below 10 KB.

CHARTER takes a statechart description in a format which is very close to
hsm format of SCOPE (which means that SCOPE is likely to accept the same file
format soon). Technically files in .ch format are programs in the charter
language implemented in DULCE interpreter framework. Does CHARTER interprets
the input file treating keywords and other elements as instructions. The
semantics of these instructions is to produce code. A Java program is
generated on-the-fly during interpretation.

The .ch file is rather straightforward (see the sample cassette.ch file). A
more elaborate description should appear here eventually.

CHARTER produces a very simple code, which is easy to understand for humans.
It is not the objective of CHARTER to generated small heavily-optimized code.
In contrary, optimizations are omitted in favor of clarity. CHARTER
demonstrates the state pattern code generation-scheme and DULCE's
capabilities.

Please contact one of the authors if you find this tool useful, have a comment, bug
request or would like any other kind of support.




4. INSTALLATION NOTE

Firstly install DULCE and compile (available at
http://www.imm.dtu.dk/~jsm/dulce/)

Unpack the tar.gz containing a distribution of CHARTER.

Edit the charter file, changing the first line (interpreter incantation) to
the actual path, where dulce's demo language is available on your system.

Call make lib to compile the runtime system (or make all to compile the
runtime system and the example).


4.1 FILE LIST

In charter.tar.gz package:

charter     - A code generator script implemented in dulce's demo language
list 	    - Generic list manipulation library for dulce
pp	    - Generic helpers for pretty printing (dulce language)
cassette.ch - Sample model of cassette player

OR.java     - class representing OR-states (part of the runtime library)
Main.java   - an example of main function (for cassette player)

MANUAL      - this minimal instructions
LICENSE     - current license for CHARTER
Makefile    - makefile to compile the runtime system and the example




5. USAGE

Type make to see what make targets are available.

Use make lib to compile parts of runtime library. Use make all to compile
examples.

If you have a model file statechart.ch and want to generate code for it call:
	
	cat statechart.ch | ./charter > YourOutputFileName.java

Then you can browse the resulting java code, or compile it 

	javac YourOutputFileName.java

To run the model you also have to provide the main loop. See Main.java for an
example of such.



6. INPUT FILE FORMAT

TBD.

---------------------------------------------------------------------------