Subweb Home
PLASMA Home
Overview
Template Syntax
Command Line
Template Tutorial
Worked Example
Code Style Guide
Schema Definition
Error Messages
Problem Reports
PARSEC Licence
Template Language Syntax
Introduction

PARSEC implements a powerful relational Archetype Language by defining a small number of control statements known as Directives.

Each template file is partitioned into regions. Directives declare where regions start, what context they expose and where they end.

A region provides a context based on a simple join query executed over any number of tables from the Metamodel. The default, top most Region does not have a context associated with it and this region is called the null region.

The current context allows attributes from the tables included by queries to be written out to the generated code file.

During processing, PARSEC ignores all white space including carriage returns & line feeds and although the template files are free format, there is a Style Guide available which ideally should be followed. The file extension for template files is .mcx (MDA Code Executable).

A PARSEC template Syntax Definition File for the TextPad text editor on the Windows platform is available here. To download the .syn file you may have to right click on the link and select "Save Target As...".

PARSEC Directives

The PARSEC language does not have the concept of variables or conditional statements such as "if", "while" or "case". They are unnecessary because conditionality is always encoded in the Metamodel.

However, there are Selector Directives which allow instances or rows to be selected on row position. But there is no facility to select rows on data values within a particular attribute or column.

Directives define regions and also select and exclude instances, open and close output files and write fields from the Metamodel.

During execution, the contents of a template file is written to the output stream unless a Directive instructs otherwise.

All Directives are contained within brackets. The start bracket is defined by the string "<<<", and the end bracket by ">>>".

Format Directives

These Directives improve how the template file or its generated output will appear.

The <<<| Your comment here.>>> Comment Directive can be used to insert a comment anywhere in a code template. The Directive can be used in its shorthand form by simply placing a "|" character any where on a line, except within the brackets of another Directive. This will cause all characters from the right of the "|" to the end of line to be ignored.

White space, including carriage returns and linefeeds, are not copied from the code template to the output stream. To cause output text to be placed at the start of a new line it must be prefixed by the <<<:>>> New Line Directive. By convention, but also because it improves the appearance of template files, it is usual to start line sequences with this Directive, rather than it be placed at the end.

The <<< >>> Space Directive copies the same number of spaces contained within the brackets to the output stream. This directive is most useful when placed at the start or end of a line where leading and trailing spaces are ignored. It is also used after a Tab Directive to ensure at least one space separates two consecutive stings of output text.

Indenting code always improves its appearance, as does lining up columns in tables. The        <<<!05>>> Tab Directive, for example, ensures that the next text sent to the output stream will start in column 5. If the existing text on the output line is already on or over the text position specified, the Directive is ignored.

The Template Directive

Regions are defined by the Template Directive. For example, <<<Template=Page>>> defines a region where the context covers the Page table. Here all the attributes of the Page table from the Metamodel are made available. The end of the region is defined by the <<<Endplate=Page>>> Directive.

The Template Directive can also provide a context over multiple tables or objects from the Metamodel. For example, <<<Template=Page,Menu,Option>>> allows related attributes of Page, Menu and Options to be accessed within the region covered by the Directive.

The order of instances in a table in the Metamodel does not have any relevance to the Translator Engine. Because the rows provided by a context are returned in an arbitrary order, a code template should not be written to depend on the order of returned instances.

PARSEC templates enforce the analysis rule that between any two instances there may only exist a single relationship.

Selector Directives

An unmodified context makes all instances available to the region. Selector Directives allow only certain instances to be chosen based on returned position. These Directives do not exclude on the basis of data contained within the instance.

Selector Directives are only valid while a context exists. In other words, they are only used within a region or sub region defined by a Template Directive.

The <<<[>>> Copy Except Last Directive will copy over all iterations except the last to the output stream. This means that the last instance returned by the context will be excluded from processing within the region. The <<</[>>> command terminates the Region. In fact, the "/" character is used to signify the closing of all regions, except for Template Directives.

Working in the opposite way, the <<<]>>> Copy Last Directive will copy only the last iteration to the output stream.

Similarly, the <<<{>>> Copy First Directive will only copy over the first instance and the <<<}>>> Copy Except First Directive copies all instances except the first.

If no instances exist within a Region, the <<<~>>> Null Instance Directive is used to write specified text to the output stream. The text will not be written if one or more instances exist.

Combining Selector Directives

It is possible to combine Selector Directives by enclosing one selector region within another. The table below summarizes the effect of selectors on each other:

                   [ ] { }      Context

               [{  X   X    |
               [}  X     X  |- 3 Instances
               ]}    X   X  |

               [{  X   X    |- 2 Instances
               ]}    X   X  |

               ]{    X X    |- 1 Instance

In words, the combination of:

       <<<[>>> and <<<{>>> - Returns first instance, except
                             when there is only one instance.

       <<<]>>> and <<<}>>> - Returns last instance, except
                             when there is only one instance.

       <<<[>>> and <<<}>>> - Returns middle instances.  Does
                             not return the first or last instances.

       <<<]>>> and <<<{>>> - Returns instance when there is
                             only one instance.
Data Directives

Code templates ultimately depend on data from the Metamodel being included in the generated source code. Data Directives specify what field of what table is to be copied over. For example, the <<<#WEB_Page.Reference>>> Normal Data Directive writes out an item of data without changing its format from the Page table in the Metamodel.

The field to be output is specified by using the dot notation. After the "#" which declares the type of Directive, the table name is given followed by a full stop (the selector) and then the column name. By convention the table object name is prefixed by the TLA (Three Letter Abbreviation) of the domain it belongs to. This not strictly necessary as the table's name and domain are always declared in the Metadata Schema, but it is useful for large systems. Because the format of the data is passed unchanged through the Template Engine, it is most often used with numeric fields.

The <<<$WEB_Page.Tag_Value>>> Lower Case Data Directive will convert the string which makes up Tag_Value to lower case regardless of its representation in the Metamodel. Similarly, the <<<^WEB_Page.Tag_Name>>> Upper Case Data Directive will change all alphabetical characters to upper case before output. The original data in the Metamodel is not modified. Finally, the <<<%WEB_Page.Title>>> Capped Case Data Directive will capitalize each word in the field before it is copied over.

File Directives

Normally, all output from the Template Engine goes to standard output. To redirect output to a file the <<<File>>> Write File Directive is used. This Directive declares two regions each with the same context. The first, bounded by <<<File>> and <<</File>>> is used to specify the file name to create for output. The second region bounded by <<</File>>> and <<<Close> contains further Directives specifying what should be written to the file.

It quite common to want to reuse code template fragments or need to be able to organize code templates by splitting them up into smaller sections. The <<<Include>>> Include File Directive declares a region, bounded by <<</Include>>>, that is used to specify a code template file name for processing by the Template Engine. The Template Engine permits the Include File Directive to be used recursively.

MON-10-NOV-2003