README.md

Go implementation of EDN, extensible data notation

go-edn is a Golang library to read and write EDN (extensible data notation), a subset of Clojure used for transferring data between applications, much like JSON or XML. EDN is also a very good language for configuration files, much like a JSON-like version of YAML.

This library is heavily influenced by the JSON library that ships with Go, and people familiar with that package should know the basics of how this library works. In fact, this should be close to a drop-in replacement for the encoding/json package if you only use basic functionality.

This implementation is complete, stable, and presumably also bug free. This is why you don't see any changes in the repository.

If you wonder why you should (or should not) use EDN, you can have a look at the why document.

Installation and Usage

The import path for the package is olympos.io/encoding/edn

To install it, run:

go get olympos.io/encoding/edn

To use it in your project, you import olympos.io/encoding/edn and refer to it as edn like this:

import "olympos.io/encoding/edn"

//...

edn.DoStuff()

The previous import path of this library was gopkg.in/edn.v1, which is still permanently supported.

Quickstart

You can follow http://blog.golang.org/json-and-go and replace every occurence of JSON with EDN (and the JSON data with EDN data), and the text makes almost perfect sense. The only caveat is that, since EDN is more general than JSON, go-edn stores arbitrary maps on the form map[interface{}]interface{}.

go-edn also ships with keywords, symbols and tags as types.

For a longer introduction on how to use the library, see introduction.md. If you're familiar with the JSON package, then the API Documentation might be the only thing you need.

Example Usage

Say you want to describe your pet forum's users as EDN. They have the following types:

type Animal struct {
	Name string
	Type string `edn:"kind"`
}

type Person struct {
	Name      string
	Birthyear int `edn:"born"`
	Pets      []Animal
}

With go-edn, we can do as follows to read and write these types:

import "olympos.io/encoding/edn"

//...


func ReturnData() (Person, error) {
	data := `{:name "Hans",
              :born 1970,
              :pets [{:name "Cap'n Jack" :kind "Sparrow"}
                     {:name "Freddy" :kind "Cockatiel"}]}`
	var user Person
	err := edn.Unmarshal([]byte(data), &user)
	// user '==' Person{"Hans", 1970,
	//             []Animal{{"Cap'n Jack", "Sparrow"}, {"Freddy", "Cockatiel"}}}
	return user, err
}

If you want to write that user again, just Marshal it:

bs, err := edn.Marshal(user)

Dependencies

go-edn has no external dependencies, except the default Go library. However, as it depends on math/big.Float, go-edn requires Go 1.5 or higher.

License

Copyright © 2015-2019 Jean Niklas L'orange and contributors

Distributed under the BSD 3-clause license, which is available in the file LICENSE.