Edit Anything

Professional text and hex editing
with Binary Templates technology.






010 Editor - Text/Hex Editor Homepage

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:

    char     header[4];
    int      numRecords;

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. See Data Types for a list of allowed types. Variables can also be edited using Scripts (see Editing Variables with Scripts). Variables which behave as regular C variables can be declared using the local keyword as discussed below. The main way of grouping Template variables together is to declare structs or unions and see the Structs and Unions help topic for more information.


Special Attributes

One or more special attributes can be specified after a variable inside '<' and '>' brackets. The following attributes are supported:

   < format=hex|decimal|octal|binary,
     fgcolor=<color>|<function>|(<expression>),
     bgcolor=<color>|<function>|(<expression>),
     comment="<string>"|<function>|(<expression>),
     name="<string>"|<function>|(<expression>),
     open=true|false|suppress,
     hidden=true|false,
     read=<function>|(<expression>),
     write=<function>|(<expression>),
     size=<number>|<function>|(<expression>),
     optimize=true|false,
     disasm=<constant>|<function>|(<expression>) >

Special Attributes that can use <function> or (<expression>) statements are discussed in the Attribute Functions and Inline Expressions section and note (<expression>) is only available in 010 Editor version 12.0 or higher and <function> had extra limitations before version 12.0. All attributes are discussed below except for the read and write attributes (used to create Custom Variables), the size attribute (used to create On-Demand Structures), the optimize attribute (used with Optimized Arrays) and the disasm attribute (used for Disassembly in Templates).


Attribute Functions and Inline Expressions

Some special attributes as listed above can specify a custom function or expression. One method to do this is to specify just the function name in the attribute. For example:

    typedef byte MySize <comment=SizeCommentFunc>;

Then the function should be defined in the Template after the typedef or variable is defined. The first argument for the function is a reference to the variable defined with '&'. Only the write function takes a second argument which is a string. The return type depends upon the type of attribute being defined and the following is an example of a comment function that returns a string:

    string SizeCommentFunc( MySize &s )
    {
        if( s < 0 )
            return "Negative sizes not allowed.";
        else
            return "";
    }

Starting in 010 Editor version 12.0, inline functions can be written, meaning the code can be specified directly inside the '<' and '>' brackets without having to write a separate function. There are two ways to do this. First, a function can be called for the attribute and arguments can be passed to the function using '(' and ')' but the arguments can be any expression. For example:

    typedef float Vec3f[3] <read=Str("<%g %g %g>",this[0],this[1],this[2])>;
    Vec3f v1;

The keyword this is used to access the current variable inside the expression and note that this[0], this[1], etc. can be used if the variable is an array. The second way to write an inline function is to write an expression enclosed inside brackets '(' and ')'. For example to specify a red background color if an int64 is negative use:

    int64 c1 <bgcolor=(this < 0 ? cRed : cNone )>;

More examples are available in the Inline Read and Write Functions section.


Display Format

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 id;
    int crc <format=hex>;
    int flags <format=binary>;

Colors

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 multiple 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 example:

     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.

Starting in version 12.0 of 010 Editor, a function or expression can also be specified for a foreground or background color. Custom color functions should return an integer and see the Attribute Functions and Inline Expressions section for information on writing custom functions. For example to color negative integers red use:

    typedef int64 ColorInt <bgcolor=BgColorInt>;
    int64 BgColorInt( ColorInt &var )
    {
        if( var < 0 )
            return cRed;
        else
            return cNone;
    }
    ColorInt c1;

This can also be accomplished using an inline expression inside brackets '(' and ')' and the this keyword:

    int64 c1 <bgcolor=(this < 0 ? cRed : cNone )>;

When applying colors to an array, usually the whole array is colored the same color unless the array is defined as a Duplicate Array.


Endian

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. Using this technique, the same file can contain both little and big endian data.


Comments

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>>'. 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";
        else
            return "Valid machine status";
    }

When using comment functions with a struct, the comment function receives a reference to the struct. The '&' symbol should be used when declaring the first parameter. For example:

    typedef struct { 
        int version; 
        //...
    } RECORD <comment=RecordComment>;
    
    string RecordComment( RECORD &r )
    {
        if( r.version < 10 )
            return "Old version record";
        return "";
    }
    
    RECORD rec;

Starting in 010 Editor version 12.0, comment functions can be declared inline and see Attribute Functions and Inline Expressions for more information. 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. 010 Editor version 12.0 or higher is required for comment expressions.


Names

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>>'. A name function is similar to a comment function and takes as arguments a variable and returns a string. See the Attribute Functions and Inline Expressions section for information on writing custom functions or expressions. 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.


Order

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).


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.


Hidden Variables

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.


Local Variables

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;

    int    recordCounts[5];
    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.


This is the manual for 010 Editor, a professional hex editor and text editor. Use 010 Editor to edit the individual bytes of any binary file, hard drive, or process on your machine. 010 Editor contains a whole host of powerful analysis and editing tools, plus Binary Templates technology that allows any binary format to be understood.





Newsletter - Receive special offers, tips, tricks and news. Join now



010 Editor v12.0.1 is here!
What's new?


Navigation


Products

010 Editor














E-mail: info@sweetscape.com