API for gloss.core

by Unknown

Usage:
(ns your-namespace
  (:require gloss.core))

Overview



Public Variables and Functions



bit-map

function
Usage: (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

function
Usage: (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

function
Usage: (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

function
Usage: (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

macro
Usage: (defcodec name frame)
Defines a compiled frame.


defcodec-

macro
Usage: (defcodec- name frame)
Defines a private compiled frame.


delimited-block

function
Usage: (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

function
Usage: (delimited-frame delimiters frame)
Defines a frame which is terminated by delimiters.


enum

function
Usage: (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

function
Usage: (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

function
Usage: (finite-frame prefix-or-len frame)
Defines a frame which is either of finite length, or has a prefix which describes
its length.


header

function
Usage: (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.


ordered-map

function
Usage: (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

function
Usage: (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

function
Usage: (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.


string

function
Usage: (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"])

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)
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.