XTRAN Example — Template-Driven Generation from Repository Data



Menu




Introduction

Scenario — you are a Master Data Manager (MDM) in charge of a "single source of truth" enterprise data repositoryMultiple materials (code, documentation, etc.) are individually generated from the data in that repository.  So every time there are changes in the data, all of the materials must be painfully recreated to reflect those changes — a laborious and error-prone process.

XTRAN to the rescue!

The following example uses an XTRAN rule set comprising 452 non-comment lines of XTRAN's rules language ("meta-code") to automate the template-driven generation of materials from data.  The rules took 1¾ hours to design, 4¾ hours to create, and 3¾ hours to debug.  (That's right, only 10¼ hours total!)

The XTRAN rule set these examples illustrate uses text data sources to instantiate a destination file from a text template, using data from one or more delimiter separated value (DSV) data files. (The most common form of DSV is comma separated values, or CSV.)  Such a data file might, for instance, be generated from a repository or exported from a spreadsheet.

The rules provide the following features:

These capabilities allow you to automatically generate a variety of materials from your data repository.  A change in the data can then trigger automatic regeneration of those materials, ensuring that they all remain synchronized and up to date.

A typical usage scenario would be to create procedures so that, whenever there is a change in repository data, the relevant data are automatically extracted from the repository in DSV form and XTRAN is run as needed to regenerate all materials affected by the change in the repository data.

Note that, by specifying the use of different data fields and field value editing in different XTRAN runs using these rules, you can generate a wide variety of materials from a single data source.  For instance, all of the examples below use the same data file to generate dramatically different materials.

How can such powerful and generalized template-driven generation from a repository be automated in only 10½ hours and only 452 code lines of XTRAN rules?  Because there is so much capability already available as part of XTRAN's rules language.  These rules take advantage of the following functionality:

The input to and output from XTRAN are untouched.



Process Flowchart

Here is a flowchart for this process, in which the elements are color coded:

data flowchart

Examples




All of the following examples use the same data file, data1.dsv, which contains:

? Data file for XTRAN examples
? Revised 2018-08-01.1630 by Stephen F. Heffner
?
? Fields:  Function name, return type, flags, comment
?
FNC1,INTEGER,21,comment1
F2,real,1fff,comment2
func3,REAL,FFF1AF,comment3
fnc4,integer,,comment4
?
? End of data file

Because this data file uses a comment character other than the default of ; (semicolon), we specify ? as its comment character in repetition commands that name it.  However, it uses the default DSV data delimiter of , (comma), so we don't need to specify that.

Each of the examples also assumes environment variables set to:

For each example, the instantiated output file is shown.




Example 1 — generate an HTML table

In the template for this example, we specify the following editing for each field:

Field description Force case Prefix Suffix Min field width Justification Fill character
Function name Lower <TD> </TD>      
Return type Upper <TD ALIGN="right"> </TD>      

Instantiated target file, as HTML:

<HTML>
<!--
Function return type table; automatically generated 2018-01-01
with XTRAN from data1.dsv
-->

<DIV>

<TABLE>

<TR>
<TH>Function name&nbsp; &nbsp;</TH>
<TH ALIGN="right">Return result type</TH>
</TR>

<TR>
<TD>fnc1</TD>
<TD ALIGN="right">INTEGER</TD>
<TR>

<TR>
<TD>f2</TD>
<TD ALIGN="right">REAL</TD>
<TR>

<TR>
<TD>func3</TD>
<TD ALIGN="right">REAL</TD>
<TR>

<TR>
<TD>fnc4</TD>
<TD ALIGN="right">INTEGER</TD>
<TR>

</TABLE>

</DIV>

</HTML>

Instantiated target file, as rendered by this browser:

Function name    Return result type
fnc1 INTEGER
f2 REAL
func3 INTEGER
fnc4 REAL


Example 2 — generate a C array of structures


In the template for this example, we specify the following editing for each field:

Field description Force case Prefix Suffix Min field width Justification Fill character
Function name     ", 10 (defaulted to left) (defaulted to <SPACE>)
Flags Upper     8 Right 0
Comment Lower          

Instantiated target file:

#include "stg.h"
/*
 * Function flags table; automatically generated 2018-01-01
 * with XTRAN from data1.dsv
 */
    struct stg stg_table[] =
        {
        { "FNC1",   0x00000021 },       /*comment1*/
        { "F2",     0x00001FFF },       /*comment2*/
        { "func3",  0x00FFF1AF },       /*comment3*/
        { "fnc4",   0x00000000 },       /*comment4*/
        { NULL }                        /*end of table*/
        };

Note that, because data1.dsv's data line with fnc4 has no value for the "flags" field, the XTRAN rules zero-filled that field to the minimum field width of 8.



Example 3 — generate a text document

In the template for this example, we specify the following editing for each field:

Field description Force case Prefix Suffix Min field width Justification Fill character
Function name            
Return type Upper          
Flags       1   0

Instantiated target file:

This document was automatically generated 2018-01-01 with XTRAN
from data1.dsv, which was extracted from our repository after
changes in repository data.

The function FNC1 has a return type of "INTEGER".  Its flags are
0x21.

The function F2 has a return type of "REAL".  Its flags are
0x1fff.

The function func3 has a return type of "REAL".  Its flags are
0xFFF1AF.

The function fnc4 has a return type of "INTEGER".  Its flags are
0x0.

For more information about this document, please contact our repository
administrator.

Note that, because data1.dsv's data line with fnc4 has no value for the "flags" field, the XTRAN rules zero-filled that field to the minimum field width of 1.

###