octet.spec — funcool/octet 1.1.2

The spec abstraction.

It includes the basic abstraction protocols for define own type specs and some useful types that allows build asociative or indexed spec compositions.

For more examples see the spec function docstring.

AssociativeSpec cljs

compose clj/s

(compose constructor types)

Create a composed typespec with user defined type constructor.

This allows define a typespec with automatic conversion between user data type and serialized data without defining yourself a datatype using low level constructions.

Let see an exameple for understand it better.

Imagine you are have this data type:

(defrecord Point [x y])

With help of compose, create a new spec for your datatype:

(def point-spec (buf/compose ->Point [buf/int32 buf/int32]))

Now, you can use the previously defined datatype and typespec for write into buffer:

(buf/write! buffer mypoint point-spec)
;; => 8

Or read from the buffer:

(buf/read buffer (point))
;; => #user.Point{:x 1, :y 2}

IndexedSpec cljs

ISpec clj/s≠ protocol

Basic abstraction for something that can be work like a Spec.

read clj/s

(read _ buff start)

Read all data from buffer.

write clj/s

(write _ buff start data)

Read all data from buffer.

ISpecDynamicSize clj/s≠ protocol

Abstraction for calculate size for dynamic specs.

size* clj/s

(size* _ data)

Calculate the size in bytes of the object having a data.

ISpecSize clj/s≠ protocol

Abstraction for calculate size of static specs.

size clj/s

(size _)

Calculate the size in bytes of the object.

ISpecWithRef clj/s≠ protocol

Abstraction to support specs having references to other specs within an AssociativeSpec or an IndexedSpec

read* clj/s

(read* _ buff start data)

Read data from buffer, use data to calculate length etc

write* clj/s

(write* _ buff start value types data)

Write data from buffer, use data to store length etc

repeat clj/s

(repeat n type)

Creare a composed typespec that repeats n times a provided type spec.

As example, create a spec with help of repeat function:

(def spec (buf/repeat 2 buf/int32))

Write data into buffer using previously defined typespec:

(buf/write! yourbuffer [200 300] spec)
;; => 8

Or read data from your buffer using previously defined typespec:

(buf/read yourbuffer spec)
;; => [200 300]

spec clj/s

(spec & params)

Polymorphic constructor for Spec instances.

Spec is a some kind of composition of arbitrary number of types in associative or indexed data structure.

Little example on how to create associative composition:

(spec :field1 (long)
      :field2 (string 20))

An other example on how to create indexed composition that represents the same bytes representation that previous one:

(spec (long) (string 20))

The main difference between the two reprensentation is that if you read a buffer using an associative spec, the result will be clojure hash-map, and if indexed spec is used, the result will be clojure vector containing the values.

The same rules applies for writing data into a buffer.