The generation process is defined by 2 or 3 files, as follows:

The process of generation is straight forward, as it follows a specific set of sequences, as follows:

  1. For each <file>
  2. Step through the children of the <file> in the order they exist
  3. For each target <template>, generate them in the order they exist.


<file> element

The <file> element specifies which files are actually generect by XCG. Each file to be generated will have a seperate <file> element.

This element specifies the pathname of the file as well as the templates that are used to generate its contents.

The following is an example of a simple <file> element:

<file name = "&lt;file&gt;/&lt;root-c&gt;.hpp" >
    <content type = "template" > header elements </content>
</file>

Within the <file> element, the name attribute specifies the pathname of the file. In this example, the file will be created in a directory, the name of which is the same as the basename (i.e. without an extension, if it had one) of the file being generated from (i.e. the source instance data file, NOT the template file). The file that is created has the same name as the root element, with ".hpp" appended, and the first character capitalized.

For example, if we were generating from "foo.xml", and the root element in the file was <fubar>, then the file generated would be "foo/Fubar.hpp"

The <content> element defines what the file will contain after generation.


<content> element

The <content> element is used for either inline content or as a refererence to the <template> elements that define the contents.

If not specifying inline contents, then there must be a <type> attribute. The <type> attribute can only contain the value "template", which means it refers to a <template>. The value of the element is the named of the <template> to use. Other types may be supported in the future.

For inline versions, the value of the element is the actual contents that will be placed into the file (after transformation of course).

Here is a sample <content> element:

<content name = "major divider" >
<![CDATA[
//=============================================================================
]]>
</constant>

Something very important to note here is that a CDATA section has been used to provide the value of the element. This is a good idea, as all formatting will be preserved when generating the file, in addition to not needing to specially encode the keywoards; Since you can't use a < (and others) without encoding it, it allows the actual keywords to be used - "<child-v>" - instead of having to encode them specially - "&lt;child-v&gt;". I find the former much easier to read, but I won't be arogant enough to assume that is the case for you ;-)


<template>  element

<template> elements are used for several purposes:

Here is a more complicated sample iteration <template> (from xcg.xml), that combines some of what we know so far:

 1   <template name = "source elements read attributes" type = "attributes" order = "alpha" >
 2       <content if = "firstAttribute" >
 3   <![CDATA[
 4       // Get attributes if provided
 5       xmlChar* ]]>
 6       </content>
 7       <content if = "notFirstAttribute" >
 8   <![CDATA[
 9       ]]>
10       </content>
11       <content>
12   <![CDATA[
13   a = xmlGetProp(n, reinterpret_cast<xmlChar*>("<attribute>"));
14       if (a)
15       {
16           _<attribute-vt> = reinterpret_cast<const char*>(a);
17           xmlFree(a);
18       }
19   ]]>
20       </content>
21       <content if = "lastAttribute" >
22   <![CDATA[
23      
24   ]]>
25       </content>
26   </template>

Line 1 specifies that the name of this element is "source elements read attributes", that it will iterate through the attributes of the owning element (which itself has to be iterated), and that the iteration order is alphabetic.

What does this mean? It means that when XCG executes this template, it will do so by applying this template to every attribute that the parent element has, and it will do so such that the attributes will be iterated in alphabetical order.

The <content> element on line 2 will only be generated when the first attribute is iterated. After then, it will be skipped.

The <content> element on line 7 will only be generated when the last attribute is iterated. Before then, it will be skipped.

The <content> element on line 11 will be generated into the output every for every attribute that exists in the element.

Finally, the <content> element on line 21 will only generate before the last attribute is iterated. It will not be executed on the last attribute, but will be on all others.

I think the power of XCG is starting to show now. With the conditionals, <template> elements, ability to iterate, etc., there is very little that XCG can't do, and you don't even know about custom conditions and elemenet meta data yet!


Transformations

By now I'm sure you are wandering how the element, attribute, and child names are placed in the output? Well, its actually pretty simple: by specifying them as if they were XML elements!

If you look back at the previous example, on line 13, you'll notice near the end of the line that <attribute> that looks like an XML element. In truth, it's NOT an XML element (because its in a CDATA section, and would have to be done differently if it wasn't), its where the currently iterated attribute name will be substituted. So, for example, if the current attribute being iterated was type, then line 13 would actually generate:

a = xmlGetProp(n, reinterpret_cast<xmlChar*>("<type>"));

Transformations - like capitalization, pluralizing, etc. - are accomplished on the text name of the substitution (in this case, the attribute name) by adding transformation characters at the end of the substitution keyword.

For example, to pluralize the <attribute> type in the previous example, you simply change the keyword from <attribute> to <attribute-p>. To follow the previous example, <attribute-p> would produce a replacement of "<types>".

The number of transformations is only limited by the number that are defined (i.e. you can add as many transformation characters as desired to the keyword). Following the example once again, <attribute-cp> would produce "<Types>".

The currently defined transformation characters are (and the order they will be executed, regardless of the order they are added to the keyword):

t
Performs translations of invalid words to valid words. The invalid words, and their replacements, are specified with <replacement> element(s).
v or V
Performs validation of individual characters. For example, in c++, its not valid to have a - character in a identifier, so it would need to be replaced or removed. The invalid characters, and their replacements strings (note string, not character there) are specified with the <invalid> elements
The difference in v and V is that v replaces the character with the replacement string, while V deletes the character and capitalizes the following charactor. For example, for an attribute name "boo-boo" and the following invalid element:
<invalid context = "global" string = "-" > _ </invalid>
v would produce "boo_boo", while V would produce "booBoo".
p
Makes the value plural. The internal logic currently only adds an s to the end, so its important to specifiy words that cannot be pluralized that way with <plural> elements.
For example, the word "child" cannot be made plural just by adding an s, so the following <plural> element should be specified if its possible for child to need to be pluralized:
<plural context = "global" string = "child" > children </plural>
This specifies that anytime a request is made to pluralize "child" (regardless of case), that it be changed to "children" instead of just adding an s.
c or C
Captializes the value. c makes just the first character capitalized, while C capitalizes the entire value.


<invalid>, <plural>, and <replacement>  elements

The syntax of these 3 elements are currently the same. There purposes are as folows:

<invalid>
Specify invalid characters and their replacement strings for use with v and V transformations.
<plural>
Override p transformations for the specified word. Used when the default logic will produce an invalid value.
<replacement>
Specify invalid words and their replacements for t transformations.
For more specific details, see the reference page.


<condition>, <eval>, <element>, and <meta>  elements

New to 1.1.0 and later is the ability to specify custom conditionals for custom element specific meta data that you define.

Element meta data is specified through the <element> and <meta> elements, like this:

<element name = "foo" >
     <meta name = "value" > true </meta>
</element>

In the above case, the meta data is a value named "value", which is a true or false value specifying whether the foo element contains a value. In this case, it does.

Element meta data is only valid in a configuration file.

Now that we have the meta data, to use it, we create a <condition> element. Here is an example:

1   <condition name = "hasValue" op = "and" >
2        <eval op = "hasMeta" > value </eval>
3        <eval op = "equal" type = "boolean" >
4             <left type = "meta" > value </left>
5             <right> true </right>
6        </eval>
7   </condition>

This adds a new condition that can be used in the if attribute of a <content> element. It will evaluate to true only if the current element has an associated <element> element that contains a <meta> element with the name "value" with a value that evaluates to true.