When documenting RIFF forms that you create, use the notation listed in the preceding section along with the extended notation listed in the following table to unambiguously define the structure of the new form.
| <name> |
|
|
| |
|
A label that refers to some element of the file, where name is the name of the label. Examples follow: |
| |
|
<NAME-ck> <GOBL-form> <bitmap-bits> <foo> |
| |
|
Conventionally, a label that refers to a chunk is named <ckID-ck>, where ckID is the chunk ID. Similarly, a label that refers to a RIFF form is named <formType-form>, where formType is the name of the form's type. |
| <name> – elements |
|
|
| |
|
The actual data represented by <name> is defined as elements. This states that <name> is an abbreviation for elements. An example follows. |
| |
|
<GOBL-form> – RIFF ('GOBL'<form-data>) |
| |
|
This example defines label <GOBL-form> as representing a RIFF form with chunk ID “GOBL” and data equal to <form-data>, where <form-data> is a label that would be defined in another rule. Note that a label may represent any data, not just a RIFF chunk or form. |
| |
|
Note A number of atomic labels are defined in “Atomic Labels,” later in this chapter. These labels refer to primitive data types. |
| <name:type> |
|
|
| |
|
This is the same as <name>, but it also defines <name> to be equivalent to <type>. This notation obviates the following rule: |
| |
|
<name> – <type> |
| |
|
This allows you to give a symbolic name to an element of a file format and to specify the element data type. An example follows: |
| |
|
<xyz-coordinate> – <x:INT> <y:INT> <z:INT> |
| |
, |
|
| |
|
This defines <xyz-coordinate> to consist of three parts concatenated together: <x>, <y>, and <z>. The definition also specifies that <x>, <y>, and <z> are integers. This notation is equivalent to the following: |
| |
|
<xyz-coordinate> – <x> <y> <z> <x> – <INT> <y> – <INT> <z> – <INT> |
| [elements] |
|
|
| |
|
An optional sequence of labels and literal data. Surrounded by square brackets, it may be considered an element itself. An example follows: |
| |
|
<FOO-form> – RIFF('FOO'[<header-ck>]<data-ck>) |
| |
|
This example defines form “FOO” with an optional <header> chunk followed by a mandatory <data> chunk. |
| |
|
|
| el1 | el2 | . . . | elN |
|
|
| |
|
Exactly one of the listed elements must be present. An example follows: |
| |
|
<hdr-ck> – hdr(<hdr-x> | <hdr-y> | <hdr-z>) |
| |
|
This example defines the “hdr” chunk's data as containing one of <hdr-x>, <hdr-y>, or <hdr-z>. |
| element . . . |
|
|
| |
|
One or more occurrences of element may be present. Note that an ellipsis has this meaning only if it follows an element; in other cases (such as, A | B | . . . | Z), the ellipsis has its ordinary English meaning. If there is any possibility of confusion, an ellipsis should only be used to indicate one or more occurrences. An example follows: |
| |
|
<data-ck> – data(<count:INT> <item:INT> . . . ) |
| |
|
This example defines the data of the “data” chunk to contain an integer <count>, followed by one or more occurrences of the integer <item>. |
| [element] . . . |
|
|
| |
|
Zero or more occurrences of element may be present. An example follows. |
| |
|
<data-ck> – data(<count:INT> [<item:INT>] . . . ) |
| |
|
This example defines the data of the “data” chunk to contain an integer <count> followed by zero or more occurrences of an integer <item>. |
| { elements } |
|
|
| |
|
The group of elements within the braces should be considered a single element. An example follows: |
| |
|
<blorg> – <this> | <that> | <other>... |
| |
|
This example defines <blorg> to be either <this> or <that> or one or more occurrences of <other>. The next example defines <blorg> to be either <this> or one or more occurrences of <that> or <other>, intermixed in any way. |
| |
|
<blorg> – <this> | {<that> | <other>}... |
| struct { . . . } name |
|
|
| |
|
A structure defined using C syntax. This can be used instead of a sequence of labels if a C header (include) file is available that defines the structure. The label used to refer to the structure should be the same as the structure's typedef name. An example follows: |
| |
|
<3D_POINT> – struct { INT x; // x-coordinate INT y;// y-coordinate INT z;// z-coordinate } 3D_POINT |
| |
|
Wherever possible, the types used in the structure should be the types listed in the following section, “Atomic Labels,” because these types are more portable than C types such as int. The structure fields are assumed to be present in the file in the order given, with no padding or forced alignment. |
| |
|
Unless the RIFF chunk ID is “RIFX” integer byte ordering is assumed to be in Intel format. |
| // comment |
|
|
| |
|
An explanatory comment to a rule. An example follows: |
| |
|
<weekend> – 'Sat'|'Sun' // 4-char code for day |