Have ideas to improve npm?Join in the discussion! »

    jsedn

    0.4.1 • Public • Published

    jsedn

    A javascript implementation of edn. To see it in action checkout the edn playground. If you open your browser console you will have access to a global jsedn object with which you can try things beside JSON encoding. I recommend jsedn.unify("[?x was always better than ?y]", {x: "sonic", y: "mario"}).jsEncode().

    Build Status npm version Coverage Status

    Getting Started

    Install

    npm install jsedn

    Use in a web page directly

    Use jsedn.js, which is a standalone version that will provide a global "jsedn".

    Code

    var edn = require("jsedn");
    var map = edn.parse("{:a 5 [1 2] {:name :mike :age 40}}");
    console.log(map.at(new edn.Vector([1, 2])).at(edn.kw(":name")));

    Will output "mike".

    Now the other way:

    edn.encode({a: 1, "id": 333});

    Will output:

    {"a" 1 "id" 333} 

    Finally lets encode js into edn then back to js:

    edn.parse(edn.encode({
        a: 1, 
        b: {
            age: 30, 
            feeling: ["electric", "pink"]
        }
    })).at("b").at("feeling").at(0)

    Will output "electric". Definitely working in both directions.

    Command Line

    If you have installed via npm you will have a jsedn script that accepts input via pipe/stdin. Currently takes:

    • -s flag for "select" which you pass a path separated by space
    • -j encodes input as JSON
    • -p indicates pretty print for json output
    > echo "{:a first-item :b [{:name :walter :age 50 :kids [:A :B :C]}]}" | jsedn -s ":b 0 :kids 2"
    outputs: :b 0 :kids 2 => :C

    Testing

    I have developed this in a very test driven manner e.g. each test written before the next feature is implemented. Baring that in mind it means any bugs you find it would be awesome if you could edit the tests adding one which clearly indicates the bug/feature request.

    npm install
    git submodule update --init
    npm test

    API

    parse (ednString)

    Will turn a valid edn string into a js object structure based upon the classes details below.

    edn.parse("{:a-keyword! [1 2 -3.4]}");
    encode (jsObj)

    Will encode both native JS and any object providing a ednEncode method.

    edn.encode({"a-keyword!": [1,2,-3.4]});
    setTagAction (tag, action)

    Will add the tag action to be performed on any data prepended by said tag.

    edn.setTagAction(new edn.Tag('myApp', 'tagName'), function(obj) {
        //do stuff with obj here and then return it
        var mutatedObj = thingsHandlerDoes(obj);
        return mutatedObj;
    });
    setTokenPattern (tokenName, pattern)

    If for some reason you would like to over-ride or add a new token pattern.

    edn.setTokenPattern()))
    setTokenAction (tokenName, actionCallback)

    Allows for customization of token handling upon match. For instance if you decided you would prefer nil to be represented by undefined instead of null (default).

    edn.setTokenAction('nil', function(token) { return undefined;});
    setTypeClass (type, class)

    This is useful if you want to over-ride the naive implementations of Map etc.

    edn.setTypeClass('List', MyListClass));
    atPath (obj, path)

    Simple way to lookup a value in elements returned from parse.

    var parsed = edn.parse("[[{:name :frank :kids [{:eye-color :red} {:eye-color :blue}]}]]");
    edn.atPath(parsed, "0 0 :kids 1 :eye-color");

    path is a space separated string which consists of index (remember Array/Set/Vector are all 0 indexed) and key locations.

    encodeJson

    Provides a json encoding including type information e.g. Vector, List, Set etc.

    console.log(edn.encodeJson(edn.parse("[1 2 3 {:x 5 :y 6}]")));

    yields:

    {"Vector":[1,2,3,{"Map":[{"Keyword": ":x"},5,{"Keyword":":y"},6]}]}
    toJS

    Attempts to return a "plain" js object. Bear in mind this will yield poor results if you have any Map objects which utilize composite objects as keys. If an object has a hashId method it will use that when building the js dict.

    var jsobj = edn.toJS(edn.parse("[1 2 {:name {:first :ray :last :cappo}}]"));

    yields:

    [1, 2, {":name": {":first": ":ray", ":last": ":cappo"}}]

    Notice that you can not always go back the other direction. In the example above if you were to edn.parse it you would end up with:

    [1 2 {":name" {":first" ":ray" ":last" ":cappo"}}] 

    In which you have strings for keys instead of keywords. At one point I would "infer" that if a string started with a ":" it would be treated as a keyword. This caused more problems than it resolved which brings us to our next methods.

    kw (string)

    Interns a valid keyword into an edn.Keyword object e.g:

    edn.kw(":myns/kw")
    sym (string)

    Interns a valid symbol into an edn.Symbol object e.g:

    edn.sym("?name")
    unify (data, values, [tokenStart])

    Unifies the first form with the second. Useful for populating a "data template". It accepts either edn objects or strings as arguments.

    edn.unify("{?key1 ?key1-val ?key2 ?key2-val :all [?key1-val ?key2-val]}", "{key1 :x key1-val 200 key2 :y key2-val 300}");

    yields:

    {:x 200 :y 300 :all [200 300]} 

    A third argument is expected which can be used to indicate the "tokenStart" first character for unify tokens. This defaults to "?".

    An example with Map as data and js obj as values and changing the tokenStart to $

    edn.unify(new edn.Map([edn.kw(":place"), edn.sym("$place")]), {place: "salt lake city"}, "$");

    yields:

    {:place "salt lake city"} 

    Classes/Interfaces

    Symbol

    Used to create symbols from with in js for encoding into edn.

    Keyword

    As above but for keywords. Note that the constructor enforced that keywords start with a ":" character.

    Iterable [List Vector Set]

    List, Vector and Set all implement the following methods:

    • exists (key) -> boolean indicating existance of key
    • at (key) -> value at key in collection
    • set (key, val) -> sets key/index to given value
    • each (iter) -> iterate overa all members calling iter on each, returns results
    • map (iter) -> iterate over all members calling iter on each and returning a new instace of self
    • walk (iter) -> recursively walk the data returning a new instance of self

    Map

    Supports any type of object as key. Supports all of the methods listed for Iterable plus indexOf which returns the index of the item, which can be 0 and thus non-truthy.

    each, map and walk all accept a callback which takes the value as the first argument and the key as the second. In the case of map and walk if you want to modify the key you must return a Pair object e.g.

    edn.parse("{:x 300 y: 800}").map(function(val, key){
        return new edn.Pair(edn.kw("#{key}-squared"), val * val);
    });

    yields:

    {:x-squared 90000 :y-squared 640000} 

    Tag

    Used for defining Tag Actions. Has a constructor which accepts 2..n args where the first arg is your a namespace and the rest are used to categorize the tag. Tag provides two methods ns and dn:

    var tag = new edn.Tag('myApp', 'people', 'special', 'stuff');
    console.log(tag.ns()); => myApp
    console.log(tag.dn()); => myApp/people/special/stuff

    Constructor also supports being passed single argument delimited by / e.g:

    new edn.Tag('myApp/people/special/stuff')

    Tagged

    If you do not have tag handlers specified for a given tag you will end up with Tagged items in your result which have two methods:

    tag() -> Tag object found
    obj() -> Object to be tagged
    

    Tagged pairs can also be used when you want to serialize a js obj into edn w/ said tagging e.g.

    edn.encode(new edn.Tagged(new edn.Tag("myApp", "Person"), {name: "walter", age: 300}));

    outputs:

    #myApp/person {"name" "walter" "age" 300} 

    Conversion Table

    element edn jsedn js
    nil nil null null
    boolean true false true false true false
    character \c "c" "c"
    string "some string" "some string" "some string"
    symbol ?sym~b~o!ol edn.sym "?sym~b~o!ol" "?sym~b~o!ol"
    keywords :keyword edn.kw ":keyword" ":keyword"
    integer 666 666 666
    floating point -6.66 -6.66 -6.66
    list (a b (c d)) new edn.List([edn.sym("a"), edn.sym("b"), new edn.List([edn.sym("c"), edn.sym("d")])]) ["a", "b", ["c", "d"]]
    vector [a b c] new edn.Vector([edn.sym("a"), edn.sym("b"), edn.sym("c")]) ["a", "b", "c"]
    map {:a 1 :b 2} new edn.Map([edn.kw(":a"), 1, edn.kw(":b"), 2]) {a: 1, b: 2}
    set #{1 2 3} new edn.Set([1, 2, 3]) [1 2 3]
    tagged elements #tagName [1 2] new edn.Tagged(new edn.Tag("tagName"), new edn.Vector([1, 2])) n/a

    Install

    npm i jsedn

    DownloadsWeekly Downloads

    1,252

    Version

    0.4.1

    License

    none

    Last publish

    Collaborators

    • avatar
    • avatar