Fork us on GitHub Follow us on Facebook Follow us on Twitter

Changes between Version 15 and Version 16 of StructuredBinaryData


Ignore:
Timestamp:
2012-08-01T21:16:47Z (7 years ago)
Author:
Sean Bartell
Comment:

Explain referencing counting and move parameters.

Legend:

Unmodified
Added
Removed
Modified
  • StructuredBinaryData

    v15 v16  
    153153
    154154Transforms can be composed to create a new transform that applies them in
    155 order. The transform `ascii <- zero_terminated`
    156 first removes the 0x00 from the end of the blob, then decodes it as ascii. Note
    157 that the order of composition is consistent with function composition and
    158 nested application in mathematics, and also consistent with the general idea
    159 that data moves from right to left as it is decoded.
     155order. The transform `ascii <- zero_terminated` first removes the 0x00 from the
     156end of the blob, then decodes it as ascii. Note that the order of composition
     157is consistent with function composition and nested application in mathematics,
     158and also consistent with the general idea that data moves from right to left as
     159it is decoded.
     160
     161Transforms can have parameters that affect how they decode data:
     162`transform u16(little_endian) = if (little_endian) { uint16le } else { uint16be };`.
     163When such a transform is used, expressions must be given to calculate its
     164parameters. Currently, the only possible expressions are parameters given to
     165the current transform, boolean and integer literals, and previously decoded
     166fields in the current `struct`:
     167{{{
     168transform item(little_endian) = struct {
     169    .len <- u16(little_endian);
     170    .text <- ascii <- known_length(.len);
     171    .data <- known_length(8);
     172};
     173}}}
    160174
    161175== Structs ==
     
    202216There are some example files in `uspace/dist/src/bithenge`.
    203217
     218=== Using the API ===
     219
     220An overview of the API will be written later.
     221
     222Nodes, expressions, and transforms use reference counting.  Functions that
     223produce such objects (through a `bithenge_xxx_t **` argument) create a new
     224reference to the object; you are responsible for ensuring the reference count
     225is eventually decremented. If a function’s documentation says it “takes
     226[ownership of] a reference” to an object, the function guarantees the object’s
     227reference count will eventually be decremented, even if an error occurs.
     228Therefore, if you create an object only to immediately pass it to such a
     229function, you do not need to worry about its reference count.
     230
    204231== Future language ideas ==
    205232
    206233In approximate order of priority.
    207 
    208 === Transform parameters ===
    209 
    210 Currently, a transform can only have one input. Parameters will allow a
    211 transform to use multiple inputs:
    212 {{{
    213 transform strings(len) = struct {
    214     .str1 <- ascii <- known_length(len);
    215     .str2 <- ascii <- known_length(len);
    216 };
    217 }}}
    218 A transform with parameters can be defined as in `transform strings(len)`, and
    219 the parameters can be referenced inside the transform. When a transform is
    220 used, expressions are given for the values of its parameters.
    221 
    222 At first the only expressions will be parameters, as above, integer literals or previously decoded
    223 fields, as in
    224 {{{
    225     .len <- uint32le;
    226     .data <- known_length(.len);
    227 }}}
    228234
    229235=== Other ideas ===