A conditional clause takes one of two rather different forms:
IF [NOT] BooleanMethod [ELSE_SKIP SizeMethod]
PRINT_IF [NOT] VerifyMethod
The first style is used to make the entire processing of the field conditional: if the condition is met then the field is decoded and otherwise it is skipped. With the second style the field is always processed and the condition governs only whether it is displayed or not. This distinction leads to an important semantic difference between the two: An IF clause is evaluated before the field value is obtained while a PRINT_IF is evaluated after.
Conditional clauses are optional and, on any FIELD statement, only one type (IF or PRINT_IF) may be used. We will now examine each in deeper detail.
IF [NOT] BooleanMethod [ELSE_SKIP SizeMethod]
The keyword IF introduces the first style of conditional clause. The IF is followed by a call to a Boolean Method with an optional intervening NOT. A Boolean Method is one that makes some test and returns True or False.
Here is a good example:
FIELD fmt_length (Fixed 1 Byte) (Decimal) "Format Length"
FIELD fmt (FromField Bytes fmt_length 0) IF NOT (Fieldis EqualTo 0 fmt_length) (StringOfHex 32) "Format Data"
This example shows a way of dealing with a variable-length field where the length is given by another field. If the length is zero then the second field does not actually exist. The conditional clause is:
IF NOT (FieldIs EqualTo 0 fmt_length)
The FieldIs method makes a numeric comparison of the value in a named field (fmt_length in this case) with a given constant (0 here). Note that the result of the test is complemented by virtue of the NOT; we want to process the field only if the length is not zero. Actually, the clause could equally well be written:
IF (FieldIs NotEqualTo 0 fmt_length)
You may find times that you want to use an IF and skip some amount of data if the test fails. An IF clause can be extended to allow this as in this example taken from the Van Jacobson Compressed headers decoder (VJC.DEC):
FIELD Seq (Fixed 1 Bit) IF (TestTableData Special Special) ELSE_SKIP (Fixed 1 Bit) (Decimal) IN_ SUMMARY Seq 40 Seq
Here a particular bit is meaningful only when another field has been set in a certain way (as tested by the TestTableData call). To use this option on an IF, place the keyword ELSE_SKIP after the call to the Boolean Method and follow that by a call to a Size Method that determines how much data is to be skipped.
PRINT_IF [NOT] VerifyMethod
This form of conditional clause is triggered by the PRINT_IF keyword. The condition is tested by a VerifyMethod and the test may be reversed by the presence of a NOT.
A VerifyMethod is like a BooleanMethod in that it returns True or False. A different set of testing operations is provided though, mostly functions to test the value obtained for the field.
Here is an example from the SMB decoder. SMB makes extensive use of bit flags and, to make them stand out, the decoder generally displays such flags only when they are set. (Flags that are not set are assumed to be of no interest.)
FIELD case (Fixed 1 Bit) PRINT_IF (FieldIs EqualTo 1) (Constant "Pathnames Are Caseless") "Bit 3"