Changes between Version 15 and Version 16 of StructuredBinaryData

Timestamp:

2012-08-01T21:16:47Z (13 years ago)

Author:

Sean Bartell

Comment:

Explain referencing counting and move parameters.

StructuredBinaryData

@@ -153 +153 @@
 
 Transforms can be composed to create a new transform that applies them in
-order. The transform `ascii <- zero_terminated`
-first removes the 0x00 from the end of the blob, then decodes it as ascii. Note
-that the order of composition is consistent with function composition and
-nested application in mathematics, and also consistent with the general idea
-that data moves from right to left as it is decoded.
+order. The transform `ascii <- zero_terminated` first removes the 0x00 from the
+end of the blob, then decodes it as ascii. Note that the order of composition
+is consistent with function composition and nested application in mathematics,
+and also consistent with the general idea that data moves from right to left as
+it is decoded.
+
+Transforms can have parameters that affect how they decode data:
+`transform u16(little_endian) = if (little_endian) { uint16le } else { uint16be };`.
+When such a transform is used, expressions must be given to calculate its
+parameters. Currently, the only possible expressions are parameters given to
+the current transform, boolean and integer literals, and previously decoded
+fields in the current `struct`:
+{{{
+transform item(little_endian) = struct {
+    .len <- u16(little_endian);
+    .text <- ascii <- known_length(.len);
+    .data <- known_length(8);
+};
+}}}
 
 == Structs ==
@@ -202 +216 @@
 There are some example files in `uspace/dist/src/bithenge`.
 
+=== Using the API ===
+
+An overview of the API will be written later.
+
+Nodes, expressions, and transforms use reference counting.  Functions that
+produce such objects (through a `bithenge_xxx_t **` argument) create a new
+reference to the object; you are responsible for ensuring the reference count
+is eventually decremented. If a function’s documentation says it “takes
+[ownership of] a reference” to an object, the function guarantees the object’s
+reference count will eventually be decremented, even if an error occurs.
+Therefore, if you create an object only to immediately pass it to such a
+function, you do not need to worry about its reference count.
+
 == Future language ideas ==
 
 In approximate order of priority.
-
-=== Transform parameters ===
-
-Currently, a transform can only have one input. Parameters will allow a
-transform to use multiple inputs:
-{{{
-transform strings(len) = struct {
-    .str1 <- ascii <- known_length(len);
-    .str2 <- ascii <- known_length(len);
-};
-}}}
-A transform with parameters can be defined as in `transform strings(len)`, and
-the parameters can be referenced inside the transform. When a transform is
-used, expressions are given for the values of its parameters.
-
-At first the only expressions will be parameters, as above, integer literals or previously decoded
-fields, as in
-{{{
-    .len <- uint32le;
-    .data <- known_length(.len);
-}}}
 
 === Other ideas ===