systems.thoughtfull.argus — systems.thoughtfull/argus 0.3.0

argus clj/s

(argus & {:keys [encoders decoders default-decoder]})

Create a specification for encoding/decoding arbitrary Clojure values into JSON-compatible values and tagged values (a map with a single key/value pair where the key is a valid tag). A specification is thread safe. Because it caches lookups reusing a specification improves performance and is encouraged.

Every specification will have encoders and decoders for the standard argus tags: #date, #instant, #set, #uuid.

A specification may be extended with encoders and decoders for arbitrary types. Each encoder and decoder is associated with an extension tag. An extension tag must begin with an octothorpe and contain at least two name segments separated by a period. A name segment may contain alphanumerics, dash, and underscore. For example: '#clojure.keyword'.

Encoding is dispatched on a type. If no suitable encoder can be found for a dispatch type, argus will look for an encoder for a superclass or interface, and if found it will cache the encoder for the dispatch type. If a suitable encoder still cannot be found, then an error is thrown.

An encoder can have two forms. The first form is a vector of two elements the first being a valid extension tag and the second element being a single-argument function to encode an object. The second encoder form is a single-argument function taking an object and returning a tagged value.

The first encoder form, the vector form, the preferred form, will have its tag validated once upon construction of the specification. If the tag is not a valid extension tag, then an error is thrown.

The second encoder form, the function form, will be wrapped in a function that validates the tag of every tagged value produced. If the tag produced is not a valid extension tag, then an error is thrown.

argus only validates tags and does not validate that encoded values are JSON compatible. This is up to you and/or the JSON encoding library you use.

Decoding is dispatched on a tag. If no suitable decoder can be found for the tag, then a default decoder, if specified, is used. A decoder is a single-argument function taking an already decoded value from which it produces a value of an arbitrary non-JSON-compatible type.

The default decoder is a two-argument function taking the tag and an already decoded value from which it produces a value of an arbitrary non-JSON-compatible type. If no default decoder is specified, then the default default decoder will return a tagged value.

Each decoder tag in the specification is validated, and if a tag is not a valid extension tag, then an error is thrown.

Example:

systems.thoughtfull.argus> (argus :encoders {MyType ["#my.type" my-type-encoder]}
                             :decoders {"#my.type" my-type-decoder}
                             :default-decoder (fn [t v] :unknown-value))

• encoders (optional) — a map from type to encoder
• decoders (optional) — a map from extension tag to decoder
• default-decoder (optional) — a two-argument function, defaults to default-decoder.

deargus clj/s

(deargus argus value)

Decode JSON-compatible tagged values into arbitrary Clojure values.

In addition keys in a map are decoded specially. If a key is a string starting with a colon, then it is decoded as a keyword. Keyword namespaces are preserved.

If a key is a string starting with a quote, then it is decoded as a symbol. Symbol namespaces are preserved.

If a key is a string starting with two colons or two quotes, then one colon or quote is removed and the rest of the string is returned unmodified.

Example:

systems.thoughtfull.argus> (deargus (argus) {":key/word" {"#set" [1]},
                                             "'sym/bol" {"#set" [2]},
                                             "::not-keyword" {"#set" [3]},
                                             "''not-symbol" {"#set" [4]}})
{:key/word #{1}, sym/bol #{2}, ":not-keyword" #{3}, "'not-symbol" #{4}}

-argus — an argus specification produced by argus -value — a JSON-compatible tagged value to decode

default-decoder clj/s

(default-decoder tag value)

Takes a tag and value and returns a tagged value.

Example:

user> (default-decoder "#foo.bar" 42)
{"#foo.bar" 42}

enargus clj/s

(enargus argus value)

Encode arbitrary Clojure values into JSON-compatible tagged values.

In addition keys in a map have a special encoding. If a key is a keyword, then it is encoded as a string starting with a colon. Keyword namespaces are preserved.

If a key is a symbol, then it is encoded as a string starting with a quote. Symbol namespaces are preserved.

If a key is a string starting with a colon or quote, then the colon or quote is escaped by doubling it.

Example:

systems.thoughtfull.argus> (enargus (argus) {:key/word #{1}
                                             'sym/bol #{2}
                                             ":not-keyword" #{3}
                                             "'not-symbol" #{4}})
{":key/word" {"#set" [1]},
 "'sym/bol" {"#set" [2]},
 "::not-keyword" {"#set" [3]},
 "''not-symbol" {"#set" [4]}}

-argus — an argus specification produced by argus -value — a JSON-compatible tagged value to encode