Changes between Version 17 and Version 18 of StructuredBinaryData

Timestamp:

2012-08-04T18:03:30Z (12 years ago)

Author:

Sean Bartell

Comment:

Document flow control syntax

StructuredBinaryData

@@ -132 +132 @@
 
 ||= name =||= input =||= output =||= description =||= example =||
-||ascii           ||blob node        ||string       ||decodes some bytes as ASCII characters ||  `hex:6869` becomes `"hi"` ||
-||uint8           ||1‐byte blob node ||integer node ||decodes a 1‐byte unsigned integer ||  `hex:11` becomes `17` ||
-||uint16be        ||2‐byte blob node ||integer node ||decodes a 2‐byte big‐endian unsigned integer ||  `hex:0201` becomes `513` ||
-||uint16le        ||2‐byte blob node ||integer node ||decodes a 2‐byte little‐endian unsigned integer ||  `hex:0101` becomes `257` ||
-||uint32be        ||4‐byte blob node ||integer node ||decodes a 4‐byte big‐endian unsigned integer ||  `hex:00000201` becomes `513` ||
-||uint32le        ||4‐byte blob node ||integer node ||decodes a 4‐byte little‐endian unsigned integer ||  `hex:01010000` becomes `257` ||
-||uint64be        ||8‐byte blob node ||integer node ||decodes a 8‐byte big‐endian unsigned integer ||  `hex:0000000000000201` becomes `513` ||
-||uint64le        ||8‐byte blob node ||integer node ||decodes a 8‐byte little‐endian unsigned integer ||  `hex:0101000000000000` becomes `257` ||
-||zero_terminated ||blob node        ||blob node    ||takes bytes up until the first `00` ||  `hex:7f0400` becomes `hex:7f04` ||
+||ascii             ||blob node        ||string       ||decodes some bytes as ASCII characters ||  `hex:6869` becomes `"hi"` ||
+||known_length(len) ||blob node        ||blob node    ||requires the input to have a known length || ||
+||nonzero_boolean   ||integer          ||boolean      ||decodes a boolean where nonzero values are true || `0` becomes `false` ||
+||uint8             ||1‐byte blob node ||integer node ||decodes a 1‐byte unsigned integer ||  `hex:11` becomes `17` ||
+||uint16be          ||2‐byte blob node ||integer node ||decodes a 2‐byte big‐endian unsigned integer ||  `hex:0201` becomes `513` ||
+||uint16le          ||2‐byte blob node ||integer node ||decodes a 2‐byte little‐endian unsigned integer ||  `hex:0101` becomes `257` ||
+||uint32be          ||4‐byte blob node ||integer node ||decodes a 4‐byte big‐endian unsigned integer ||  `hex:00000201` becomes `513` ||
+||uint32le          ||4‐byte blob node ||integer node ||decodes a 4‐byte little‐endian unsigned integer ||  `hex:01010000` becomes `257` ||
+||uint64be          ||8‐byte blob node ||integer node ||decodes a 8‐byte big‐endian unsigned integer ||  `hex:0000000000000201` becomes `513` ||
+||uint64le          ||8‐byte blob node ||integer node ||decodes a 8‐byte little‐endian unsigned integer ||  `hex:0101000000000000` becomes `257` ||
+||zero_terminated   ||blob node        ||blob node    ||takes bytes up until the first `00` ||  `hex:7f0400` becomes `hex:7f04` ||
 
 == Basic syntax ==
@@ -207 +209 @@
 is `{"id": 6, "label": "A", "x": 3, "y": 8}`.
 
+== Flow Control ==
+
+Boolean conditions can use
+`if (expression) { transform-if-true } else { transform-if-false }`, for
+example: `if (little_endian) { uint32le } else { uint32be }`. There is also
+syntax for switches: `switch (expression) { expression: transform; ... }`. Both
+of these have syntactic sugar for use in `struct`s; in a `struct`,
+`if (expression) { fields... }` is equivalent to
+`<- if (expression) { struct { fields... } };`.
+
+Three kinds of repetition are supported. `repeat(expression) {transform}`
+applies the transform a given number of times. `repeat {transform}` applies the
+transform until it fails or the end of the data is reached.
+`do {transform} while(expression)` applies the transform until the expression,
+evaluated within the result of the transform, is false; this can be used for
+things like
+`do { struct { .keep_going <- nonzero_boolean <- uint8; .val <- uint8; } } while(.keep_going)`.
+For each type of repetition, the result is an internal node with sequential
+keys starting at `0`.
+
 == Using Bithenge ==
 
@@ -242 +264 @@
 === Other ideas ===
 
- Conditional transforms:: A way to apply different transforms depending on an
-   expression. For example, something like:
-   `if (.has_extra) { struct { .extra <- uint32le; } }`.
- Repetition:: Transforms may need to be repeated a known number of times, until
-   the end of the data, or until the transform indicates that repetition should
-   stop. For instance, `repeat(.len) {uint32le;}`. The result could be a tree
-   like `{0: 1351, 1: 17}`.
  Subblobs:: When there are pointers to other offsets in the blob, the script
    could pass the whole blob as a parameter and apply transforms to subblobs.