• Stars
    star
    119
  • Rank 297,930 (Top 6 %)
  • Language
    Ruby
  • License
    MIT License
  • Created about 12 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ruby implementation of Extensible Data Notation as defined by Rich Hickey

edn-ruby

Build Status

© 2012 Relevance Inc

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

Note that you might also want to look at edn_turbo which provides a much faster EDN parser (It's written in C) with an interface that is largely compatible with ths gem.

Usage

To read a string of EDN:

EDN.read('[1 2 {:foo "bar"}]')

Alternatively you can pass in an IO instance, for example an open file:

File.open("data.edn") do |f|
  data = EDN.read(f)
  # Do something with data
end

By default EDN.read will throw an execption if you try to read past the end of the data:

EDN.read("")   # Boom!

Alternatively, the EDN.read method takes an optional parameter, which is the value to return when it hits the end of data:

EDN.read("", :nomore)

#=> :nomore

There is no problem using nil as an eof value.

EDN::Reader

You can also do things in a more object oriented way by creating instances of EDN::Reader:

r = EDN::Reader.new('[1 2 3] {:a 1 :b 2}')

r.read #=> [1, 2, 3]
r.read #=> {:a => 1, :b => 2}
r.read #=> RuntimeError: Unexpected end of file

EDN:Reader will also take an IO instance:

r = EDN::Reader.new(open("data.edn"))

r.read  # Read the first form from the file.
r.read  # Read the second form from the file.
r.read  # Read the third from from the file.

You can also iterate through the forms with each:

r = EDN::Reader.new('[1 2 3] {:a 1 :b 2}')

r.each do |form|
  p form
end

#=> [1, 2, 3]
#=> {:a => 1, :b => 2}

Note that in contrast to earlier versions of this gem, EDN::Reader is no longer Enumerable.

Like EDN.read, Reader.read also takes an optional parameter, which is returned when there is no more data:

r = EDN::Reader.new('1 2 3')
r.read(:eof)  # returns 1
r.read(:eof)  # returns 2
r.read(:eof)  # returns 3
r.read(:eof)  # returns :eof

Converting Ruby data to EDN

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.

Value Translations

Note that EDN uses its own terminology for the types of objects it represents and in some cases those types not map cleanly to Ruby.

In EDN, you have keywords, which look like Ruby symbols and have the same meaning and purpose. These are converted to Ruby symbols.

You also have EDN symbols, which generally reflect variable names, but have several purposes. We parse these and return EDN::Type::Symbol values for them, as they don't map to anything built into Ruby. To create an EDN symbol in Ruby, call EDN::Type::Symbol.new or EDN.symbol with a string argument, or use the convenience unary operator ~ like so: ~"elf/rings".

EDN also has vectors, which map to Ruby arrays, and lists, which are linked lists in Clojure. We map EDN lists to EDN::Type::List values, which are type-compatible with arrays. To create an EDN list in Ruby, call EDN::Type::List.new or EDN.list with all arguments to go in the list. If you have an array, you will use the splat operator, like so: EDN.list(*[1, 2, 3]). You can also use the ~ unary operator like so: ~[1, 2, 3].

EDN also has character types, but Ruby does not. These are converted into one-character strings.

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 an instance of EDN::Type::UUID.

Tags that are not registered generate a struct of the type EDN::Type::Unknown with the methods tag and value.

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.

Other examples are:

EDN.tagout("wolf/pack", {:alpha=>"Greybeard", :betas=>["Frostpaw", "Blackwind", "Bloodjaw"]})
 => "#wolf/pack {:alpha \"Greybeard\", :betas [\"Frostpaw\" \"Blackwind\" \"Bloodjaw\"]}"

class Range
  def to_edn
    EDN.tagout("ruby/range", [self.begin, self.end, self.exclude_end?])
  end
end

(0..9).to_edn
=> "#ruby/range [0 9 false]"

Metadata

Certain elements of EDN can have metadata. Metadata is a map of values about the element, which must follow specific rules.

  • Only symbols, lists, vectors, maps, and sets can have metadata. Tagged elements cannot have metadata.
  • Metadata keys must be symbols, keywords, or strings.

Metadata can be expressed in one of the following three ways:

  • Via a map. The element is prefixed with a map which has a caret (^) prefixed to it, like so: ^{:doc "This is my vector" :rel :temps} [98.6 99.7].
  • Via a keyword. The element is prefixed with a keyword, also prefixed by a caret: ^:awesome #{1 2 \c}. This results in the key :awesome being set to true, as if the metadata was: ^{:awesome true} #{1 2 \c}.
  • Via a symbol. The element is prefixed with a symbol, also prefixed by a caret: ^Boolean "true". This results in the key :tag being set to the symbol, as if the metadata was: ^{:tag Boolean} "true". This is used in Clojure to indicate the Java type of the element. In other EDN implementations, it may be ignored or used differently.

More than one piece of metadata can be applied to an element. Metadata is applied to the next element appearing after it, so in the case of ^:foo ^{:bar false} [1 2], the metadata would be, in total, ^{:foo true, :bar false}. Note that ^:foo is applied to the element [1 2] with the metadata ^{:bar false} applied to it. Because of this, key collisions are resolved right-to-left.

Contributors

  • Clinton N. Dreisbach (@crnixon)
  • Michael Ficarra (@michaelficarra)
  • Andrew Forward (@aforward)
  • Gabriel Horner (@cldwalker)
  • Russ Olsen (@russolsen)

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

More Repositories

1

labrepl

Clojure
504
star
2

tarantula

a big hairy fuzzy spider that crawls your site, wreaking havoc
Ruby
444
star
3

rcov

The new home of RCov on GitHub
Ruby
409
star
4

streamlined

Ruby
207
star
5

diametric

Diametric is a library for building schemas, queries, and transactions for Datomic from Ruby objects.
Ruby
169
star
6

org-html-slideshow

JavaScript presentation slides generated from Emacs org-mode
Clojure
160
star
7

functional-koans

A set of common ideas for learning functional programming
156
star
8

etc

bash scripts, aliases, other misc things go here
Shell
153
star
9

log_buddy

logbuddy is your friendly little log buddy by your side
Ruby
141
star
10

clojure-conj

134
star
11

cap_gun

Bang! You've deployed!
Ruby
115
star
12

castronaut

CAS Server
Ruby
101
star
13

mycroft

It's your data, look at it anywhere
Clojure
66
star
14

vasco

A route-explorer for Rails
JavaScript
57
star
15

hooppps

Ruby
56
star
16

boids

Boids flocking simulator in ClojureScript (for ClojureScript training)
JavaScript
38
star
17

blue-ridge-sample-app

Sample Rails project demonstrating JavaScript testing with Blue-Ridge
JavaScript
30
star
18

how_we_work

Relevance's How We Work site
JavaScript
22
star
19

java-tdd

TDD Examples, Labs, and References
Java
19
star
20

multi_rails

Test against many versions of Rails with a single command.
Ruby
19
star
21

spec_converter

Ruby
15
star
22

smoke_signals

CruiseControl.rb Campfire notifications
Ruby
11
star
23

cache_test

Fork of Damien Merenne's cache_test plugin. Updated to work with Rails 2.1.x.
10
star
24

jquery-demos

Demos and Presentation on jQuery
JavaScript
9
star
25

github_hook

Simple object wrapper around the Github post receive JSON payload.
Ruby
7
star
26

Iteration-Zero

Slides for Iteration Zero talk
5
star
27

clojure-async-blocks

Area to rough out async blocks in clojure
Clojure
5
star
28

prototaculous

sample code and presentation on Prototype and Scriptaculous
JavaScript
5
star
29

contegix-cloud-client

Contegix Cloud client API reference implementation
Ruby
5
star
30

relevance_rails

Relevance awesome sauce packaged up in an easy to use gem
Ruby
5
star
31

obsidian

It's metastable
Ruby
5
star
32

connectomatic

A simple gem that makes it easy to use multiple databases from Rails
Ruby
4
star
33

relevant-datetime

Datetime widget for Relevant
Ruby
4
star
34

relevant-hudson

Hudson widget for Relevant
Ruby
4
star
35

relevant-google-calendar

Google Calendar plugin for Relevant
Ruby
4
star
36

ending-legacy-code

Ending legacy code in our lifetime
4
star
37

koality

Runs opinionated code quality tools as part of you test stuite
Ruby
4
star
38

relevant-html

Simple html widget for Relevant
Ruby
3
star
39

automan

Let's just say it's awesome. Fair enough?
JavaScript
3
star
40

relevant-twitter

Twitter widget for the Relevant radiator
Ruby
3
star
41

boomstick

Boomstick tries to make it easier to explore Clojure and Datomic by generating an Ubuntu image containing a selection of Clojure editors, Datomic, and supporting software.
Shell
3
star
42

git-control

Git Control of Your Source (conference talk)
3
star
43

elzar

BAM!
Ruby
3
star
44

relevant-eventbrite-signups

Show event signups on Relevant
Ruby
3
star
45

jvm-shootout

JVM Shootout: Examples and presentation on various JVM languages
Clojure
3
star
46

relevant-widget

Base widget functionality for widgets
Ruby
3
star
47

relevant-github

View github feeds via Relevant
Ruby
3
star
48

rails-template

Build a Rails template for Relevance projects!
Ruby
3
star
49

relevance_portfolio_iteration_switcher

Simple switcher for navigating between iterations of projects in our portfolio.
Ruby
1
star
50

fluxion

Asynchronous metric collection, aggregation, and delivery
Clojure
1
star
51

slushy

Aussie kitchenhand helping in the provisional kitchen with Fog and Chef
Ruby
1
star
52

refactotum

Refactotum -- Presentation for RailsConf 2011 Refactotum Tutorial
1
star