File: README — Documentation for peanuts (2.1.4)

Introduction

*This is currently undergoing some rewrite. 2.x branch will introduce minor api incompatibilities.*

Upd: Ok, the thing is out and the example below has been updated for 2.x, but the rdocs are largely out of date and I’m not sure whether I should update them since it seems like nobody’s using this lib anyway.

Peanuts is an library that allows for bidirectional mapping between Ruby objects and XML.

Released under the MIT license.

Features

Type awareness (extensible).
XML namespaces support.
Pluggable backends to work with different XML APIs (REXML implemented so far).

Installation

Beta 2.x (recommended) and stable 1.x available from Gemcutter

gem install peanuts --source http://gemcutter.org

Usage

Please see an example below. See also Peanuts, Peanuts::ClassMethods

TODO

Inheritance
Mixins
More mappings?
More types?

Docs

rdoc.info/projects/omg/peanuts

Bugs & such

Please report via Github issue tracking.

Example

See also gist.github.com/230202 for real world example.

class Cheezburger
  include Peanuts

  attribute :weight, :float
  attribute :price, :decimal

  def initialize(weight = nil, price = nil)
    @weight, @price = weight, price
  end

  def eql?(other)
    other && weight == other.weight && price == other.price
  end

  alias == eql?
end

class Paws
  include Peanuts

  elements :paws, :name => :paw, :ns => 'urn:x-lol'
end

class Cat
  include Peanuts

  namespaces :lol => 'urn:x-lol', :kthnx => 'urn:x-lol:kthnx'

  root 'kitteh', :ns => 'urn:x-lol'

  attribute :has_tail?, :boolean, :name => 'has-tail', :ns => :kthnx
  attribute :ears, :integer

  element :ration, [:string], :name => :eats, :ns => :kthnx
  element :name, :ns => 'urn:x-lol:kthnx'

  shallow :paws, Paws

  shallow :pals, :ns => :kthnx do
    elements :friends, :name => :pal
  end

  element :cheezburger, Cheezburger
  element :moar_cheezburgers do
    elements :cheezburger, Cheezburger
  end
end

xml_fragment = <<-EOS
    <kitteh xmlns='urn:x-lol' xmlns:kthnx='urn:x-lol:kthnx' ears=' 2 ' kthnx:has-tail=' yes  '>
      <name xmlns='urn:x-lol:kthnx'>
          Silly
          Tom
      </name>
      <kthnx:eats>
        tigers
        lions
      </kthnx:eats>
      <kthnx:pals>
        <pal>Chrissy</pal>
        <pal>Missy</pal>
        <pal>Sissy</pal>
      </kthnx:pals>
      <paws>
        <paw>  one</paw>
        <paw> two </paw>
        <paw>three</paw>
        <paw>four</paw>
      </paws>
      <cheezburger price='2.05' weight='14.5547' />
      <moar_cheezburgers>
        <cheezburger price='19' weight='685.940' />
        <cheezburger price='7.40' weight='9356.7' />
      </moar_cheezburgers>
    </kitteh>
EOS
cat = Cat.restore_from(xml_fragment)
cheezburger = cat.cheezburger

assert_equal 'Silly Tom', cat.name
assert_equal %w(tigers lions), cat.ration
assert_equal ['Chrissy', 'Missy', 'Sissy'], cat.friends.names
assert_equal 2, cat.ears
assert_equal true, cat.has_tail
assert_equal %w(one two three four), cat.paws
assert_kind_of Cheezburger, cat.cheezburger
assert_equal 2, cat.cheezburger.weight
...
puts cat.save_to(:string)