BARfly Help

BARfly Help - Node editing - Editing data - Dump view

Editing - Dump view

This page describes content of the BARfly Silver and BARfly Gold builds.

Editing in dump view might seem daunting at first, but dump view is by far the most powerful tool you have to edit binary data. You can perform sophisticated modifications to node data, and in a very quick fashion.

When data are dumped, the edit control in the data display view is populated with the node data. You can edit the data just like you would in a plain-text editor. You can also copy, cut, and paste, just like in a plain-text editor.

BARfly dumps data in either UTD or XML format. Although there are significant differences in the syntax of these two formats, the general philosophy that BARfly uses to dump node data is the same for both formats. In the following sections, it is discussed how BARfly arranges dumped data, as well as how each dumped format handles this data.

US ::= [#x0-#x20] | ',' | ';'
XS ::= [#x0-#x20]

It is important to note that the two formats have a different concept of what constitutes "whitespace." Whitespace, or separator characters that are often optional and only serve to separate meaningful tokens, is all characters from ASCII 0 to ASCII 32 (the space character) for both formats. This range includes tabs and line breaks. However, UTD also includes two additional characters in its definition of whitespace: the comma and the semicolon characters.

Dumped Data Structures

Data structures are dumped with the name of the structure type identified at the beginning, and the individual member assignments contained within a delimited subsection.

UTD Structure ::= ((Structure Type Declarator) US)? (Structure Name) US? ('= ' US?)? '{' US? (UTD Structure Content) US? '}'
XML Structure ::= '<' (Structure Name) XS? '>' XS? (XML Structure Content) XS? '</' (Structure Name) XS? '>'
Structure Type Declarator ::= struct | class

A UTD structure begins with an optional construct type declarator ("struct" or "class") and a required structure name (defined by the I.F), with the content enclosed by curly braces. An XML structure begins with an XML open tag with no attributes, and ends with an XML close tag. The XML tag has the same name as the structure name defined by the I.F.

UTD Examples

XML Examples

The content of the structures has several different syntaxes for both formats. For UTD, there are two ways of identifying data: assignment statements, and sequential members. For XML, there are three ways of identifying data: assignment statements using tags, assignment statements using attributes, and sequential members.

UTD Structure Content ::= ((UTD Assignment Statement) US)* | ((UTD Sequential Member) US)*
XML Structure Content ::= ((XML Tag Assignment Statement) XS)* | ((XML Attribute Assignment Statement) XS)* | ((XML Sequential Member) XS)*

If a structure is derived-from-simple, there will be only one unit of data, and a sequential member must be used (assignment statements are inapplicable).

For all other types of structures, either assignment statements or sequential members can be used to characterize the individual variables.

Sequential Members

The "sequential members" method of assigning variables is the simplest way to assign variables. The order the variables appear in the structure declaration in the I.F. determines the order they appear in the dumped data. The following table shows what a sequential member dump looks like.

UTD Examples

XML Examples

UTD Sequential Member ::= (UTD Value)
XML Sequential Member ::= (XML Value) | (XML Tag Assignment Statement)

If there are more members in the dumped content than there are variables in the actual structure type, BARfly generates an error.

If there are fewer members in the dumped content than there are variables in the actual structure type, BARfly assigns default values for the non-appearing members. Theoretically, you could leave the structure content completely empty, which causes BARfly to assign default values to every member of the structure.

BARfly allows XML tag assignment statements when sequential members are expected only in one circumstance: when the field to be assigned is more complex than what can be represented by just a single value, not enclosed by any tag. This is because substructures and arrays naturally require some sort of enclosure for their sub-members, and there is no straightforward way to perform this task in XML other than to introduce a sub-element tag. Of course, this assignment statement must still occur in the natural order of variable declaration for the structure.

Assignment Statements

The "assignment statements" method of assigning variables is not as straightforward as the "sequential members" method, but it makes up for it by offering the user a great deal of additional flexibility. Assignment statements do not need to appear in the same order the variables appear in the structure declaration. The following table shows what assignment statements look like when dumped.

UTD Examples

XML Examples

UTD Assignment Statement ::= (Variable Name) US? '=' US? (UTD Value)
XML Tag Assignment Statement ::= '<' (Variable Name) XS? '>' (XML Variable Values) '</' (Variable Name) XS? '>'
XML Attribute Assignment Statement ::= '<' (Variable Name) XS 'val' XS? '=' XS? (([#x22] (XML Scalar Value) [#x22]) | ([#x27] (XML Scalar Value) [#x27])) XS? '/' XS? '>'

When BARfly generates assignment statements, it uses the natural order of structure variables. However, you can re-enter the assignment statements in any order, not necessarily the natural order of declaration. If you do not enter an assignment statement for a variable, BARfly assigns default values for the non-appearing member.

UTD assignment statements begin with the variable name, have an equals symbol next, followed by the assigned value.

XML assignment statements are a bit more complicated. An assignment statement begins with an XML tag bearing the name of the variable, but whether it is an empty tag or an open-and-close tag pair depends on whether it is a "tag" assignment or an "attribute" assignment.

An XML tag assignment statement is composed of an open tag and a close tag, with no attributes. The space between the open tag and close tag is reserved for the variable value. Depending on the complexity of the variable, it could be a single number, or it could be mixed content with many sub-elements.

An XML attribute assignment statement is composed of an empty tag with one attribute. This attribute, named "val," is followed by an equals sign, which is followed by a quoted quantity indicating the variable value. An attribute assignment statement is only capable of assigning a single scalar quantity; you cannot assign arrays or whole substructures with attribute assignments.

Value Syntax

BARfly has a unique value-interpretation system for both UTD values and XML values assigned to structure variables. The UTD assigned-value syntax is consistent with subnode value-entry parsing rules, while the XML assigned-value syntax is consistent with XML parsing rules.

UTD Value ::= (UTD 1-D Array Values) | (UTD 2-D Array Values) | (Scalar Value) | (String) | (UTD Substructure Values)
UTD 2-D Array Values ::= '{' US? (((UTD 1-D Array Values) | (String))) US)* '}'
UTD 1-D Array Values ::= '{' US? (((Scalar Value) | (String) | (UTD Substructure Values)) US)* '}'
UTD Substructure Values ::= '{' US? UTD Structure Content US? '}'

Wherever a scalar value is expected, you can use any value consistent with the subnode value-entry parsing rules.

Wherever a substructure is expected, use curly braces instead of a scalar value or a string. The substructure content syntax is the same as the outer structure content's syntax.

One-dimensional arrays can be handled in one of two ways. Array elements can be enclosed within curly braces, with each array element appearing in sequential order (each array element is a separate scalar value, string, or substructure instance). Arrays of characters can also be characterized this way, but it is also possible to have a single string in place of the braces (the string, according to subnode value-entry parsing rules, determines the number of bytes assigned to the array).

Two-dimensional arrays are "arrays of arrays." To characterize these arrays, at least one outer curly brace enclosure is required. The individual elements of this array are one-dimensional arrays, which means each element can either be a sub-contained curly-brace enclosure, or it can be a string (for two-dimensional arrays of characters).

These rules might seem a bit hard to digest--unless you are familiar with C-based languages, in which case, there's almost nothing new to be learned. In any case, the following table provides examples of how complex variable types are characterized in UTD.

Scalar Examples

Substructure Examples

1-D Array Examples

2-D Array Examples

XML Scalar Value ::= (Scalar Value) - (Short String)
XML Value ::= (XML Scalar Value) | (XML String)
XML Variable Values ::= (XML 1-D Array Values) | (XML 2-D Array Values) | (XML Scalar Value) | (XML String) | (XML Substructure Values)
XML 2-D Array Values ::= ((XML_String) XS)* | (('<a>' | '<A>') XS? ((XML 1-D Array Values) | (XML String)) XS? ('</a>' | '</A>'))*
XML 1-D Array Values ::= (XML String) | (((XML Scalar Value) | (XML String) | (XML Substructure Values)) XS)*
XML Substructure Values ::= '<' (Structure Name) XS? '>' XS? (XML Structure Content) XS? '</' (Structure Name) XS? '>'

XML value syntax is slightly more complicated than UTD. Attribute assignments can make use of any UTD scalar value, EXCEPT short strings. Sequential members can be characterized as either XML scalar values or XML strings. Variable values characterized by tag assignments can make use of a full range of possible assignment syntaxes, depending on the variable type.

XML scalar values can use any value consistent with the subnode value-entry parsing rules, except for short strings.

XML strings have a markup format different from UTD strings. The format of this markup is described in the next subsection.

Wherever a substructure is expected, an open-and-close tag enclosure is used. The substructure content syntax is the same as the outer structure content's syntax.

One-dimensional arrays can be handled in one of two ways. Array elements can be placed as XML scalar values, XML strings, or XML substructures, with each array element appearing in sequential order. Arrays of characters can also be characterized this way, but it is also possible to have a single XML string (the string, according to XML string parsing rules, determines the number of bytes assigned to the array).

Two-dimensional arrays are "arrays of arrays." There are two ways to characterize these arrays. The individual elements of this array are one-dimensional arrays, which means each element can either be a sub-contained enclosure of <a> ... </a> tags, or it can be an XML string (for two-dimensional arrays of characters).

XML lends itself very well to categorizing hierarchical data. Since BARfly automatically "tabs out" the XML output in the dump, structure content dumped in XML is fairly easy to understand. The following table provides examples of how complex variable types are characterized in XML.

Scalar Examples

Substructure Examples

1-D Array Examples

2-D Array Examples

XML Strings

XML uses its own markup conventions for operator characters and unprintable characters. BARfly honors such conventions in the form of entities. XML entities have similar functionality to the backslash escape sequences used in UTD and subnode value-entry parsing rules, but they begin with an ampersand instead of a backslash, and end with a semicolon.

In XML, strings can be represented by either single quotes or double quotes. They are interchangeable; there is no implicit "automatic null byte" for double quotes. Therefore, the only way to guarantee a null byte on the end of a string in dumped output is to place a null byte entity in the dumped data.

Symbols that require markup in UTD might not need it in XML, and symbols that require markup in XML might not need it in UTD. The following table explains XML string markup.

< Less-than character, '<'.

> Greater-than character, '>'.

& Ampersand character, '&'.

' Apostrophe (single quote) character, "'".

" Double quote character, '"'.

&#xnn; Character code determined by nn, which is a hexadecimal number between 00 and FF.

&#nnn; Character code determined by nnn, which is a decimal number between 00 and 255.

Dumped Unorganized Blocks

Unorganized blocks are dumped with the name of the block type identified at the beginning, and the individual units of the block contained within a delimited subsection.

UTD Unorganized Block ::= ((Block Type Declarator) US)? (Block Name) US? (UTD Unit Count US?)? ('= ' US?)? '{' US? (UTD Unorganized Block Content) US? '}'
XML Unorganized Block ::= '<' (Block Name) XS? (XML Unit Count XS?)? '>' XS? (XML Unorganized Block Content) XS? '</' (Block Name) XS? '>'
Block Type Declarator ::= block | fileformatframework
UTD Unit Count ::= '[' US? (Scalar Value) US? ']'
XML Unit Count ::= 'unitcount' XS? '=' XS? (([#x22] (XML Scalar Value) [#x22]) | ([#x27] (XML Scalar Value) [#x27]))

A UTD unorganized block begins with an optional construct type declarator ("block" or "fileformatframework") and a required block name (defined by the I.F), with the content enclosed by curly braces. An XML unorganized block begins with an XML open tag, and ends with an XML close tag. The XML tag has the same name as the block name defined by the I.F.

Optionally, a unit count can identify the exact number of units in the block. In UTD, this is a bracketed integer immediately following the block's name. In XML, this is a "unitcount" attribute with a numeric assignment. The unit count serves to ensure that the block will always be a specific number of units, even if there are fewer units specified by the block's content in the dump. It also acts as a ceiling, which causes BARfly to generate an error if the number of units specified by the block's content in the dump exceeds this count.

UTD Examples

XML Examples

Unorganized block dumped content is very easy to understand. Numbers or strings, sized to whatever length desired, appear sequentially, and in any order, until the close of the block.

UTD Unorganized Block Content ::= (((Scalar Value) | (String)) US)*
XML Unorganized Block Content ::= (((XML Value) | (XML String)) XS)*

UTD content follows the subnode value-entry parsing rules . XML content follows a variation on these rules. The XML value and string markup format is described in the section above.

The following table lists several examples of unorganized block dumps.

UTD Examples

XML Examples

Note that text strings in unorganized blocks are always scaled to match the unit of the block if the block is a text block. If the "abc" block in the above example were a text block with a unit type of long, then each character ('c', 'd', and 'e') would count for four bytes each, not one, totalling 4x4 = 16 for the left example, and 4x3 = 12 for the right.

Dumped Organized Blocks

Organized blocks are dumped with the name of the block type identified at the beginning, and the individual units of the block contained within a delimited subsection.

UTD Organized Block ::= ((Block Type Declarator) US)? (Block Name) US? ('= ' US?)? '{' US? (UTD Organized Block Content) US? '}'
XML Organized Block ::= '<' (Block Name) XS? '>' XS? (XML Organized Block Content) XS? '</' (Block Name) XS? '>'

A UTD organized block begins with an optional construct type declarator ("block" or "fileformatframework") and a required block name (defined by the I.F), with the content enclosed by curly braces. An XML organized block begins with an XML open tag with no attributes, and ends with an XML close tag. The XML tag has the same name as the block name defined by the I.F.

UTD Example

XML Example

Organized block dumped content is very easy to understand. The content is entirely composed of other node characterizations, which represent the block's children in sequential order. These children are data structures, unorganized blocks, and other organized blocks.

UTD Organized Block Content ::= ((UTD Structure | UTD Unorganized Block | UTD Organized Block) US)*
XML Organized Block Content ::= ((XML Structure | XML Unorganized Block | XML Organized Block) XS)*

There is no fundamental limit to how high up in the hierarchy you can dump your data; you can dump from the top-level node if you want. Each successive organized block "sub-dumps" its contents accordingly.

Header structures are a special case in organized block content. If the first child in the dumped content is not a structure of the same name as the block's header structure, a header structure with default values is automatically populated as the first child of the block. If the first child in the content does match the block's header structure name, the header structure is populated like any other child of the organized block.

You might wonder what happens to the node browser if you make many diverse changes to the dumped content of an organized block, completely rearranging the hierarchy of its children. The answer is, the node browser is seamlessly updated to correspond with your changes. BARfly will completely tear the tree apart and reassemble it if necessary.

Limits to Editing Dumped Content

While dump view gives you incredible amounts of liberty in editing node data, there are still a few limitations when it comes to node type changes.

You are allowed to change the node type of the dumped node you are currently editing. You can change from one structure type to another, from one block type to another, or even from structure to block or from block to structure. There are a few special cases, though, when you cannot change node type. These are described below.

Header structure types: If you are editing a header structure in dump view, you cannot change its type. This is because an organized block with a header structure can only have one type of first child per its declaration in the I.F.
Top-level node: You cannot change the node type of the top-level node. You can edit every single one of its children, but you cannot change the top-level node's type, because an I.F.'s framework is characterized by having a consistent top-level node type for all files that use the I.F. as a schema.

Click here for information about changing dump view settings.

Click here for general information about dump view.