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

Changes between Version 15 and Version 16 of StructuredBinaryData

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

Explain referencing counting and move parameters.


  • StructuredBinaryData

    v15 v16  
    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.
     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`:
     168transform item(little_endian) = struct {
     169    .len <- u16(little_endian);
     170    .text <- ascii <- known_length(.len);
     171    .data <- known_length(8);
    161175== Structs ==
    202216There are some example files in `uspace/dist/src/bithenge`.
     218=== Using the API ===
     220An overview of the API will be written later.
     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.
    204231== Future language ideas ==
    206233In approximate order of priority.
    208 === Transform parameters ===
    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.
    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 }}}
    229235=== Other ideas ===