Reference for "templates.

xml" and its scripting features

Structures
Structures consist of elements. An element can reference another structure or defne
one of various basic data types.
Structures and element have an id that is used to reference them. The optional label
is what appears as their name in the UI.
Elements may only appear inside a structure or a select.
Elements have an optional count attribute which specifes a repetition of the
element, creating a sequence. Valid values are:
number A discrete number for a specifc repetition count
* The asterisk means that the repetition ends only with a zero-length
element or at the end of the block or the element's max size
$id Use a $ to reference another element which contains the number of
repetitions
script Script code
Elements have an optional link attribute for acting as a clickable reference to another
block. The only valid value for this attribute is currently "*".
"struct" elements have an optional size attribute which specifes the maximum size in
bytes of the element. The attribute value is either a number, a value from another
element which is identifed by its id prefxed with $, or a number prefxed with % to
end the element at a block ofset that is equal to the next multiple of the given
number. There is also a maxsize optional attribute which applies to elems in
sequences. To specify the size of the various string types, count must be used
instead.
The available data types for elements are:
int Optional prefx with u or s for (un)signed, postfx with 8, 16, 24, 32,
48 or 64 for bit size, optional postfx with le or be for endianness
byte Same as uint8
double A 64 bit foating point number (in common IEEE/CPU format)
varint64 Variable length 64 bit int, 1-9 bytes (Hufman encoding, see sqlite3
format spec)
char A single-byte character, or a range of byte chars when using the
count attribute
string Same as char
dstring A UDF-type dstring, not useful anywhere else
pstring A string of single-byte chars, with the frst byte specifying the number
of following chars
p2string A string of single-byte chars, with the frst two bytes specifying the
number of following chars
cstring A zero-terminated string of single-byte chars. Ends after the 00 byte
if count is not specifed
UTF8 A unicode string, with optional le or be at end of name to specify
endianness
UTF16 A unicode string, with optional le or be at end of name to specify
endianness
skip Skips the number of bytes specifed in the count attribute
struct Use the attribute ref to name the id of a struct that this element
represents
select Use the attribute ref to name the id of a select declaration for a
conditional element
The optional view attribute can be used to change the way their value is shown:
dec Show a decimal value (with int types only)
hex Show a hexadecimal value (with int types only)
format=name The name references the id of a view-formatter.
collapsed collapse the structure
expanded expand the structure
To show custom values for an element, declare a view-formatter XML element.
Script Function Reference (origin: source code module
Templates.TmplScriptContext )
Note: See "Script Methods Reference.txt" for a complete list of methods and their
types
ElemInt (element-name) : Int64
ElemOfs (element-name) : Int32
ElemSize (element-name) : Int32
ElemStr (element-name) : String
Data_int8 (ofset) : Int32
Data_uint8 (ofset) : Int32
Data_intsizebe (ofset) : Int64
Data_uintsizebe (ofset) : Int64
Data_intsizele (ofset) : Int64
Data_uintsizele (ofset) : Int64
size: 16, 32, 64
Data_int8 (ofset, scope) : Int32
Data_uint8 (ofset, scope) : Int32
Data_intsizebe (ofset, scope) : Int64
Data_uintsizebe (ofset, scope) : Int64
Data_intsizele (ofset, scope) : Int64
Data_uintsizele (ofset, scope) : Int64
scope: 0: within structure, -1: within template, -2: within block, 1: within parent
structure
DebugLog (msg as String)
Outputs text to the system console (use Console.app on OSX or DebugView on
Windows to see it) for trace & debugging purposes.
Script Programming
The script syntax is based on RbScript from REAL Software's REALbasic language.
It is described here: http://docs.realsoftware.com/index.php/RBScript
When writing code, a few rules must be observed:
If using <code> with the "type" attribute like "-expr", all code for the expression
must be in a single line. It's not possible to split the line into several, not even by
using the "_" continuation character. This is because the script code will be modifed
by prepending code such as "result = " to the script's last line, and this wouldn't work
if the expression isn't all in one line. As a work-around, you can use the "-function"
type instead, where no such line modifcation takes place.
The "<" and "&" can not be written in the code directly, because the surrounding xml
syntax does not allow this. Instead, a "<" must be written as "&gt;" and a "&" as
"&amp;". Or use <![CDATA[ ... ]]>
Macros
Currently, argument replacing only takes place inside <code></code> inside a
macro.
Debugging scripts
There hasn't been put much efort into making debugging easier without access to
the source code. I, the author, usually run the program in REAL Studio's debugger so
that I can gather all necessary information.
However, there is one function that can be used to see what's happening inside a
script function: DebugLog (see function reference). Its output currently ends up as
console output on OSX (use "Console.app") and Linux, and as debugging output
under Windows (use "DebugView")
Fixing errors in Templates and Script code
Remember to alter the templates fle in small steps, as it's easy to make mistakes,
and fnding the cause of the error is often as not easy as one might like.
Avoid using the <code type="global"> tag, instead prefer macros, because the
global code gets prepended to every script, which has two disadvantages:
1. Each script takes longer to prepare (compile).
2. For any Elem functions in the code there will be an attempt to convert them
into Data_ function calls with fxed ofsets as this makes execution faster. This
attempt is made even if the code won't be executed. Therefore, avoid having Elem
calls in global code as it might create warnings about "elem not found".
To see if a modifcation was successful, launch iBored and wait for it to load the
templates completely. The templates are loaded in the background and it can take 10
to 20 seconds easily. Hence, to see when all is loaded, open any item in the disks
window (drop a fle with at least 512 in size into it if there are no items listed) in order
to open the block viewer, which will then wait for the templates loading to fnish.
Should you get any error message displayed before the block viewer shows the data,
there's likely an error in the templates fle.
Besically, there are two types of static errors to be made:
1. XML formatting errors
2. RbScript coding errors
If it's an XML error, you'll probably see a message like this:
Parse error in templates.xml (XML Error), line 0
msg: XML parser error N: ...
In this case, disregard the given line number - it's useless in most cases. To fnd the
error, either track back your changes or use a XML validator (google it) to have it
check the templates fle. It should be able tell you where and what is wrong, exactly.
If it's a RbScript error, it'll look like this:
Parse error in templates.xml (RbScript Error), line X
Compile error N:

At Node:
The line number X is close to the line of the error, not precise in all cases, though.
Often, the given line number is where the XML node ends which contains the code.
The error number N refers to RbScript errors as in this document:
http://docs.realsoftware.com/index.php/RBScript#Error_Codes
Then the 2 lines in which the error should be found are listed.
Finally, the XML node is shown that contains the problematic code.
Containers (Context)
<child-context> can create a new container even without <new-container>: If <new-
container> is missing, the properties "startBlk" and "blkCount" must be set, which
then create a new container that uses the same container as the parent context, but
limited to the given block range. This is useful in order to use the same block
numbers as the parent uses.
If <new-container> is used, a property named after the attribute "extentsProp" must
be set, containing the parent context's extent(s) that form the new container.
Optionally, a new blockSize for the container can be specifed via a property named
by the attribute "blkSizeProp".
Properties are usually only shared within one <context> clause. To make them
accessible to child contexts, <copy-property> must be used.