Skip to content
XML/JSON representations of your Ruby objects
Ruby
Latest commit 7e1bb76 May 24, 2013 @mdub Update rake and rspec.
Failed to load latest commit information.
benchmark Add Jbuilder example to benchmarks. Aug 21, 2012
examples Simplify example. Jul 30, 2011
lib Release! Aug 21, 2012
spec Support numeric JSON :indentation. Aug 21, 2012
.document Set up documentation using YARD. Oct 14, 2009
.gitignore Use Bundler to lock down gems. Sep 13, 2010
.rspec Make RSpec output colourful. Nov 2, 2012
.travis.yml Integrate Travis CI. Feb 27, 2012
Gemfile Update rake and rspec. May 24, 2013
LICENSE
README.markdown Avoid confusing use of OpenStruct in example. Jul 29, 2011
Rakefile Upgrade to RSpec 2. May 26, 2011
representative.gemspec Move all development dependencies to Gemfile. Mar 13, 2012

README.markdown

Representative

"Representative" makes it easier to create XML or JSON representations of your Ruby objects.

It works best when you want the output to roughly follow the object structure, but still want complete control of the result.

Generating XML

Given a Ruby data-structure:

@books = [
  Book.new(
    :title => "Sailing for old dogs", 
    :authors => ["Jim Watson"],
    :published => Publication.new(
      :by => "Credulous Print",
      :year => 1994
    )
  ),
  Book.new(
    :title => "On the horizon", 
    :authors => ["Zoe Primpton", "Stan Ford"],
    :published => Publication.new(
      :by => "McGraw-Hill",
      :year => 2005
    )
  ),
  Book.new(
    :title => "The Little Blue Book of VHS Programming",
    :authors => ["Henry Nelson"],
    :rating => "****"
  )
]

Representative::Nokogiri can be used to generate XML:

xml = Representative::Nokogiri.new do |r|

  r.list_of :books, @books do
    r.element :title
    r.list_of :authors
    r.element :published do
      r.element :by
      r.element :year
    end
  end

end

puts xml.to_s

which produces:

<books type="array">
  <book>
    <title>Sailing for old dogs</title>
    <authors type="array">
      <author>Jim Watson</author>
    </authors>
    <published>
      <by>Credulous Print</by>
      <year>1994</year>
    </published>
  </book>
  <book>
    <title>On the horizon</title>
    <authors type="array">
      <author>Zoe Primpton</author>
      <author>Stan Ford</author>
    </authors>
    <published>
      <by>McGraw-Hill</by>
      <year>2005</year>
    </published>
  </book>
  <book>
    <title>The Little Blue Book of VHS Programming</title>
    <authors type="array">
      <author>Henry Nelson</author>
    </authors>
    <published/>
  </book>
</books>

Notice that:

  • The structure of the output mirrors the structure described by the nested Ruby blocks.
  • Representative walks the object-graph for you.
  • Using list_of for a collection attribute generates an "array" element, which plays nicely with most Ruby XML-to-hash converters.
  • Where a named object-attribute is nil, you get an empty element.

Generating JSON

Representative::Json can be used to generate JSON, using exactly the same DSL:

json = Representative::Json.new do |r|

  r.list_of :books, @books do
    r.element :title
    r.list_of :authors
    r.element :published do
      r.element :by
      r.element :year
    end
  end

end

puts json.to_s

producing:

[
  {
    "title": "Sailing for old dogs",
    "authors": [
      "Jim Watson"
    ],
    "published": {
      "by": "Credulous Print",
      "year": 1994
    }
  },
  {
    "title": "On the horizon",
    "authors": [
      "Zoe Primpton",
      "Stan Ford"
    ],
    "published": {
      "by": "McGraw-Hill",
      "year": 2005
    }
  },
  {
    "title": "The Little Blue Book of VHS Programming",
    "authors": [
      "Henry Nelson"
    ],
    "published": null
  }
]

Installation

Representative is packaged as a Gem. Install with:

gem install representative

Ruby on Rails integration

A separate gem, RepresentativeView, integrates Representative as an ActionPack template format.

Tilt integration

Representative includes integration with Tilt, which can be enabled with:

require "representative/tilt_integration"

This registers handlers for ".xml.rep" and ".json.rep" templates.

Copyright

Copyright (c) 2009 Mike Williams. See LICENSE for details.

Similar projects

If Representative is not your cup of tea, you may prefer:

Just don't go back to using "this_thing.to_xml" and "that_thing.to_json", m'kay?

Something went wrong with that request. Please try again.