sfv-clj

A Clojure library for (de)serialisation of structured field values (RFC 8941). The actual implementation is provided by the structured-fields Java library.

This library provides the following functionality:

• low-level wrappers around the Java implementations
  • parsing strings into values
  • constructing values
• Clojure data <-> library type conversion
  • sfv->clj to turn a (deserialised) value into Clojure data
  • clj->sfv to turn Clojure data into a value (that can then be serialised)
• Tagged literal shorthands for convenience

Usage

(require '[org.clojars.johnnyjayjay.sfv :as sfv])

;; low-level constructors
(def sf-value
  (sfv/sf-dictionary
    {"simple-string" (sfv/sf-string "value")
     "parametrized-int" 
      (sfv/sf-integer 
       (sfv/sf-parameters {"param-key" (sfv/sf-decimal 4.5M)})
       1234)}))

;; the same SFV as before, this time in its Clojure data representation
(def sf-value-data
  ;; #sf/... is shorthand for creating a map like the second value without params
  {:simple-string #sf/str "value"
   :parametrized-int
   {:type :sf/integer
    :value 1234
    :params {:param-key #sf/dec 4.5M}}})

;; converting between one and the other:
(sfv/clj->sfv sf-value-data)
(sfv/sfv->clj sf-value)

;; serialisation:
(sfv/serialize sf-value)
;; => "simple-string=\"value\", parametrized-int=1234;param-key=4.5"

;; parsing:
(sfv/parse-dictionary "simple-string=\"value\", parametrized-int=1234;param-key=4.5")

Structured field dictionary are technically ordered. In the construction of the examples above however, I used regular Clojure maps for their construction. This library has a dependency on ordered for an ordered map implementation. You are free to use this when constructing dictionaries, but you don't have to if it doesn't matter in your context. sfv->clj will always produce ordered maps for dictionaries.

Overview of the available tagged literals and their associated types:

• #sf/int 5 - :type :sf/integer
• #sf/dec 0.123M - :type :sf/decimal
• #sf/str "hello" - :type :sf/string
• #sf/tok "world" - :type :sf/token
• #sf/bool true - :type :sf/boolean
• #sf/ilist [...] - :type :sf/inner-list

Note that these construct Clojure data representations of the corresponding structured field values, not the object representations (those obtained via clj->sfv).

License

Copyright © 2024 JohnnyJayJay

This program and the accompanying materials are made available under the terms of the Apache License 2.0 which is available at http://www.apache.org/licenses/LICENSE-2.0.