|

Class templates

Introduction

The Ionflux Tools Class Library distribution provides a set of class templates, which can be used to create interfaces and implementation skeletons for C++ classes using the Ionflux Tools Template Engine. Using class templates instead of writing everything by hand (or using copy & paste) has at least all of the following advantages:

• Spend more time actually writing good interfaces than formatting header and implementation files.
• Documentation tags are generated automatically from your interface specifications and documentation hints. So you save time without compromising good code documentation.
• Prevent typing errors in dull repetitive code fragments or documentation tags.
• Create implementation skeletons that instantly compile, even if implementation is not yet completed. So you can start testing code as early as possible and save debugging time.
• Automatically include license disclaimer, copyright notice etc. with header and implementation files.
• Support of properties and automatic generation of corresponding accessor functions (although C++ does not natively support properties, you won't notice the difference after some time using this feature).
• Changing interfaces becomes a lot easier.
• Preview the implementation skeleton of new classes as often as you like before generating the actual files.
• Templates and configuration are fully customisable.
• It's easy to write code to generate more code automatically.

At the moment, the class templates are useful for generating interface and implementation skeletons. You will still have to do some work though to fill in the function bodies and add specialties not yet supported by the class templates. However, using the class templates can save you a lot of work in creating nicely formatted, documented new classes for your project. See the files in the conf directory of the distribution for examples. The class templates are located in the template directory of the distribution. They are written to be somewhat general on purpose, but you can of course modify them to fit the specific requirements of your project.

See conf/class/ExampleClass.conf for an example of how to use class templates. You can generate the class header and implementation for the ExampleClass using:

iftpl template/class/Class.hpp.tpl conf/class/ExampleClass.conf
iftpl template/class/Class.cpp.tpl conf/class/ExampleClass.conf

Class template features

This section provides an overview of the features provided by the Ionflux Tools class templates. You can set class configuration directives in a configuration file (see Configuration file I/O) and invoke iftpl (see Template Engine) at any time to create the header and implementation files for the new class.

Project

The project configuration directive defines general information concerning the project which a class is part of. You can use any of the following options:

name Name of the project.
author Author(s) or copyright holder of the project (this will be used in the file header).
mail Project e-mail address.

File

These directives can be defined in the root configuration context to set additional options:

copyrightYear Copyright year or range of years.
includeGuardPrefix Include guard prefix. This will be prepended to the class name (in upper case) to define an include guard for header files.

Namespace

Use the namespace directive to specify namespaces which the class should be a member of. The namespace directive supports only one option:

name Name of the namespace.

Using

The using configuration directive specifies a list of using directives to be included in the implementation file. It does not have any options.

Include

The include configuration directive specifies a list of header files to be included (using the #include preprocessor instruction) in the class header file. It does not have any options. You can use either include.header or include.impl, depending on whether you want the include directives to appear in the header or implementation file.

Forward

The forward configuration directive specifies a list of forward declarations to be included in the class header file.

Struct

This directive can be used to specify helper structs that should be declared along with the class in the header file. The following options are supported:

name Struct name (this must be a valid C++ struct name).
desc Short description.
field A field of the struct. This supports the options type for field type, name for field name and desc for field short description.

Class

This directive provides general information about the class. You can use any of the following options:

name Class name (this must be a valid C++ class name).
shortDesc Short description (this may describe the class in a more human-readable way).
longDesc Detailed description of the class, usage hints etc..
includeDir Directory where the header file for this class is located.
base List of base classes including access specifiers.
group Documentation group (or module). This supports the options name, for group name, shortDesc for group short description and longDesc for long description. Note that you have to define shortDesc and longDesc only once (i.e. in only one class configuration file).

Constructor

Use the constructor.public directive to define a constructor. The default constructor (and destructor) will always be generated automatically, so you do not have to configure them explicitly. Constructor directives support the following options:

param Function parameter. Use the name option to specify the parameter name, the type option to specify the parameter type and desc to specify a short description for the parameter. Default values for parameters may be specified with the default option.

Variables

Use either the variable.public, variable.private or variable.protected configuration directives to specify class member variables. The variable directive supports the following options:

spec This may be used to define static variables (set to static).
type Variable type.
name Variable name (this must be a valid C++ variable name).
desc Short description of the variable.
value Set the initial value of a static variable.

Property

Properties are a special type of variables that can be publicly accessed through special functions (called accessors). Accessors are usually named after the variable, with a get or set prefix. You use the get accessor function to read the current value of the variable and the set accessor function to set the value of a variable. Properties have the advantage of additional access security, possibilities for sanity checking and separation of the data representation from the interface. Thus, it is a always a Good Thing to use properties instead of public variables. However, usually this means some overhead in writing the accessor functions. Not so with the Ionflux Tools class templates, since you can just define properties like you would define any member variable. You do this by using either the property.private or the property.protected directive, which support the following options:

type Type of the property (the type that will be returned from a get accessor function).
name Property name.
setFromType Type from which the property can be set (used in the set accessor function).
desc Short description of the property.

Using the property directive with the unmodified class templates will create default data representations and accessor behavior. Of course, you can change this to any representation and behavior you like.

Function

You can use the function.public, function.private and function.protected configuration directives to define member functions of the class. Each of these directives supports the following options:

spec Function specifier (set to virtual for virtual functions).
type Function return type.
name Function name.
const Set to true to define a const function.
pureVirtual Set to true to define a pure virtual function (pure virtual functions are declared as such in the header file but not included in the implementation skeleton).
shortDesc Function short description.
longDesc Long description, usage hints etc..
param Function parameter. Use the name option to specify the parameter name, the type option to specify the parameter type and desc to specify a short description for the parameter. Default values for parameters may be specified with the default option.
return Return value. Use the value option to specify an expression which will be used as return value of the function and desc for a short description of the return value.

---