Declaring variables in templates is performed similar to ANSI C and Scripts, but with an important difference: every time a variable is declared in the Template, that variable is mapped to a set of bytes in a file. For example, running the template:
Would create the character array header, which is mapped to the first 4 bytes of the current file, and the integer numRecords, which is mapped to the next 4 bytes of the file. Both variables will be displayed in the Template Results panel and can be used for editing the file. Variables can also be edited using Scripts (see Editing with Scripts).
The main way of grouping Template variables together is to declare structs or unions. See the Structs and Unions help topic for more information.
One or more special attributes can be specified after a variable inside '<' and '>' brackets. The
following attributes are supported:
All attributes are discussed below except for the read and write attributes which can be used to create special Custom Variables (see Custom Variables) and the size attribute which can be used to create on-demand structures (see On-Demand Structures).
By default, all variables declared will be displayed in the Template Results panel in decimal format. To switch between hexadecimal, decimal, octal, or binary display formats, see the functions DisplayFormatDecimal, DisplayFormatHex, DisplayFormatBinary, and DisplayFormatOctal in Interface Functions.
An alternate way of specifying the format for a variable is to use the syntax '<format=hex|decimal|octal|binary>' after a variable declaration or a typedef. For example:
int crc <format=hex>;
int flags <format=binary>;
When parsing a file, different colors can be applied to variables by using a
Template. For example, the header bytes of a file could be colored differently
than the rest of the file. There are two ways to control the color of
variables. If you just wish to set the color of a single variable, the syntax
'<fgcolor=???>' or '<bgcolor=???>' can be used
after a variable to set the foreground or background color respectively. Here '???' can indicate either
a built-in color constant (see SetBackColor for a list)
or a number constant in the format '0xBBGGRR' (e.g. 0xFF0000 is blue). For
int id <fgcolor=cBlack, bgcolor=0x0000FF>;
The second way of coloring variables is to use the SetForeColor, SetBackColor, or
SetColor functions to set the default color. Every variable defined after a call
to one of these functions will be assigned the default color. The special
color constant 'cNone' can be used to turn off coloring. For example:
SetForeColor( cRed );
int first; // will be colored red
int second; // will be colored red
SetForeColor( cNone );
int third; // will not be colored
See the SetBackColor function
for more information. When using a dark Theme, background colors are automatically darkened to fit in better with the theme and this can be controlled using the ThemeAutoScaleColors function. Note that the fgcolor and bgcolor syntax requires 010 Editor version 3.1 or higher.
Any data written or read from a file depends upon the endian of the file (see Introduction to Byte Ordering). By default, all variables declared will have the same endian as the file, but the endian can be modified by using the functions BigEndian or LittleEndian (see I/O Functions). Using this technique, the same file can contain both little and big endian data.
A comment can be attached to a variable using the syntax '<comment="<string>">'. For example:
int machineStatus <comment="This should be greater than 15.">;
This comment will be displayed in the Comment column of the Template Results. Alternately, a comment can be provided using a custom function using the syntax '<comment=<function_name>>'. The comment function takes as arguments a variable and returns a string to be displayed in the Comment column. For example:
int machineStatus <comment=MachineStatusComment>;
string MachineStatusComment( int status )
if( status <= 15 )
return "*** Invalid machine status";
return "Valid machine status";
Note that extended characters can be included in string constants when a Template file uses the UTF-8 character set. Comments with strings are only available in version 3.1 of 010 Editor or higher and comments with custom functions are only available in version 4.0 of 010 Editor or higher.
The name attribute can be used to override the text displayed in the Name column of the Template Results. Similar to the comment attribute above, the name attribute can be given a string with the syntax '<name="<string>">' or can be given a function with the syntax '<name=<function_name>>'. A name function is similar to a comment function and takes as arguments a variable and returns a string. The following is an example of using the name attribute with a string:
byte _si8 <name="Signed Byte">;
The above statement would display "Signed Byte" in the Name column of the Template Results instead of the string "byte _si8". Note that if the variable is part of an array, the array indices will be automatically appended to the name. The name attribute is only available in version 4.0 of 010 Editor or higher.
After each Template variable is declared, the current file position is moved forward. The current file position can be examined using the function FTell. By using the functions FSeek or FSkip, the current position can be moved around the file. This technique allows a file to be parsed out of order. Note that to read from a file without defining a variable, the functions ReadByte, ReadShort, ReadInt, etc. can be used (see I/O Functions).
In some instances, a variable may be required which is not mapped to a file and not displayed in the Template Results (i.e. a regular C/C++ variable). In this case, the special keyword 'local' can be used before the declaration. For example:
local int i, total = 0;
for( i = 0; i < 5; i++ )
total += recordCounts[i];
double records[ total ];
In this example, i and total are not added to the Template Results panel by default; however, the display of local variables in the Template Results panel can be enabled by right-clicking on the Template Results panel and clicking Show Local Variables.
Open Status of Variables
When a Template is run, all the created variables are displayed in
a tree format in the Template Results.
By default all arrays and structs will be closed in the tree and can be
opened by clicking the small '+' or arrow beside each item; however, sometimes
it is useful to have an array or struct open by default which makes viewing
important data easier. To open an array or struct by default use the
syntax '<open=true>' after a variable. The syntax '<open=false>'
can also be used to set an array or struct closed after the template is
run (this is the default behavior).
When the Expand All Children of Node operation is run on the Template Results tree (this is performed by right-clicking on the Template Results), all arrays or structs under the selected variable are opened. Alternately, all nodes in the Template Results can be recursively opened by right-clicking on the tree and selecting Expand All Nodes. To prevent an array or struct from being opened during an Expand All operation, use the syntax '<open=suppress>' after the variable. Controlling the open status of variables is only available in version 3.1 of 010 Editor or higher.
Null-terminated strings are commonly defined in binary files. 010 Editor allows the special syntax in a template to read a null-terminated string:
will both read a string until a 0 byte is encountered. Unicode strings (wide strings) can
be read using:
See Arrays and Strings for more information on strings.
Enums are useful when writing Templates (see Data Types, Typedefs, and Enums for information on declaring enum types). When an enum variable is declared and the variable is selected in the Template Results, a down arrow will appear to the right of the text field. Clicking on the down arrow displays a drop-down list of all constants defined for the enum. Selecting an item from the drop-down list, or entering a constant in the edit field and pressing Enter will assign the variable to a new value. Enums may also be used with bitfields.
The syntax '<hidden=true>' can be used to hide the display
of variables in the Template Results. This
syntax can also be used with typedefs and '<hidden=false>' can
be used to re-enable the display of a variable. Hidden variables are only
available in version 3.1 of 010 Editor or higher.