© 2012 Relevance Inc
edn2023 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.
If the edn gem is installed it should be uninstalled:
$ gem uninstall edn
Add this line to your application's Gemfile:
gem 'edn2023'
And then execute:
$ bundle
Or install it yourself as:
$ gem install edn2023
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.
To read a string of EDN:
require '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.
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
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.
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.
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.
To register a tag for reading, call the method EDN.register with a tag and one of the following:
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 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]"
Certain elements of EDN can have metadata. Metadata is a map of values about the element, which must follow specific rules.
Metadata can be expressed in one of the following three ways:
^) prefixed to it, like so: ^{:doc "This is my vector" :rel :temps} [98.6 99.7].^:awesome #{1 2 \c}. This results in the key :awesome being set to true, as if the metadata was: ^{:awesome true} #{1 2 \c}.^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.
git checkout -b my-new-feature)git commit -am 'Added some feature')git push origin my-new-feature)FAQs
Unknown package
We found that edn2023 demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.