diff --git a/user_guide.adoc b/user_guide.adoc index 73d89ef..f8cf7b3 100644 --- a/user_guide.adoc +++ b/user_guide.adoc @@ -313,43 +313,67 @@ data — it all comes naturally from the `contents`. [[valid-values]] === Validating attribute values -To ensure attributes in your data structures adhere to expected formats and ranges, Kaitai Struct provides a mechanism for validating attribute values using the `valid` key. This key allows you to define constraints for values, enhancing the robustness of your specifications. Here's how you can enforce these constraints: +IMPORTANT: Feature available since v0.9. -* `eq` (or directly `valid: value`): Ensures the attribute value exactly matches the given value. -* `min`: Specifies the minimum valid value for the attribute. -* `max`: Specifies the maximum valid value for the attribute. -* `any-of`: Defines a list of acceptable values, one of which the attribute must match. -* `expr`: An expression that evaluates to true for the attribute to be considered valid. +To ensure attributes in your data structures adhere to expected formats +and ranges, Kaitai Struct provides a mechanism for validating attribute +values using the `valid` key. This key allows you to define constraints +for values, enhancing the robustness of your specifications. Here's how +you can enforce these constraints: + +* `eq` (or directly `valid: value`): ensures the attribute value exactly + matches the given value. +* `min`: specifies the minimum valid value for the attribute. +* `max`: specifies the maximum valid value for the attribute. +* `any-of`: defines a list of acceptable values, one of which the + attribute must match. +* `expr`: an expression that evaluates to true for the attribute to be + considered valid. For most cases, the direct `valid: value` shortcut is preferred for its simplicity, effectively functioning as `valid/eq`. [source,yaml] ---- seq: - - id: exact_value + # Full form of equality constraint: the only valid value is 0x42 + - id: exact_value1 + type: u1 + valid: + eq: 0x42 + + # Shortcut for the above: the only valid value is 0x42 + - id: exact_value2 type: u1 - valid: 0x42 # Shortcut for eq: The only valid value is 0x42 + valid: 0x42 + # Value must be at least 100 and at most 200 - id: bounded_value type: u2 valid: - min: 100 # Value must be at least 100 - max: 200 # and at most 200 + min: 100 + max: 200 - - id: enum_value + # Value must be one of 3, 5, or 7 + - id: enum_constraint_value type: u4 valid: - any-of: [3, 5, 7] # Value must be one of 3, 5, or 7 + any-of: [3, 5, 7] - - id: calculated_value + # Value must be even + - id: expr_constraint_value type: u4 valid: - expr: _ % 2 == 0 # Value must be even + expr: _ % 2 == 0 ---- -When a value does not meet the specified criteria, Kaitai Struct raises a validation error, halting further parsing. This preemptive measure ensures the data being parsed is within the expected domain, providing a first layer of error handling. +When a value does not meet the specified criteria, Kaitai Struct raises a +validation error, halting further parsing. This preemptive measure +ensures the data being parsed is within the expected domain, providing a +first layer of error handling. -NOTE: The actual implementation of validation checks is language-dependent and may vary in behavior and supported features across different target languages. +NOTE: The actual implementation of validation checks is +language-dependent and may vary in behavior and supported features across +different target languages. [[var-length-struct]] === Variable-length structures