edn-ruby
edn-ruby is a Ruby library to read and write edn (extensible data notation), a subset of Clojure used for transferring data between applications, much like JSON, YAML, or XML.
Installation
Add this line to your application's Gemfile:
gem 'edn'
And then execute:
$ bundle
Or install it yourself as:
$ gem install edn
Usage
To read a string of edn:
EDN.read("[1 2 {:foo \"bar\"}]")
To convert a data structure to an edn string:
data.to_edn
By default, this will work for strings, symbols, numbers, arrays, hashes, sets, nil, Time, and boolean values.
Tagged Values
The interesting part of edn is the extensible part. Data can be be tagged to coerce interpretation of it to a particular data type. An example of a tagged data element:
#wolf/pack {:alpha "Greybeard" :betas ["Frostpaw" "Blackwind" "Bloodjaw"]}
The tag (#wolf/pack
) will tell any consumers of this data to use a data type registered to handle wolf/pack
to represent this data.
The rules for tags from the edn README should be followed. In short, custom tags should have a prefix (the part before the /
) designating the user that created them or context they are used in. Non-prefixed tags are reserved for built-in tags.
There are two tags built in by default: #uuid
, used for UUIDs, and #inst
, used for an instant in time. In edn-ruby
, #inst
is converted to a Time, and Time values are tagged as #inst
. There is not a UUID data type built into Ruby, so #uuid
is converted to a string, but if you require edn/uuid
, #uuid
values are converted to an instance of EDN::UUID
.
Tags that are not registered are converted as their base data type and a warning will be shown.
Registering a New Tag For Reading
To register a tag for reading, call the method EDN.register
with a tag and one of the following:
- A block that accepts data and returns a value.
- A lambda that accepts data and returns a value.
- A class that has an
initialize
method that accepts data.
Examples:
EDN.register("clinton/uri") do |uri|
URI(uri)
end
EDN.register("clinton/date", lambda { |date_array| Date.new(*date_array) }
class Dog
def initialize(name)
@name = name
end
end
EDN.register("clinton/dog", Dog)
Writing Tags
Writing tags should be done as part of the class's .to_edn
method, like so:
class Dog
def to_edn
["#clinton/dog", @name.to_edn].join(" ")
end
end
EDN
provides a helper method, EDN.tagout
:
class Dog
def to_edn
EDN.tagout("clinton/dog", @name)
end
end
This method calls .to_edn
on the second argument and joins the arguments appropriately.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request