117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# Go implementation of EDN, extensible data notation
|
|
|
|
[](https://godoc.org/olympos.io/encoding/edn)
|
|
|
|
go-edn is a Golang library to read and write
|
|
[EDN](https://github.com/edn-format/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](docs/why.md) document.
|
|
|
|
## Installation and Usage
|
|
|
|
The import path for the package is `olympos.io/encoding/edn`
|
|
|
|
To install it, run:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```go
|
|
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](docs/introduction.md). If you're familiar with the JSON
|
|
package, then the [API Documentation](https://godoc.org/olympos.io/encoding/edn) 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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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](https://github.com/go-edn/edn/graphs/contributors)
|
|
|
|
Distributed under the BSD 3-clause license, which is available in the file
|
|
LICENSE.
|