To Translate an xml Parse Tree

TranslateTree()

The main script you need to use is TranslateTree(). The simplest form is as follows:

result = xmltr.TranslateTree(adrXmlTbl, adrTransTbl)

Here it takes two parameters: (i) an address of an xml parse tree produced by the blox parser; and (ii) an address of a translation rule table.

The return value is the result of the translation.

The second parameter can also be a list of addresses of translation tables. In this case, each translation table will be searched in turn to find the translation rule which matches a particular tag pattern. The first translation table in the list is the first one searched, and so on. Wildcard or default translation rules in any translation table will take precedence over translation rules (of any kind) in subsequent translation tables.

TranslateTree() also takes some optional parameters as follows:

result = xmltr.TranslateTree(adrXmlTbl, adrTransTbl,
   userData=nil, adrFindScript=nil,
   adrRuleScript=nil, adrDefaultRule=nil,
   adrRuleCache=nil, translateRoot=false)

The optional parameters are:

	userData: Data you provide which might be required by translation scripts (for example some context information about your web site tables). You can retrieve this with GetUserData() (see below).
	adrFindScript: The address of a script which will be used instead of the built-in FindRule() script (described below).
	adrRuleScript: The address of a script which will be used instead of the built-in ProcessRule() script (described below).
	adrDefaultRule: The address of a “catch all” translation rule (script, string, outline or wpText) which will be used if no matching translation rule is found in any of the supplied translation rule tables.
	adrRuleCache: The address of a Frontier table which will be used for caching the addresses of matched translation rules. If you supply a table address and preserve the table between calls to TranslateTree(), then the time consuming search for translation rules will occur only once (hence saving time when doing multiple translations using the same translation rules). In this case, whenever you make a change to your translation rule table/s, empty the rule cache table to force it to be rebuilt on the next call to TranslateTree().
	translateRoot: By default, xmltr translates only the child nodes of the supplied xml parse tree. If you need to translate only a fragment of an xml parse tree, you can set this parameter to true which will cause TranslateTree() to translate the root node (of the fragment) rather than just the child nodes.

To Define a Script Translation Rule

Script translation rules have the following calling convention:

result = scriptRuleName(adrXmlNode, nodeData)

A translation rule script takes two parameters: (i) the address of the xml node (in the xml parse tree) currently being translated; and (ii) a reference to context data used by the translation machinery.

You can use the first parameter in conjunction with blox scripts, such as blox.GetAttribute() which will return the value of a named attribute of the xml node (i.e. an attribute associated with the corresponding xml tag pair in the source document).

The second parameter is passed through to scripts such as TranslateChildren() and is used to convey state information required in the translation process. It is also where the userData parameter to TranslateTree() is stored.

Utility Scripts Which Return Context Information

GetUserData()

Within a translation rule script you can retrieve the userData parameter supplied to TranslateTree() using the script GetUserData():

userData = xmltr.GetUserData(nodeData)

GetTagDepth()

Within a translation rule script you can get the nesting level of xml tags (or parse tree nodes) for the current node being translated using the script GetTagDepth().

depth = xmltr.GetTagDepth(nodeData, tagName="")

If tagName is omitted, then the all containing tags (including the current tag) are counted. For example, if the current tag context was <page><section><title> then this script would return 3 (numeric).

If tagName is specified, then only tags of that name are counted (other intermediate tags are not counted). For example, if the current tag context was <item><anotheritem><item> and tagName is specified as “item” then this script would return 2 (numeric).

Utility Scripts for Translating Child Nodes

TranslateChildren()

result = xmltr.TranslateChildren(adrXmlNode, nodeData)

This script translates all the child nodes of the current xml parse tree node. adrXmlNode and nodeData are the two parameters which need to be passed to script translation rules. You will need to use TranslateChildren() within translation rule scripts to translate the “content” of a node (to which you then typically apply HTML formatting).

TranslateChild()

result = xmltr.TranslateChild(adrXmlNode, nodeData, childName, ix=1)

This script translates a single child node of the current xml parse tree node. adrXmlNode and nodeData are the two parameters which need to be passed to script translation rules. childName is the name of the child node to be translated. ix is the index of that child node when there is more than one child node with the nominated name (defaults to one).

This script can be used within translation rule scripts to translate the content of single child nodes.

TranslateSomeChildren()

childTable = xmltr.TranslateSomeChildren(adrXmlNode, nodeData,
   select={}, exclude={})

This script works like TranslateChildren() except that it translates only some of the child nodes. The optional parameter select (which should be a list of strings) defines the names of the child nodes which should be translated. The optional parameter exclude (also a list of strings) defines the names of the child nodes which should not be translated (names in this list override names in the select list).

If you don’t specify the parameters select or exclude, then TranslateSomeChildren() behaves exactly the same as TranslateChildren().

The script can be useful for “filtering” the content of an xml node.

CollectChildren()

childTable = xmltr.CollectChildren(adrXmlNode,
   nodeData, nameList)

This script works like TranslateChildren() except that it translates only the child nodes whose names (i.e. the xml tag names) are included in nameList (which should be a list of strings). The result is returned as a table (not a table address, an actual table object) in which each entry is the translated content of a child node. The entries in the table are named according to the child node names (i.e. the xml tag names).

This script can be useful for marshalling the translated content of the nominated child nodes prior to re-assembling in a particular order for presentation, which may be different from the order in which the content appeared in the xml source file.

CollectSimilarChildren()

childList = xmltr.CollectSimilarChildren(adrXmlNode,
   nodeData, childName)

Continuing in the same vein, this script marshals the translated content of child nodes which share the same name (tag name), childName. The translated content is marshalled into a Frontier list (typically of strings, but dependent on the downstream translation rules).

Defining a Default Translation Rule

_default()

Place a translation rule with this name at any level of the translation table and it will be selected if no exact match or wildcard rule can be found for a given tag pattern. Most commonly you would place such a rule at the topmost level of the translation rule table, or in a separate translation table which is searched last, as a “catch all” translation rule.

This could be useful, for example, if you wanted to ignore the content between any xml tags which did not have specific translation rules. In this case you would define a “_default” translation rule as an empty string.

If the “_default” translation rule is a script rule, its calling syntax as for other script translation rules is:

result = _default(adrXmlNode, nodeData)

Defining “sameas” Rules

rulename	sameas:<tag pattern>

You use a string, outline or wpText object to define a “sameas” translation rule. In this case, the tag pattern (including angle brackets such as <page><title>) which appears after the string “sameas:” will be used to locate the actual translation rule.

When locating the translation rule for the specified tag pattern, the same pattern matching machinery is used as for normal translation rules. Hence the tag pattern appearing after “sameas:” can match a specific translation rule, a wildcard rule or a default rule in any of the supplied list of translation tables.

Translation of Entities

Xmltr provides a default translation for xml entities, which just preserves the xml syntax of ampersand followed by entity name followed by semicolon.

If you want to override this translation, you can provide an entry at the topmost level of the translation rule table named “_entity”. This entry can be either an entity mapping table or a script.

Each entry within an entity mapping table defines the mapping for a particular entity. The name of the entry is the name of the entity (minus the ampersand and semicolon notation) and the value of the entry is the mapping for that entity — for example a string (or outline or wpText) value. Entries can also be scripts, in which case the mapping is the return value of the script (which of course gives more flexibility to do arbitrary computations). In this case, the script takes one parameter, the name of the entity:

entityValue = entityName(entityName)

When you define entity mappings in a table this way, you can have a separate entity mapping table for each translation rule table (indeed some translation rule tables may contain an “_entity” sub table and nothing else). In this case each translation rule table will be searched to find a mapping for the entity. Only if no mapping is found, will the default entity translation be performed.

If the “_entity” entry at the topmost level of a translation table is a script, then this script will be called to translate each entity that is encountered in the xml parse tree.

entityValue = _entity(entityName)

In this case the first translation rule table which contains an “_entity” entry which is a script will stop the search of further translation rule tables.

If you want to use the default translation for any cases you don’t handle, call the built-in script TranslateEntityDefault() (described next).

TranslateEntityDefault()

entityValue = xmltr.TranslateEntityDefault(entityName)

This script provides the built-in default translation for entities (which just preserves the xml entity notation of ampersand, followed by entityname followed by semicolon).

Providing Override Scripts for Processing

FindRule()

adrRule = _FindRule(nodeData, adrTransTbl)

You can provide your own script for finding translation rules for particular tag patterns. This script will be used instead of the built-in FindRule() script (you’ll need to peruse the source of FindRule() to understand exactly how it works).

Provide your replacement script as an optional parameter, adrFindScript, to TranslateTree().

Typically your script might call the built-in FindRule() script and then do some additional processing.

_ProcessRule()

result = ProcessRule(adrXmlNode, adrRule, nodeData)

You can provide your own script for processing translation rules. This script will be used instead of the built-in ProcessRule() script.

Provide your replacement script as an optional parameter, adrRuleScript, to TranslateTree().

Overriding the built-in ProcessRule() script could be useful if you want to implement your own special format for rules in the translation rule table. (For example you might want to invent a shorthand way of specifying translation rules. Your custom ProcessRule() script would know how to recognise and process this format.).

Website built using Frontier and xmltr. Documentation also available in pdf format for offline reading. Copyright The Design Group Qld 2000. This page last updated Thu, 23 Aug 2001