gloss.core — gloss 0.2.6

bit-map clj

(bit-map & args)

Defines an ordered map of signed integers with the specified bit-lengths. The sum of the bit-lengths must be divisible by 8.

(bit-map :a 3, :b 4, :c 1) <=> {:a 3, :b -15, :c false}

bit-seq clj

(bit-seq & bit-lengths)

Defines a sequence of unsigned integers with the specified bit-lengths. The sum of the bit-lengths must be divisable by 8. Single bit values are treated specially, and will decode to simply 'true' or 'false'.

(bit-seq 4 3 1) <=> [15 7 true]

If a number is larger than its bit-count can contain, it will be truncated during encoding.

byte-count clj

(byte-count b)

Returns the number of bytes in the value. Compatible with any data structure that can be transformed into a sequence of ByteBuffers.

compile-frame clj

(compile-frame frame)

(compile-frame frame pre-encoder post-decoder)

Takes a frame, and returns a codec. This function is idempotent; passing in a codec is a safe operation.

Functions that transform the values after they are decoded and before they are encoded can be specified, which allows the frame to only be an intermediate representation of the final Clojure data structure.

defcodec clj macro

(defcodec name frame & coders)

Defines a compiled frame.

defcodec- clj macro

(defcodec- name frame & coders)

Defines a private compiled frame.

delimited-block clj

(delimited-block delimiters strip-delimiters?)

Defines a frame which is just a byte sequence terminated by one or more delimiters.

If strip-delimiters? is true, the resulting byte sequences will not contain the delimiters.

delimited-frame clj

(delimited-frame delimiters frame)

Defines a frame which is terminated by delimiters.

enum clj

(enum primitive-type & map-or-seq)

Takes a list of enumerations, or a map of enumerations onto values, and returns a codec which associates each enumeration with a unique encoded value.

(enum :byte :a :b :c) (enum :int32 {:a 100, :b 200, :c 300})

finite-block clj

(finite-block prefix-or-len)

Defines a byte sequence which is either of fixed length or has a prefix which describes its length.

finite-frame clj

(finite-frame prefix-or-len frame)

Defines a frame which is either of finite length, or has a prefix which describes its length.

header clj

(header frame header->body body->header)

A header is a frame which describes the frame that follows. The decoded value from the header frame will be passed into 'header->body,' which will return the resulting codec for the body. When encoding, the value of the body will be passed into 'body->header,' which will return the resulting value for the header.

nil-frame clj

ordered-map clj

(ordered-map & key-value-pairs)

Creates a codec which consumes and emits standard Clojure hash-maps, but ensures that the values are encoded in the specified order. Useful for interop with C structs and network protocols.

prefix clj

(prefix primitive)

(prefix signature to-count from-count)

A prefix is a specialized form of header, which only describes the length of the sequence that follows. It is only meant to be used in the context of 'finite-frame' or 'repeated'. A prefix may be as simple as a primitive type:

(prefix :int32)

But may also be a more complex frame:

(prefix [(string :utf-8 :delimiters ["\0"]) :int64] second (fn [n] ["hello" n]))

For complex prefixes, 'to-count' must take the value of the header and return the length of the sequence that follows, and 'from-count' must take the length of the sequence and return the value of the prefix.

repeated clj

(repeated frame & {:as options})

Describes a sequence of frames. By default, the sequence is prefixed with a 32-bit integer describing the length of the sequence. However, specifying a custom :prefix or :delimiters that terminate the sequence is also allowed.

sizeof clj

(sizeof this)

Returns the number of bytes this codec will encode to, or nil if it is value-dependent.

string clj

(string charset & {:as options})

Defines a frame which contains a string. The charset must be a keyword, such as :utf-8 or :ascii. Available options are :length, :delimiters, :suffix, and :char-sequence.

A string with :length specified is of finite byte length:

(string :ascii :length 3)

A string with :delimiters specified is terminated by one or more delimiters:

(string :utf-8 :delimiters ["\r\n" "\r"])

By specifying :value->delimiter you can selectively delimit a value when encoding:

(string :utf-8 :delimiters ["\r\n" " "] :value->delimiter (fn [v] (if (= v "END") ["\r\n"] [" "])))

If a string is already bounded in length, but has a terminating sequence, use :suffix

(string :utf-8, :length 3, :suffix "\r\n")

:suffix can be used in conjunction with both :length and :delimiters. The given :length is assumed to not include the suffix, and the delimiters are assumed to be followed by the suffix.

By default, this frame will return a string, but it can be more memory-efficient to have it return a java.lang.CharSequence instead. This frame also will encode CharSequences. To have the decoded result be a CharSequence, set :char-sequence to true:

(string :utf-8, :length 3, :char-sequence true)

string-float clj

(string-float charset & {:as options})

string-integer clj

(string-integer charset & {:as options})