Keywords
There are two formats of keywords:
-
<keyword>
-
This is a direct replacement of the keyword without any modifications.
-
<keyword-transformations>
-
This version performs the transformations as specified after the - (dash).
The (currently) defined keyords, and what they mean, are:
-
<root>
-
Replaced with the name of the XML root element.
-
<element>
-
Replaced with the name of the current element when iterating through all
elements. This will generate an error if found while there isn't an element
iteration going on.
-
<attribute>
-
Replaced with the name of the current attribute when iterating through an
elements attributes. This will generate an error if found while there isn't an
attribute iteration going on.
-
<child>
-
Replaced with the name of the current child element when iterating through an
elements children. This will generate an error if found while there isn't a
child iteration going on.
-
<date>
-
Replaced with the date that the generation was started. Note that the date/time
is retreived once, at the start of generation. This means that all
<date>
keywords will be replaced with the exact same date. The format of the date is
YYYY-MM-DD (for example "2004-10-24").
-
<time>
-
Replaced with the time that the generation was started. Note that the date/time
is retreived once, at the start of generation. This means that all
<time>
keywords will be replaced with the exact same time. The format of the time is
hh:mm:ss in 24 hour format (for example "22:10:37" for 10:10:37pm
local time).
-
<datetime>
-
Replaced with the date and time that the generation was started. Note that the
date/time is retreived once, at the start of generation. This means that all
<datetime>
keywords will be replaced with the exact same date and time. The format of the
date/time is YYYY-MM-DD hh:mm:ss (for example "2004-10-24 22:10:37"). -
<filename>
-
Replaced with the file name of the source file. This is not not the
pathname - i.e. only the actual filename. For example, for the source file
"/usr/dummy/foo.xml", this would return "foo.xml".
-
<file>
-
Replaced with the file name of the source file, minus an extension, if present.
This is not not the pathname - i.e. only the actual filename. For
example, for the source file "/usr/dummy/foo.xml", this would return
"foo".
-
<r>
-
Replaced with the first character of the root element name, after
transformations have been applied.
-
<e>
-
Replaced with the first character of the name of the current element when
iterating through all elements. The first character is taken after all
transormations have been applied. This will generate an error if found while
there isn't an element iteration going on.
-
<a>
-
Replaced with the first character of the name of the current attribute when
iterating through an elements attributes. The first character is taken after
all transormations have been applied. This will generate an error if found
while there isn't an attribute iteration going on.
-
<c>
-
Replaced with the first character of the name of the current child element when
iterating through an elements children. The first character is taken after
all transormations have been applied. This will generate an error if found
while there isn't a child iteration going on.
Conditonals
The following list defines all the currently defined conditionals, as well as
what they mean. Its worth noting that a future release will allow custom
defined conditionals, and these may or may not be predefined.
- firstAttribute
-
Within an attribute iteration, is true only when the current attribute is the
first iterated attribute.
- notFirstAttribute
-
Within an attribute iteration, is true only when the current attribute is not
the first attribute.
- lastAttribute
-
Within an attribute iteration, is true only when the current attribute is the
final iterated attribute.
- notLastAttribute
-
Within an attribute iteration, is true only when the current attribute is not
the final iterated attribute.
- firstChild
-
Within a child iteration, is true when the current child element is the first
child element. Child elements are iterated in alphabetical order.
- notFirstChild
-
Within a child iteration, is true when the current child element is not
the first child element. Child elements are iterated in alphabetical order.
- lastChild
-
Within a child iteration, is true when the current child element is the last
child element. Child elements are iterated in alphabetical order.
- notLastChild
-
Within a child iteration, is true when the current child element is not
the last child element. Child elements are iterated in alphabetical order.
- firstElement or firstRoot
-
Within an element iteration, is true when the current element is the first
element acording to the desired ordering (either tree order or alphabetical
order).
- notFirstElement or notFirstRoot
-
Within an element iteration, is true when the current element is not the
first element acording to the desired ordering (either tree order or alphabetical
order).
- lastElement or lastRoot
-
Within an element iteration, is true when the current element is the last
element acording to the desired ordering (either tree order or alphabetical
order).
- notLastElement or notLastRoot
-
Within an element iteration, is true when the current element is not the
last element acording to the desired ordering (either tree order or alphabetical
order).
- custom
-
Any name specified in a
<condition>
element can be referenced (recursively) as a conditional.
Transformations
- 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
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
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.
<condition>
element
Purpose
Define template specific custom conditionals, used to conditionally include
code generation content.
Format
-
<condition
name
=
"childIsSingle"
op
=
"and"
>
...
</condition>
-
Only
<eval>
elements can be used within a
<condition>
element.
Attributes:
-
name
-
Name used to reference this conditional in the
if
attribute of a
&let;content>
element.
-
op
-
If more than a single
<eval>
element exists directly below the element, then this attribute determines how
the
<eval>'s relate to each other. The
possible values are:
- and
-
All the
<eval>'s must evaluate to true for the
condition to be true.
- or
-
Any one of the
<eval>'s must evaluate to true for the
condition to be true. Evaluation aborts as soon as one evaluates to true.
When only a single
<eval>
exists at the first level within the element's value, then this attribute may
be ommited.
NOTE: Ommiting this attribute when there is more than one
<eval>
will cause an error to be generated.
<config>
element
Purpose
Root element of a configuration file.
Format
-
<config>
...
</config>
-
There aren't any attributes.
The following are valid children:
-
<invalid>
-
<plural>
-
<replacement>
-
<element>
<content>
element
Purpose
Specify the actual code to be generated.
Format
-
<content
type
=
"template"
if
=
"isElement"
>
...
</content>
-
No child elements.
Attributes:
-
type
-
Specifies the location of the content to be included. The only value that is
recognized is template, in which case the value of the element
contains the name of the
<template>
to use.
NOTE: Currently, this is only supported when the element is
contained within a
<file>
element.
-
if
-
The value contains the name of a condition. At the time of generation of this
element, if the condition evaluates to true, then the contents will be
generated. If it evaluates to false, the contents will be ignored.
Any type of conditional can be used: Either a built in or a customized
condition built using the
<condition>
element.
NOTE: Currently, this cannot be used whn the element is
within a
<file>
element.
<element>
element
Purpose
Provide meta information about a specific element type, to allow conditional
code inclusion/exclusion during generation.
Format
-
<element
name
=
"foo"
>
...
</element>
-
Only
<meta>
elements used within a
<element>
elements.
NOTE: More child elements are coming!
Attributes:
-
name
-
The name of the element the that this element contains information about.
<eval>
element
Purpose
Specify opterators and arguments for custom conditional evaluations.
Format
-
<eval
op
=
"equal"
type
=
"boolean"
>
...
<eval>
-
<eval>,
<left>, and
<right>
can be used within an
<eval>
element. There aren't any depth restrictions for recursive
<eval>
elements.
Attributes:
-
op
-
Required, always. This element specifies the operator that will be used to
determine success or failure. The following operators are currently defined:
- childHasMeta
-
During a child iteration, true if the current child has a
<meta>
with the specified
name. The only argument is the value of the
<eval>, and is the
name
of the
<meta>
to look for.
- equal
-
True if the arguments are equal to each other. The arguments are
specified via
<left>
and
<right>
child elements.
The
type
attribute is required for this operator.
- hasMeta
-
During an element iteration, true if the current element has a
<meta>
with the specified
name. The only argument is the value of the
<eval>, and is the
name
of the
<meta>
to look for.
- not
-
After evaluating the child
<eval>'s (which are required) inverts
the logical result. If the children evaluate to true then this evaluates
to false, and if the children evaluated to false, then this
evaluates to true.
- isAttribute
-
No arguments. Evaulates to true if being generated during an attribute
iteration.
- isChild
-
No arguments. Evaulates to true if being generated during a child
iteration.
- isElement
-
No arguments. Evaulates to true if being generated during an element
iteration.
- custom
-
name
of
<condition>
elements are valid as operators as well.
NOTE: More operators will be added as desired. If you want
one, please let us know so it can be added (note that lack of "need"
there...)
-
type
-
Specifies how to interpret the arguments. Currently only used with equal
operator. The following types are supported:
- boolean
-
Both arguments will be interpreted as boolean's. True can be any of
"true" (case insensitive), "yes" (case insensitive), or a
non-zero integer. False can be any of "false" (case
insensitive), "no" (case insensitive), or an integer of 0 (zero).
NOTE: More types will be added as desired. If you want one,
please let us know so it can be added (note that lack of "need"
there...)
<file>
element
Purpose
The root source of code generation. Without this, nothing gets generated
because it has no where to go. There is no limit to the number of files.
Format
-
<file
name
=
"<file>/<root-c>.hpp"
>
...
</file>
-
Only
<content>
elements used within a
<file>
elements.
Attributes:
-
<name>
-
Specifies the path and filename of the file. All standard transformations are
valid.
Both platform specific and POSIX path's can be used. For POSIX, the defination
of / is platform dependant.
<generator>
element
Purpose
Root element of templates.
Format
-
<generator>
...
</generator>
-
There aren't any attributes.
The following are valid children:
-
<file>
-
<invalid>
-
<plural>
-
<replacement>
-
<template>
<invalid>
element
Purpose
The
<invalid>
element is used to provide a list of invalid characters for the v and V
keyword transformations.
Format
-
<invalid
string
=
"-"
>
_
</invalid>
-
The value is the replacement string. There isn't a limit on the size of the
replacement string.
No child elements supported.
Valid in
<config>
and
<generator>
elements.
Attributes:
-
string
-
The character that will be replaced.
NOTE: Contrary to what the name of this attribute suggests,
it only supports a single character.
<left>
and
<right>
elements
Purpose
Provide arguments to
<eval>
elements.
Format
-
<left
type
=
"childMeta"
>
single
</left>
-
The value is either the actual value for the argument, or clarification of the
type
attribute.
No child elements supported.
Attributes:
-
type
-
Specifies the type of argument, if needed. Not all operators need these. The
following values are valid:
- meta
-
Retreives the value of the
<meta>
of the current element, with the
name
specified as the value of the element. Valid within element iterations only.
- childMeta
-
Retreives the value of the
<meta>
of the current child, with the
name
specified as the value of the element. Valid within child iterations only.
<meta>
element
Purpose
Associate custom meta data to an element.
Format
-
<meta
name
=
"value"
>
true
</meta>
-
Used within
<element> elements only.
Attributes:
-
name
-
Specifies the name of the meta data.
<plural>
element
Purpose
Provide specific pluralization replacement for internal pluralize logic.
Format
-
<plural
string
=
"child"
>
children
</plural>
-
The value is the replacement string.
No child elements supported.
Valid in
<config>
and
<generator>
elements.
Attributes:
-
string
-
The string that will be replaced during a pluralization transformation.
<replacement>
element
Purpose
Provide specific replacements for words encountered as part of elements and
attributes.
Format
-
<replacement
string
=
"class"
>
Class
</replacement>
-
The value is the replacement string.
No child elements supported.
Valid in
<config>
and
<generator>
elements.
Attributes:
-
string
-
The string that will be replaced during a validate transformation.
*******************************************************************************
-->
<template>
element
Purpose
Provide specific pluralization replacement for internal pluralize logic.
Format
-
<template
name
=
"header start"
type
=
"attributes"
order
=
"alpha"
>
...
</template>
-
Only
<content>
elements can be used within a
<template>
element.
Attributes:
-
name
-
The
name
attribute is required, and is the name that is used as a value of a
<content>
element that contains a
type
attribute of "template".
-
type
-
Required, and it can have any of the following values:
- attributes
-
Template will be generated during an attribute iteration for the current
element.
- elements
-
Template will be generated during an element iteration.
- children
-
Template will be generated during an child iteration for the current element.
- inline
-
Template will be generated without iteration whenever referenced.
-
order
-
Required for element iterations only (i.e. when
type
is "elements"). The following values are valid:
- alpha
-
Elements will be iterated in collated order (normally this means alphabetical,
but on non-ascii systems that is not always the case).
- tree
-
Elements will be iterated in order of the dependancy on each other, such that
the least dependant elements will be first, and the elements that include the
most levels of child elements last.
This is useful for generating source code for a language that needs the
dependant types declared first. For example, the default template
("xcgtempl.xml") iterates elements in this order for generating the
header, but in alpha order for implementation files. This attribute is
ignored for all other cases.