peanuts 1.0 → 2.0.7

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 Igor Gunko
+Copyright (c) 2009 Igor Gunko
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,4 +1,11 @@
 === 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.
@@ -9,7 +16,8 @@ Released under the MIT license.
 - Pluggable backends to work with different XML APIs (REXML implemented so far).
 
 === Installation
-  gem install omg-peanuts --source http://gems.github.com
+Beta 2.x (recommended) and stable 1.x available from Gemcutter
+  gem install peanuts --source http://gemcutter.org
 
 === Usage
 Please see an example below.
@@ -31,7 +39,24 @@ Please report via Github issue tracking.
     class Cheezburger
       include Peanuts
 
-      attribute :weight, :integer
+      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
@@ -39,20 +64,24 @@ Please report via Github issue tracking.
 
       namespaces :lol => 'urn:x-lol', :kthnx => 'urn:x-lol:kthnx'
 
-      root 'kitteh', :xmlns => :lol
+      root 'kitteh', :ns => 'urn:x-lol'
 
-      attribute :has_tail, :boolean, :xmlname => 'has-tail', :xmlns => 'urn:x-lol:kthnx'
+      attribute :has_tail?, :boolean, :name => 'has-tail', :ns => :kthnx
       attribute :ears, :integer
 
-      element :ration, [:string], :xmlname => :eats, :xmlns => :kthnx
-      element :name, :string, :xmlns => 'urn:x-lol:kthnx'
-      elements :paws, :string, :xmlname => :paw
+      element :ration, [:string], :name => :eats, :ns => :kthnx
+      element :name, :ns => 'urn:x-lol:kthnx'
 
-      element :friends, :xmlname => :pals do # anonymous class definition follows within block
-        elements :names, :string, :xmlname => :friend, :xmlname => :pal
+      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
@@ -65,19 +94,26 @@ Please report via Github issue tracking.
             tigers
             lions
           </kthnx:eats>
-          <pals>
+          <kthnx:pals>
             <pal>Chrissy</pal>
             <pal>Missy</pal>
             <pal>Sissy</pal>
-          </pals>
-          <paw>  one</paw>
-          <paw> two </paw>
-          <paw>three</paw>
-          <paw>four</paw>
-          <cheezburger weight='2' />
+          </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.parse(xml_fragment)
+    cat = Cat.restore_from(xml_fragment)
+    cheezburger = cat.cheezburger
 
     assert_equal 'Silly Tom', cat.name
     assert_equal %w(tigers lions), cat.ration
@@ -88,17 +124,12 @@ Please report via Github issue tracking.
     assert_kind_of Cheezburger, cat.cheezburger
     assert_equal 2, cat.cheezburger.weight
     ...
-    puts cat.build
+    puts cat.save_to(:string)
 
 
 === See also
-* http://github.com/omg/threadpool -- Thread pool implementation
-* http://github.com/omg/statelogic -- A simple state machine for ActiveRecord
-
-
-
-Free hint: If you liek mudkipz^W^Wfeel like generous today you can tip me at http://tipjoy.com/u/pisuka
-
+* http://github.com/omg/unrest     -- REST-client
+* http://github.com/omg/statelogic -- Simple state machine for ActiveRecord
 
 Copyright (c) 2009 Igor Gunko, released under the MIT license
 

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake'
 require 'rake/clean'
 require 'rake/gempackagetask'
 require 'rake/rdoctask'
-require 'rake/testtask'
+require 'spec/rake/spectask'
 
 Rake::GemPackageTask.new(Gem::Specification.load('peanuts.gemspec')) do |p|
   p.need_tar = true
@@ -18,9 +18,12 @@ Rake::RDocTask.new do |rdoc|
   rdoc.main = "README.rdoc" # page to start on
   rdoc.title = "Peanuts Documentation"
   rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
-  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--line-numbers'
 end
 
-Rake::TestTask.new do |t|
-  t.test_files = FileList['test/**/*.rb']
+desc 'Run specs'
+task :test => :spec
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*.rb']
 end

data/lib/peanuts/converters.rb

@@ -8,7 +8,7 @@ module Peanuts
   # numeric::     see +Convert_integer+, +Convert_decimal+, +Convert_float+
   # date & time:: see +Convert_datetime+
   # lists::       see +Convert_list+
-  module Converter
+  class Converter
     def self.lookup(type)
       lookup!(type)
     rescue ArgumentError
@@ -16,9 +16,11 @@ module Peanuts
     end
 
     def self.lookup!(type)
-      const_get("Convert_#{type}")
-    rescue NameError
-      raise ArgumentError, "converter not found for #{type}"
+      begin
+        const_get("Convert_#{type}")
+      rescue NameError
+        raise ArgumentError, "converter not found for #{type}"
+      end
     end
 
     def self.create(type, options)
@@ -28,11 +30,16 @@ module Peanuts
     end
 
     def self.create!(type, options)
-      lookup!(type).new(options)
+      case type
+      when Symbol
+        lookup!(type)
+      else
+        type
+      end.new(options)
     end
 
     # Who could have thought... a string.
-    # 
+    #
     # Specifier:: <tt>:string</tt>
     #
     # ==== Options:
@@ -41,7 +48,7 @@ module Peanuts
     #   [<tt>:trim</tt>] Trim whitespace from both ends.
     #   [<tt>:collapse</tt>] Collapse consecutive whitespace + trim as well.
     #   [<tt>:preserve</tt>] Keep'em all.
-    class Convert_string
+    class Convert_string < Converter
       def initialize(options)
         @whitespace = options[:whitespace] || :collapse
       end
@@ -83,8 +90,8 @@ module Peanuts
       def to_xml(flag)
         return nil if flag.nil?
         string = case @format
-        when :true_false then flag ? 'true' : 'false'
-        when :yes_no then flag ? 'yes' : 'no'
+        when :true_false, :truefalse then flag ? 'true' : 'false'
+        when :yes_no, :yesno then flag ? 'yes' : 'no'
         when :numeric then flag ? '0' : '1'
         end
         super(string)
@@ -114,7 +121,7 @@ module Peanuts
     # An integer.
     #
     # Specifier:: <tt>:integer</tt>
-    # 
+    #
     # ==== Options
     # Accepts all options of +Convert_string+.
     class Convert_integer < Convert_string
@@ -135,7 +142,7 @@ module Peanuts
     #
     # Specifier:: <tt>:decimal</tt>
     # Ruby type:: +BigDecimal+
-    # 
+    #
     # ==== Options
     # Accepts all options of +Convert_string+.
     class Convert_decimal < Convert_string
@@ -180,7 +187,7 @@ module Peanuts
     #
     # Specifier:: <tt>:datetime</tt>
     # Ruby type:: +Time+
-    # 
+    #
     # ==== Options
     # Accepts all options of +Convert_string+.
     class Convert_datetime < Convert_string
@@ -206,7 +213,7 @@ module Peanuts
     #
     # ==== Options
     # All options will be passed to the underlying type converter.
-    class Convert_list
+    class Convert_list < Converter
       def initialize(options)
         @item_type = options[:item_type] || :string
         @item_converter = Converter.create!(@item_type, options)

data/lib/peanuts/mappable.rb

@@ -0,0 +1,253 @@
+require 'peanuts/xml'
+require 'peanuts/mappings'
+require 'peanuts/mapper'
+
+module Peanuts #:nodoc:
+  # See also +MappableType+
+  module MappableObject
+    def self.included(other) #:nodoc:
+      MappableType.init(other)
+    end
+
+    def from_xml(source, options = {})
+      source = XML::Reader.new(source, options) unless source.is_a?(XML::Reader)
+      e = source.find_element
+      e && self.class.mapper.read(self, source)
+    end
+
+    #    save_to(:string|:document[, options])      -> new_string|new_document
+    #    save_to(string|iolike|document[, options]) -> string|iolike|document
+    #
+    # Defines attribute mapping.
+    #
+    # [+options+] Backend-specific options
+    #
+    # === Example:
+    #    cat = Cat.new
+    #    cat.name = 'Pussy'
+    #    puts cat.save_to(:string)
+    #    ...
+    #    doc = LibXML::XML::Document.new
+    #    cat.save_to(doc)
+    #    puts doc.to_s
+    def to_xml(dest = :string, options = {})
+      dest = XML::Writer.new(dest, options) unless dest.is_a?(XML::Writer)
+      self.class.mapper.write(self, dest)
+      dest.result
+    end
+  end
+
+  # See also +MappableObject+.
+  module MappableType
+    include Mappings
+
+    def self.init(cls, ns_context = nil, default_ns = nil, &block) #:nodoc:
+      cls.instance_eval do
+        extend MappableType
+        @mapper = Mapper.new(ns_context, default_ns)
+        instance_eval(&block) if block_given?
+      end
+      cls
+    end
+
+    #    mapper -> Mapper
+    #
+    # Returns the mapper for the class.
+    attr_reader :mapper
+
+    #    namespaces(hash) -> Hash
+    #    namespaces       -> Hash
+    #
+    # Updates and returns class-level prefix mappings.
+    # When given a hash of mappings merges it over current.
+    # When called withot arguments simply returns current mappings.
+    #
+    # === Example:
+    #    class Cat
+    #      include Peanuts
+    #      namespaces :lol => 'urn:lol', ...
+    #      ...
+    #    end
+    def namespaces(*args)
+      case args.size
+      when 0
+        mapper.namespaces
+      when 1
+        if args.first.is_a?(Hash)
+          mapper.namespaces.update(args.first)
+        else
+          mapper.default_ns = args.first
+        end
+      when 2
+        mapper.default_ns = args.first
+        mapper.namespaces.update(args[1])
+      else
+        raise ArgumentError, 'bad arguments'
+      end
+    end
+
+    #    root(local_name[, :ns => ...]) -> Mappings::Root
+    #    root                           -> Mappings::Root
+    #
+    # Defines element name.
+    # TODO: moar details
+    #
+    # [+local_name+] Element name
+    # [+options+] <tt>:ns => 'uri'|:prefix</tt> Element namespace
+    #
+    # === Example:
+    #    class Cat
+    #      include Peanuts
+    #      ...
+    #      root :kitteh, :ns => 'urn:lol'
+    #      ...
+    #    end
+    def root(local_name = nil, options = {})
+      mapper.root = Root.new(local_name, prepare_options(:root, options)) if local_name
+      mapper.root
+    end
+
+    #    element(name[, type][, options])   -> mapping_object
+    #    element(name[, options]) { block }  -> mapping_object
+    #
+    # Defines single-element mapping.
+    #
+    # [+name+]    Accessor name
+    # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+    # [+options+] <tt>name</tt>, <tt>:ns</tt>, converter options (see +Converter+).
+    # [+block+]   An anonymous class definition.
+    #
+    # === Example:
+    #    class Cat
+    #      include Peanuts
+    #      ...
+    #      element :name, :whitespace => :collapse
+    #      element :ears, :integer
+    #      element :cheeseburger, Cheeseburger, :name => :cheezburger
+    #      ...
+    #    end
+    def element(name, *args, &block)
+      add_mapping(:element, name, *args, &block)
+    end
+
+    #    shallow_element(name, type[, options])     -> mapping_object
+    #    shallow_element(name[, options]) { block }  -> mapping_object
+    #
+    # Defines single-element shallow mapping.
+    #
+    # [+name+]    Accessor name
+    # [+type+]    Element type. Either this or _block_ is required.
+    # [+options+] <tt>:name</tt>, <tt>:ns</tt>, converter options (see +Converter+).
+    # [+block+]   An anonymous class definition.
+    #
+    # === Example:
+    #    class Cat
+    #      include Peanuts
+    #      ...
+    #      shallow :friends do
+    #        element :friends, :name => :friend
+    #      end
+    #      shallow :cheeseburger, Cheeseburger, :name => :cheezburger
+    #      ...
+    #    end
+    def shallow_element(name, *args, &block)
+      add_mapping(:shallow_element, name, *args, &block)
+    end
+
+    alias shallow shallow_element
+
+    #    elements(name[, type][, options])   -> mapping_object
+    #    elements(name[, options]) { block }  -> mapping_object
+    #
+    # Defines multiple elements mapping.
+    #
+    # [+name+]    Accessor name
+    # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+    # [+options+] <tt>name</tt>, <tt>:ns</tt>, converter options (see +Converter+).
+    # [+block+]   An anonymous class definition.
+    #
+    # === Example:
+    #    class RichCat
+    #      include Peanuts
+    #      ...
+    #      elements :ration, :string, :whitespace => :collapse
+    #      elements :cheeseburgers, Cheeseburger, :name => :cheezburger
+    #      ...
+    #    end
+    def elements(name, *args, &block)
+      add_mapping(:elements, name, *args, &block)
+    end
+
+    #    attribute(name[, type][, options]) -> mapping_object
+    #
+    # Defines attribute mapping.
+    #
+    # [+name+]    Accessor name
+    # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+    # [+options+] <tt>name</tt>, <tt>:ns</tt>, converter options (see +Converter+).
+    #
+    # === Example:
+    #    class Cat
+    #      include Peanuts
+    #      ...
+    #      element :name, :string, :whitespace => :collapse
+    #      element :cheeseburger, Cheeseburger, :name => :cheezburger
+    #      ...
+    #    end
+    def attribute(name, *args)
+      add_mapping(:attribute, name, *args)
+    end
+
+    def schema(schema = nil)
+      mapper.schema = schema if schema
+      mapper.schema
+    end
+
+    def from_xml(source, options = {})
+      new.from_xml(source, options)
+    end
+
+    private
+    def object_type?(type)
+      type.is_a?(Class) && !(type < Converter)
+    end
+
+    def add_mapping(node, name, *args, &block)
+      type, options = *args
+      type, options = (block ? Class.new : :string), type if type.nil? || type.is_a?(Hash)
+
+      object_type = object_type?(type)
+      options = prepare_options(node, options || {})
+
+      mapper << m = case node
+      when :element
+        options.delete(:shallow) ? ShallowElement : (object_type ? Element : ElementValue)
+      when :elements
+        object_type ? Elements : ElementValues
+      when :attribute
+        Attribute
+      when :shallow_element
+        ShallowElement
+      end.new(name, type, options)
+
+      raise ArgumentError, 'bad type for shallow element' if !object_type && m.is_a?(ShallowElement)
+
+      default_ns = m.prefix ? mapper.default_ns : m.namespace_uri
+      if object_type && !type.is_a?(MappableType)
+        raise ArgumentError, 'block is required' unless block
+        MappableType.init(type, mapper.namespaces, default_ns, &block)
+      end
+      m.define_accessors(self)
+      m
+    end
+
+    def prepare_options(node, options)
+      ns = options.fetch(:ns) {|k| node == :attribute ? nil : options[k] = mapper.default_ns }
+      if ns.is_a?(Symbol)
+        raise ArgumentError, "undefined prefix: #{ns}" unless options[:ns] = mapper.namespaces[ns]
+        options[:prefix] = ns unless options.include?(:prefix)
+      end
+      options
+    end
+  end
+end

data/lib/peanuts/mapper.rb

@@ -0,0 +1,95 @@
+require 'enumerator'
+
+module Peanuts
+  class Mapper
+    include Enumerable
+
+    attr_reader :root, :namespaces, :ns_context
+    attr_accessor :default_ns, :schema
+
+    def initialize(ns_context = nil, default_ns = nil)
+      @ns_context, @default_ns = ns_context, default_ns
+      @mappings, @footprints = [], {}
+      @namespaces = ns_context ? Hash.new {|h, k| ns_context[k] || raise(IndexError) } : {}
+    end
+
+    def root=(root)
+      raise 'root already defined' if @root
+      # TODO raise 'root in nested scopes not supported' if nested?
+      @default_ns = root.namespace_uri unless root.prefix
+      @root = root
+    end
+
+    def each(&block)
+      @mappings.each(&block)
+    end
+
+    def <<(mapping)
+      fp = MappingFootprint.new(mapping)
+      raise "mapping already defined for #{fp}" if @footprints.include?(fp)
+      @mappings << (@footprints[fp] = mapping)
+    end
+
+    def define_accessors(type)
+      each {|m| m.define_accessors(type) }
+    end
+
+    def read(nut, reader)
+      rdfp = ReaderFootprint.new(reader)
+      reader.each do
+        m = @footprints[rdfp]
+        m.read(nut, reader) if m
+      end
+      nut
+    end
+
+    def write(nut, writer)
+      @root.write(writer) do |w|
+        w.write_namespaces('' => default_ns) if default_ns
+        w.write_namespaces(namespaces)
+        write_children(nut, w)
+      end
+      nil
+    end
+
+    def write_children(nut, writer)
+      each {|m| m.write(nut, writer) } if nut
+      nil
+    end
+
+    def clear(nut)
+      each {|m| m.clear(nut) }
+    end
+
+    private
+    class Footprint #:nodoc:
+      extend Forwardable
+
+      def_delegators :@obj, :node_type, :local_name, :namespace_uri
+
+      def initialize(obj)
+        @obj = obj
+      end
+
+      def hash
+        node_type.hash ^ local_name.hash ^ namespace_uri.hash
+      end
+
+      def to_s
+        "#{node_type}(#{local_name}, #{namespace_uri})"
+      end
+    end
+
+    class MappingFootprint < Footprint #:nodoc:
+      def eql?(other)
+        self.equal?(other) || other && @obj.matches?(other)
+      end
+    end
+
+    class ReaderFootprint < Footprint #:nodoc:
+      def eql?(mappingfp)
+        mappingfp.eql?(@obj)
+      end
+    end
+  end
+end