bites.codec — bites 0.2.3

aligned clj

(aligned inner-codec
         &
         {:keys [modulo padding-byte] :or {padding-byte 0 modulo 1} :as opts})

This codec is related to padding in that it makes sure that the number of bytes written/read to/from a stream always is aligned to a specified byte boundary. For example, if a format requires aligning all data to 8 byte boundaries this codec will pad the written data with padding-byte to make sure that the count of bytes written is divisable by 8. Parameters:

• modulo: byte boundary modulo, should be positive
• :padding-byte is the numeric value of the byte used for padding (default is 0) Example: (encode (align (repeated :short-be :length 3) :modulo 9 :padding-byte 55) [1 2 3] output-stream) ;==> writes these bytes: [0 1 0 2 0 3 55 55 55]

BinaryCodec clj protocol

bin-read clj

(bin-read codec in)

bin-write clj

(bin-write codec out v)

bits clj

(bits flags)

flags is a sequence of flag names. Each flag's index corresponds to the bit with that index. Flag names null are ignored. Bit count will be padded up to the next multiple of 8.

blob clj

(blob & {:keys [length length-prefix]})

Reads a chunk of binary data as a Java byte array. Options as in repeated, except :separator is not supported.

codec? clj

(codec? codec)

constant clj

(constant codec constant-value)

Reads a constant value, ignores given value on write. Can be used as a version tag for a composite codec. Example: (encode out (constant :int-le 7) 1234) => ;will instead write bytes [7 0 0 0]

cstring clj

(cstring encoding)

Zero-terminated string (like in C). String is a sequence of bytes, terminated by a 0 byte.

decode-with clj

(decode-with codec in)

Deserialize a value from in according to the codec.

encode-with clj

(encode-with codec out v)

Serialize a value <v> to <out> according to the codec.

enum clj

(enum codec m & {:keys [lenient?]})

An enumerated value. m must be a 1-to-1 mapping of names (e.g. keywords) to their decoded values. Only names and values in m will be accepted when encoding or decoding.

header clj

(header header-codec header->body-codec body->header & {:keys [with-header?]})

Decodes a header using header-codec. Passes this datastructure to header->body-codec which returns the codec to use to parse the body. For writing this codec calls body->header with the data as parameter and expects a value to use for writing the header information. If the optional flag :keep-header is set, read will return a map with the keys:header and body else only the body will be returned.

instance clj

(instance k)

instances clj

(instances codecs)

noop clj

ordered-map clj

(ordered-map & kvs)

Parse a binary stream into a map.

padded clj

(padded inner-codec
        &
        {:keys [length padding-byte truncate?] :or {padding-byte 0} :as opts})

Make sure there is always a minimum byte length when reading/writing values. Works by reading length bytes into a byte array, then reading from that array using inner-codec. Currently there are three options:

• :length is the number of bytes that should be present after writing
• :padding-byte is the numeric value of the byte used for padding (default is 0)
• :truncate? is a boolean flag that determines the behaviour if inner-codec writes more bytes than padding can handle: false is the default, meaning throw an exception. True will lead to truncating the output of inner-codec. Example: (encode (padding (repeated (string "UTF8" :separator 0)) :length 11 :truncate? true) outstream ["abc" "def" "ghi"]) => ; writes bytes [97 98 99 0 100 101 102 0 103 104 105] ; observe: the last separator byte was truncated!

primitive clj

(primitive k)

Returns a new primitive codec, per <k>.

primitive* clj

(primitive* n read-fn write-fn & [endianess])

Create a reification of BinaryCodec that can read/write a primmitive data type.

primitives clj

repeated clj

(repeated codec & {:keys [length length-prefix separator]})

Read a sequence of values. Options are pairs of keys and values with possible keys:

• :length fixed length of the sequence
• :length-prefix codec for the length of the sequence to read prior to the sequence itself.
• :separator reads until the read value equals the given separator value. EOF of a stream is regarded a separator too. That means if the last token is the last element in a stream, the final separator may be missing. Caution: When writing the data there WILL be a final separator. This means, the written data may have more bytes than initially read! If there is no options, the decoder tries to read continuously until the stream is exhausted. Example: To read a sequence of integers with a byte prefix for the length use (repeated :byte :length-prefix :int)

string clj

(string encoding & options)

union clj

(union bytes-length codecs-map)

Union is a C-style union. A fixed number of bytes may represent different values depending on the interpretation of the bytes. The value returned by read-data is a map of all valid interpretations according to the specified unioned codecs. Parameter is the number of bytes needed for the longest codec in this union and a map of value names to codecs. This codec will read the specified number of bytes from the input streams and then successively try to read from this byte array using each individual codec. Example: Four bytes may represent an integer, two shorts, four bytes, a list of bytes with prefix or a string. (union 4 {:integer :int-be :shorts (repeated :short-be :length 2) :bytes (repeated :byte :length 4) :prefixed (repeated :byte :prefix :byte) :str (string "UTF8" :prefix :byte)})

wrap clj

(wrap codec pre-encode post-decode)

Wrap a codec with pre/post-processing functions to be applied to the value before writing/after reading. Use these to transform values according to domain specific rules.