bencode-cljc
"Instead of cursing the darkness, light a candle." ― Benjamin Franklin
A functional Clojure(script) BEncode serialization library.
[org.jamesleonis/bencode-cljc "0.1.2"]
Why?
bencode-cljc
aims to be a portable implementation of the BEncode spec, to boldly go wherever Clojure goes.
Usage
(ns your.awesome.app
(:require [bencode-cljc.core :refer [serialize deserialize]]))
(def out (serialize {"spam" (list "a" "b")})
; => "d4:spaml1:a1:bee"
(deserialize out)
; => {"spam" '("a" "b")}
Details
serialize
operates on Clojure data structures and outputs a Clojure string.
deserialize
operates on the opposite of serialize
.
If an error is encountered in either, nil
is returned.
Encoding
As an encoder, bencode-cljc
is fairly strict. The aim is full compatibility with existing BEncoded services, and not a fully featured transport encoder. As such, only Integer, Maps, Lists, and Strings are supported.
This comes with some unfortunate side-effects:
-
nil
values are unsupported.- Yep, let your outrage flow through you.
- The BEncode spec does not implement an encoding for
nil
/null
values, so they are treated as a malformed input.
- Sets are not allowed.
-
float
,decimal
, and other floating-point numbers are not allowed -
map
keys are coerced to strings. Complex values (lists, maps) and numbers are not allowed as keys.
But I'm not an evil taskmaster. I bend.
- Map keys can be keywords. However they are converted to strings via
name
. This truncates the namespace from namespaced keywords.- A future improvement might allow for deserializing map keys to keywords.
- Vectors are automatically converted to lists.
Decoding
In keeping with a portable implementation, deserialize
operates on vanilla Clojure strings.
Contrary to the Wikipedia entry, BEncode does not have the bijection property. List item order is undefined [1] [2]. Beware comparing either serialized or deserialized values.
Development
The test suite is built in CLJC, and is run under both Clojure and Clojurescript.
The Clojurescript unit tests require NodeJS to run. Otherwise only Leiningen is required.
-
lein test
runs the tests under Clojure. -
lein cljs-test
runs the tests under Clojurescript and NodeJS. -
lein test-all
runs both Clojure and Clojurescript test suite. -
lein cljs-auto-test
automatically compiles and runs the Clojurescript tests on every change. - The Clojure REPL can run the unit tests as well by calling
(run-tests)
in thebencode-cljc.core-test
namespace.
License
Copyright © 2017 James Leonis
Distributed under the EPLv2 license. See LICENSE file.