|Overview||Template Sample||Config Sample||Reference|
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:
element specifies which files are actually generect by XCG. Each file to be
generated will have a seperate
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:
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.
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:
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 - "<child-v>". I find the former much easier to read, but I won't be arogant enough to assume that is the case for you ;-)
<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:
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!
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:
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):
The syntax of these 3 elements are currently the same. There purposes are as folows:
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:
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:
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.