xmi2code Reference Rev 0.3

Do round trip code generation for UML

xmi2code website

TOC


Top

Overview

xmi2code provides a program for round trip code generation for xmi files. It consists mainly of three parts:

  • Handler:
xmi reader specialized for xmi sources
  • Model:
xmi independent representation of the UML data
  • Generator:
a set of specialized generators ( e.g. c++, php )

Features are:

  • Round Trip Generation:
Generators provide incremental code generation. That means: if a class has changes, just generate again over the sources. xmi2code will not remove your coding, instead it will add, delete or change Functions and Attributes
  • Tags in Diagrams:
Some extra tags can be added in the UML definitions. For example a constructor init list could be provided in the diagrams!
  • Access functions:
Automatic access functions for class attributes, if you want.
  • Ctor init list:
Automatic, overrideable constructor init list generation
  • Qt Support:
Support of Signal/Slots Q Object technique
  • Workaround for Umbrello:
Help for Umbrello with missing virtual, const and inline settings
  • Expandable
Easily expandable for new handlers and generators
Umbrello Homepage

Top

Command Line

usage: xmi2code [<command line options>] [target(s)]
-a Process all targets in project
-c config-file Use given configuration file. Default: xmi2code.config.
-d Dump all options before processing.
-f xmi-file Use given file as xmi-input.
-g generator Specify generator.(ada,cpp,php,php.pear,pro)
-h handler Specify handler. Default: umbrello
--help Show short help and exit.
-o key=value Set option key to value.
-v Show version and exit.
-x Stream out current option data for a config file and exit

Top

Installation

xmi2code is just a simple program. No Installation ist required.


Top

Options

xmi2code support some options and it is possible to create user defined options.

xmi2code General Options

Key Description Default value
target Target(s) for generation. At this time this could be "*" or one or more class names. ""
xmi-input File name of the xmi file which should be parsed. ""
config-file File name of the configuration file which should be used. "xmi2code.config"

Configuration File

xmi2code can be configured with a configuration file. The format is xml. There are three tags:

  • xmi2code:
is the root tag, nothing else.
  • option:
here you can set a option with the attributes: "key" and "value".
  • if:
conditional tag. It has the attribute "test" where you can specify a condition. If the condition is true the tree under "if" is evaluated. If the condition is false the tree under "if" is ignored. The only supported condition is key=value to test the value of options. If tags can be nested: option and if tag als children are allowed.

xmi2code looks for a default configuration file: xmi2code.config in the current working directory. You could override this in the command line.

Order Of Option Reading

There are three steps for reading the options:

  • Default values:
First some default values are evaluated.
  • Configuration file:
Then the values of the configuration file will be set
  • Command line:
At last, the values from the command line will override the options

Top

Handlers

xmi2code generally supports different handlers for xmi files. At this time only one handler is available: Umbrello.

Key Description Default value
handler Selection of the handler that should be used. "umbrello"



Handler: Umbrello

Code for options: "umbrello"

Type coded features

Umbrello handler supports some missing features of umbrello. They are coded in the type of operations by putting the key words before the type, separated by a colon.

  • Virtual Functions:
Virtual functions can be declared with "virtual"
  • Const Functions:
Const functions can be declared with "const"
  • Inline Functions:
Inline functions can be declared with "inline"
  • Signals:
Qt Signals can be declared with "signal"
  • Slots:
Qt Slots can be declared with "slot"
Example:
inline const:int

Example:
signal:void

Example:
slot virtual:double

Documenation coded features

This handler supports some addional features. They are coded in the documentation of objects ( class, operation, attributes, associations ). A coded line in a documentation begins with "x2c:". Here the list of the features:

Command Description Example
external
extern
Scope:Class
Mark a class a external, that means, this class is not member of the project.
x2c:external
noclass
noc
Scope:Class
Mark a class as a container of functions. This feature is limited to generators of languages that can define functions without a class.
x2c:noclass
include:
inc:
Scope:Class
Parameter:include file name
Use the given include file name, if a include for this class is necessary.
x2c:inc:qxml.h
define:
def:
Scope:Class
Parameter:code
Write the code in the class scope: For example, if want to define a enum in the class.
x2c:def:enum ABC {a,b,c};
cit: Scope:Operation
Parameter:Attribute|Baseclass=value
Write an entry into the constructor initialization list. Note that the c++ Generator writes all default values to the init list. But here you can override them, or use a base class constructor.
x2c:cit:mPI=3.14;
set Scope:Attribute
Add a set function for the attribute. How to do this, is task of the generator.Can be combined with "get"
x2c:set get
get Scope:Attribute
Add a get function for the attribute. How to do this, is task of the generator.Can be combined with "set"
x2c:get
primary Scope:Assocation (inheritance)
This inheritance should be at first in the class definition.
x2c:primary
public Scope:Assocation (inheritance)
Inheritance is public
x2c:public
protected Scope:Assocation (inheritance)
Inheritance is protected
x2c:protected
private Scope:Assocation (inheritance)
Inheritance is private
x2c:private
virtual Scope:Assocation (inheritance)
Inheritance is virtual
x2c:virtual

Top

Generators

Common Generator Options

Here are options that most generators use:

Key Description Default value
generator The value of this option selects the code generator which will be invoked. ""
template-path Points to the template file directory. "templates"
generator-path Directory where the generators expect/create the source files. "generated"
use-package-as-dir xmi2code supports a source tree where UML-packages are directories and classes are files in these directories. true enables this. "true"
indent Indentation to be used. Default is 2 (two) spaces. " "
files-case Generated file and directory name case. Can be "lower", "upper". Any different value will not change the case. "lower"

Source Tags

xmi2code uses tags in the source file for the round trip code generation. These are:

  • +x2c
This is the start tag. From here to the end tag is xmi2code maintained code. All user changes between will be lost with the next code generation.
  • ~x2c
This is the end tag.
  • -x2c
This is a tag for only one line.

Do not manipulate the tags! if you delete or duplicate tags the code generator will tumble!

templates

Template files will be invoked if the generators create new files. You can use all options as Variables in the template. Just add two "@" before the option name.

Some options are effective at template invocation time:

  • filename
The current file name
  • package
The package of the current class
  • class
The name of the current class
  • date
A current timestamp

Feel free to modify the template as you like. If you use the default templates, set "project", "author", "email" and "system-base-include".



Generator: Ada Generator

Code for options: "ada"

This is a code generator for Ada.

Special Features:

  • Reserved
Explanation for Reserved.

Here are special options for this generator:

Key Description Default value
ada.template Which template file generator use for new files. "ada"
ada.extension Which extension the files should have. "ads"
ada.default-code Default code for new operations so the user does not forget to implement the operation. "not implemented"



Generator: C++ Generator

Code for options: "cpp"

This is an code generator for c++.

Features:

  • Ctor init list
The generator will generate automatic ctor init lists for attributes, which have default values. Inits for base classes and value overrides are supported. See used handler for how to set.
  • Access functions
The generator can create access functions for attribute on request. Therefor the name of attributes are taken, and the first lower letters are cut. Get-Function will be: get<cutted attribute name>. For bool values is <cutted attribute name> will be used. Set-Functions will be: set<cutted attribute name>. A limit of automatic access functions is reached with pointers. Please design your own access functions for pointers and decide const arguments and/or returns.
  • Q_OBJECT
If any Qt Signal or Slot is detected in the class, the generator will add Q_OBJECT in the class definition.
  • Class Scope Definitions
Class Scope Definition are possible, for example to make a class scope typedef. See used handler for how to set.
  • static,virtual,const,inline
Static,virtual(also pure virtual),const and inline functions are supported: See used handler for how to set.
  • static attributes
Static attribute, with or without default value, are supported.
  • Inheritance
Multiple inheritance is supported. Usage of external classes also with nonstandard file name is supported. For Qt, or better moc, the flag "primary" on inheritances is supported. To be sure, that Q_Object class are first in the inheritance list. Visibilities ( public,protected,private ) for inheritances are possible. Virtual inheritance is also supported. See used handler for how to set.
  • abstract functions
If you set a function "abstract" but not virtual, the generator will not generator a body for this function. Benefit: you can for example set private copy ctor and the assign operator abstract if you not to provide code for this forbidden functions.

But the generator is not complete: templates are not supported now.

Here are special options for this generator:

Key Description Default value
cpp.h-template Template file for .h (header) files. "cpp.h"
cpp.cpp-template Template file for .cpp (implementation) files. "cpp.cpp"
cpp.default-code Code, that will be used in first written functions. To be sure, that they will be coded. "#error not implemented."



Generator: PHP Generator

Code for options: "php"

This is an code generator for php.

Special Features:

  • References
The PHP generator supports both, parameter and function references. Just be sure to have an "&" in the type.

Here are special options for this generator:

Key Description Default value
php.template Which template file generator use for new files. "php"
php.extension Which extension the files should have. "php"
php.default-code Default code for new operations. To be sure not to forget to code this function. "not implemented"



Generator: PHP PEAR Generator

Code for options: "php.pear"

This is a code generator for PEAR style php code. Please check http://pear.php.net/manual/en/standards.php to see what this means.

Special Features:

  • Access functions
The PHP PEAR generator supports automatic attribute access functions, just like C++ generator. Functions for geting an attribute are prefixed with 'get' and then the attribute name with the first letter uppercased (example: myAttribute: getMyAttribute()). Functions for setting the attributes are prefixed with 'set'. To add autofunctions to an attribute just add a line in the attribute documentation with 'x2c:get', x2c:set' or simply 'x2c:get set' if you want both (see Umbrello Handler options for more info). If you want to get or set your attributes as references, just prepend '&' to the attribute type (example: &MyAttributeClass).

This generator also have special features from PHP Generator.

TODO:

  • More Class PHPDoc Comments
Now the class comment is lacking of @package, @author, @date, and maybe something else?
  • Better use of packages
Think about problems in having Package_Class as class name (method parameters and return type, and class attributes must have Package preapended, so I don't know if this is really useful).
Key Description Default value
php.pear.use-package-in-classnames Prepend the Package name in the classnames (like MyPackage_MyClass). This is a half done work, since the package name is only appended in the class definition (like class MyPackage_MySubClass extends MyPackage_MyClass), but not in parameters documentation, etc. (anything different to "true" it's evaluated to false). You can use '/' in packages to add more directory levels, like package 'My/Package', this will be translated to underscores in class name, like 'My_Package_MyClass'. "false"
php.pear.underscore-in-nonpublic Prepends an underscore ('_') to the methods and attributes names that are non public (ie, private or protected). "true"



Generator: QMake Generator for Classes

Code for options: "pro"

This is an generator for QMake ".pro" files. HEADERS and SOURCES variables would be fill with all classes, which are not marked as external. It does no round trip generation, because there is no source code. If you want to use it, just include the generated file in your QMake main file. The instruction is: include(<file-you-want-to-include>)

Here are special options for this generator:

Key Description Default value
pro.file The file name for the output. "x2c.pro"

Top

Lists and Tables

List of all Options

Key Description Default value
target Target(s) for generation. At this time this could be "*" or one or more class names. ""
xmi-input File name of the xmi file which should be parsed. ""
config-file File name of the configuration file which should be used. "xmi2code.config"
handler Selection of the handler that should be used. "umbrello"
generator The value of this option selects the code generator which will be invoked. ""
template-path Points to the template file directory. "templates"
generator-path Directory where the generators expect/create the source files. "generated"
use-package-as-dir xmi2code supports a source tree where UML-packages are directories and classes are files in these directories. true enables this. "true"
indent Indentation to be used. Default is 2 (two) spaces. " "
files-case Generated file and directory name case. Can be "lower", "upper". Any different value will not change the case. "lower"
ada.template Which template file generator use for new files. "ada"
ada.extension Which extension the files should have. "ads"
ada.default-code Default code for new operations so the user does not forget to implement the operation. "not implemented"
cpp.h-template Template file for .h (header) files. "cpp.h"
cpp.cpp-template Template file for .cpp (implementation) files. "cpp.cpp"
cpp.default-code Code, that will be used in first written functions. To be sure, that they will be coded. "#error not implemented."
php.template Which template file generator use for new files. "php"
php.extension Which extension the files should have. "php"
php.default-code Default code for new operations. To be sure not to forget to code this function. "not implemented"
php.pear.use-package-in-classnames Prepend the Package name in the classnames (like MyPackage_MyClass). This is a half done work, since the package name is only appended in the class definition (like class MyPackage_MySubClass extends MyPackage_MyClass), but not in parameters documentation, etc. (anything different to "true" it's evaluated to false). You can use '/' in packages to add more directory levels, like package 'My/Package', this will be translated to underscores in class name, like 'My_Package_MyClass'. "false"
php.pear.underscore-in-nonpublic Prepends an underscore ('_') to the methods and attributes names that are non public (ie, private or protected). "true"
pro.file The file name for the output. "x2c.pro"

Links

Umbrello Homepage: http://uml.sourceforge.net
xmi2code Homepage: http://xmi2code.sourceforge.net