General Syntax Rules

A decoder is constructed of three basic elements: statements, comments and braces.

The syntax of a comment matches that used by the C++ programming language. There are two types of comments. One opens with a slash and an asterisk and closes with an asterisk and a slash; in each case, the pair of characters must be written together with no intervening space. Such a comment may extend over several lines. The other type of comment starts with two slashes and ends at the end of the line. Comments may appear anywhere.

A statement consists of a sequence of items separated by white space (spaces or line breaks). It would probably be more common usage to refer to a statement as a sequence of fields but we retain the term "field" to apply strictly to a protocol field and use "item" for the components of a statement. An item may be a keyword, a name/string, a numeric constant, or a method invocation.

Keywords that we have already met include FIELD and GROUP. We have a convention that keywords are always written in all capitals; this makes for good readability but is not required.

A name/string is a character string that represents, for example, the name of a field or the text to appear in a decode detail. A name/string must be enclosed in double quotes if it contains spaces or characters other than letters, numbers, and underscores. While names and strings are treated the same syntactically, conceptually they are rather different and by convention we write them in distinct ways. FIELDs and GROUPs are given names that do not include spaces and their names are not quoted. Furthermore, names are usually all lowercase and underscores are used as in this_is_a_field_name. We make a practice of giving methods names exemplified by DoThisToThat. Whenever names are matched, the comparison is done without sensitivity to case. Strings, that is text fragments to be displayed as part of the decode, are always double-quote delimited for readability.

A number is expressed as either a signed decimal (e.g. ‐10) or in hexadecimal notation prefaced by "0x" (for example, 0xFFFF).

A method invocation is written as a parenthesized expression consisting of a method name followed by a list of parameters as in: (MethodName param1 param2)

Braces are used to group statements together and to delimit table entries. Braces must appear in matched pairs.

DecoderScript statements are written as a sequence of items separated by at least one space. A line break counts as a space so a statement may be spread over two or more lines (as shown in the actuator_value FIELD). Numbers may be expressed either in decimal or in hexadecimal prefaced by "0x".

Following each name, we see an expression that defines the size of the field, (Fixed 1 Byte) for example. This size may serve as many as three purposes. First, as each protocol layer is decoded, a pointer (called the "bit pointer") passes through the data. This pointer starts out at the beginning of the layer and, as each field is processed, it is incremented by the size of the field. The second purpose is to store the field value in an appropriate way. And third, the size may affect how the field value is formatted.