Attribute description

Attribute description specifies how to read one particular attribute — typically, a single number, a string, array of bytes, etc. Attribute can also reference other complex structures by specifying user type given in type description. Each attribute is typically compiled into equivalent parsing instruction(s) in target language.

Common attributes

id

• Contents: a string that matches /^[a-z][a-z0-9_]*$/ — i.e. starts with lowercase letter and then may contain lowercase letters, numbers and underscore
• Purpose: identify attribute among others
• Influences: used as variable / field name in target programming language
• Mandatory: yes

type

• Contents: one of primitive data types or a user-specified type name
• Purpose: define a data type for an attribute
• Influences: how much bytes would be read, data type and contents of a variable in target programming language
• Mandatory: no — if type is not specified, then attribute is considered a generic byte sequence

repeat

• Contents: expr or eos
• Purpose: designate repeated attribute in a structure;
  • if repeat: expr is used, then attribute is repeated the number of times specified in repeat-expr key;
  • if repeat: eos is used, then attribute is repeated until the end of current stream
  • if repeat: until is used, then attribute is repeated until given expression becomes true (one may use a reference to last parsed element in such expression)
• Influences: attribute would be read as array / list / sequence, executing parsing code multiple times
• Mandatory: no

repeat-expr

• Contents: expression, expected to be of integer type
• Purpose: specify number of repetitions for repeated attribute
• Influences: number of times attribute is parsed
• Mandatory: yes, if repeat: expr

repeat-until

• Contents: expression, expected to be of boolean type
• Purpose: specify expression that would be checked each time after an element of requested type is parsed; while expression is false (i.e. until it becomes true), more elements would be parsed and added to resulting array; one can use _ in expression as a special variable that references last read element
• Influences: number of times attribute is parsed
• Mandatory: yes, if repeat: until

if

• Contents: expression, expected to be of boolean type
• Purpose: mark the attribute as optional
• Influences: attribute would be parsed only if condition specified in if key evaluates (in runtime) to true
• Mandatory: no

Attributes that depend on type

No type specified

If there's no type specified, attribute will be read just as a sequence of bytes from a stream. Thus, one has to decide on how many bytes to read. There are two ways:

• Specify amount of bytes to read in size key. One can specify an integer constant or an expression in this field (for example, if the number of bytes to read depends on some other attribute).
• Set size-eos: true, thus ordering to read all the bytes till the end of current stream.

size

size-eos

process

It is possible to apply some algorithmic processing to a byte buffer before accessing it. This can be done using process attribute.

u*, s*

These specify primitive integer types. One can map an integer to some enum value with an enum attribute.

enum

• Contents: name of existing enum
• Purpose: apply mapping of parsed integer using a given enum dictionary into some sort of named constant
• Influences: field data type becomes given enum
• Mandatory: no

str

Specifies a fixed-length string, i.e. first it reads a designated number of bytes, then it tries to convert bytes to characters using a specified encoding. There are 2 ways to specify amount of data to read:

• Specify number of bytes to read directly in size key. One can specify an integer constant or an expression in this field (for example, if the number of bytes to read depends on some other attribute).
• Set size-eos: true, thus ordering to read all the bytes till the end of current stream.

size

size-eos

encoding

strz

Specifies parsing a string until a terminator byte (i.e. C-style strings terminated with 0).

terminator

consume

include

eos-error

User-specified types