pipa-xmlnuts 0.1 → 0.2

data/README.rdoc

@@ -1,24 +1,23 @@
 == Introduction
 XmlNuts 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 (only REXML implemented so far)
+- Type awareness (extensible).
+- XML namespaces support.
+- Pluggable backends to work with different XML APIs (REXML implemented so far).
 
 == Installation
- gem install pipa-xmlnuts --source http://gems.github.com
+  gem install pipa-xmlnuts --source http://gems.github.com
 
 == Usage
-TODO
-Please see example below.
+Please see an example below.
+See also +XmlNuts::Nut+, +XmlNuts::Nut::ClassMethods+
 
-== Issue tracking
+== Reporting bugs
 Please file bugs and feature requests at http://pipa.lighthouseapp.com/projects/21756-xmlnuts
 
-== License
-Released under the MIT license (included).
-
 == Example
     class Cheezburger
       include XmlNuts::Nut
@@ -37,7 +36,7 @@ Released under the MIT license (included).
       attribute :ears, :integer
 
       element :ration, [:string], :xmlname => :eats, :xmlns => :kthnx
-      element :name, :string, :whitespace => :collapse, :xmlns => 'urn:x-lol:kthnx'
+      element :name, :string, :xmlns => 'urn:x-lol:kthnx'
       elements :paws, :string, :xmlname => :paw
 
       element :friends, :xmlname => :pals do # anonymous class definition follows within block
@@ -47,75 +46,37 @@ Released under the MIT license (included).
       element :cheezburger, Cheezburger
     end
 
-    class ParsingTest < Test::Unit::TestCase
-      def setup
-        @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>
-              <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' />
-            </kitteh>
-        EOS
-        @cat = Cat.parse(@xml_fragment)
-      end
-
-      context "A cat" do
-        should 'be named Silly Tom' do
-          assert_equal 'Silly Tom Писда', @cat.name
-        end
-
-        should 'eat tigers and lions' do
-          assert_equal %w(tigers lions), @cat.ration
-        end
-
-        should 'be a friend of Chrissy, Missy & Sissy' do
-          assert_equal ['Chrissy', 'Missy', 'Sissy'], @cat.friends.names
-        end
-
-        should 'have 2 ears' do
-          assert_equal 2, @cat.ears
-        end
-
-        should 'have tail' do
-          assert_equal true, @cat.has_tail
-        end
-
-        should 'have four paws' do
-          assert_not_nil @cat.paws
-          assert_equal 4, @cat.paws.length
-          assert_equal %w(one two three four), @cat.paws
-        end
-
-        should 'has cheezburger' do
-          assert_kind_of Cheezburger, @cat.cheezburger
-        end
-      end
-
-      context 'A cheezburger' do
-        setup do
-          @burger = @cat.cheezburger
-        end
-
-        should 'weigh 2 pounds' do
-          assert_equal 2, @burger.weight
-        end
-      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>
+          <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' />
+        </kitteh>
+    EOS
+    cat = Cat.parse(xml_fragment)
+
+    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.build
+    puts cat.build

data/lib/xmlnuts/converters.rb

@@ -1,6 +1,13 @@
-require 'time'
-
 module XmlNuts
+  autoload :Time, 'time'
+  autoload :BigDecimal, 'bigdecimal'
+
+  # === Currently supported types:
+  # string::      see +Convert_string+
+  # boolean::     see +Convert_boolean+, +Convert_yesno+
+  # numeric::     see +Convert_integer+, +Convert_decimal+, +Convert_float+
+  # date & time:: see +Convert_datetime+
+  # lists::       see +Convert_list+
   module Converter
     def self.lookup(type)
       lookup!(type)
@@ -24,9 +31,19 @@ module XmlNuts
       lookup!(type).new(options)
     end
 
+    # Who could have thought... a string.
+    # 
+    # Specifier:: <tt>:string</tt>
+    #
+    # ==== Options:
+    # [<tt>:whitespace => :collapse</tt>]
+    #   Whitespace handling behavior.
+    #   [<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
       def initialize(options)
-        @whitespace = options[:whitespace] || :trim
+        @whitespace = options[:whitespace] || :collapse
       end
 
       def to_xml(string)
@@ -36,13 +53,26 @@ module XmlNuts
       def from_xml(string)
         return nil unless string
         string = case @whitespace
-        when :trim then string.gsub(/(\A\s*)|(\s*\Z)/, '')
+        when :trim then string.gsub(/\A\s*|\s*\Z/, '')
         when :preserve then string
         when :collapse then string.gsub(/\s+/, ' ').gsub(/\A\s*|\s*\Z|\s*(?=\s)/, '')
         end
       end
     end
 
+    # An XSD boolean.
+    #
+    # Specifier:: <tt>:boolean</tt>
+    #
+    # ==== Options:
+    # [<tt>:format => :true_false</tt>]
+    #   Format variation.
+    #   [<tt>:true_false</tt>] <tt>true/false</tt>
+    #   [<tt>:yes_no</tt>] <tt>yes/no</tt>
+    #   [<tt>:numeric</tt>] <tt>0/1</tt>
+    #   In addition supports all options of +Convert_string+.
+    #
+    # See also +Convert_yesno+.
     class Convert_boolean < Convert_string
       def initialize(options)
         super
@@ -52,16 +82,17 @@ module XmlNuts
 
       def to_xml(flag)
         return nil if flag.nil?
-        case @format
-        when :truefalse then flag ? 'true' : 'false'
-        when :yesno then flag ? 'yes' : 'no'
+        string = case @format
+        when :true_false then flag ? 'true' : 'false'
+        when :yes_no then flag ? 'yes' : 'no'
         when :numeric then flag ? '0' : '1'
         end
+        super(string)
       end
 
       def from_xml(string)
-        return nil unless string
         case string = super(string)
+        when nil then nil
         when '1', 'true', 'yes' then true
         when '0', 'false', 'no' then false
         else
@@ -70,20 +101,88 @@ module XmlNuts
       end
     end
 
+    # The same as +Convert_boolean+ but with the <tt>:yes_no</tt> default format.
+    #
+    # Specifier:: <tt>:yesno</tt>
+    class Convert_yesno < Convert_boolean
+      def initialize(options)
+        options[:format] ||= :yes_no
+        super
+      end
+    end
+
+    # An integer.
+    #
+    # Specifier:: <tt>:integer</tt>
+    # 
+    # ==== Options
+    # Accepts all options of +Convert_string+.
     class Convert_integer < Convert_string
       def initialize(options)
         super
       end
 
       def to_xml(int)
-        int.to_s
+        super(int.to_s)
+      end
+
+      def from_xml(string)
+        (string = super(string)) && Integer(string)
+      end
+    end
+
+    # A decimal.
+    #
+    # Specifier:: <tt>:decimal</tt>
+    # Ruby type:: +BigDecimal+
+    # 
+    # ==== Options
+    # Accepts all options of +Convert_string+.
+    class Convert_decimal < Convert_string
+      def initialize(options)
+        super
+      end
+
+      def to_xml(int)
+        super(int && int.to_s('F'))
+      end
+
+      def from_xml(string)
+        (string = super(string)) && BigDecimal.new(string)
+      end
+    end
+
+    # A float.
+    #
+    # Specifier:: <tt>:float</tt>
+    #
+    # ==== Options
+    # [<tt>:precision</tt>] Floating point precision.
+    #
+    # In addition accepts all options of +Convert_string+.
+    class Convert_float < Convert_string
+      def initialize(options)
+        super
+        @precision = options[:precision]
+        @format = @precision ? "%f.#{@precision}" : '%f'
+      end
+
+      def to_xml(int)
+        super(int && sprintf(@format, int))
       end
 
       def from_xml(string)
-        string && Integer(super(string))
+        (string = super(string)) && string.to_f
       end
     end
 
+    # An XSD datetime.
+    #
+    # Specifier:: <tt>:datetime</tt>
+    # Ruby type:: +Time+
+    # 
+    # ==== Options
+    # Accepts all options of +Convert_string+.
     class Convert_datetime < Convert_string
       def initialize(options)
         super
@@ -91,22 +190,30 @@ module XmlNuts
       end
 
       def to_xml(time)
-        time && time.xmlschema(@fraction_digits)
+        super(time && time.xmlschema(@fraction_digits))
       end
 
       def from_xml(string)
-        string && Time.parse(super(string, options))
+        (string = super(string)) && Time.parse(string)
       end
     end
 
+    # An XSD whitespace-separated list.
+    #
+    # Specifier::             <tt>:list, :item_type => <em>simple type specifier</em></tt>
+    # Alternative specifier:: <tt>[<em>simple type specifier</em>]</tt>
+    # Ruby type::             +Array+ of <tt><em>simple type</em></tt>
+    #
+    # ==== Options
+    # All options will be passed to the underlying type converter.
     class Convert_list
       def initialize(options)
         @item_type = options[:item_type] || :string
         @item_converter = Converter.create!(@item_type, options)
       end
 
-      def to_xml(array)
-        array && array.map {|x| @item_converter.to_xml(x) } * ' '
+      def to_xml(items)
+        items && items.map {|x| @item_converter.to_xml(x) } * ' '
       end
 
       def from_xml(string)

data/lib/xmlnuts/nuts.rb

@@ -3,13 +3,11 @@ require 'xmlnuts/mappings'
 module XmlNuts #:nodoc:
   # See also +ClassMethods+
   module Nut
-    include XmlBackend
-
     def self.included(other) #:nodoc:
       other.extend(ClassMethods)
     end
 
-    # See also Nut
+    # See also +Nut+.
     module ClassMethods
       include XmlBackend
       include Mappings
@@ -39,8 +37,8 @@ module XmlNuts #:nodoc:
       # TODO: moar details
       #
       # === Arguments
-      # +xmlname+:: Element name
-      # +options+:: +:xmlns+ => Element namespace
+      # [+xmlname+] Element name
+      # [+options+] <tt>:xmlns => <tt> Element namespace
       #
       # === Example:
       #    class Cat
@@ -60,10 +58,10 @@ module XmlNuts #:nodoc:
       # Defines single-element mapping.
       #
       # === Arguments
-      # +name+::    Accessor name
-      # +type+::    Element type. +:string+ assumed if omitted (see +Converter+).
-      # +options+:: +:xmlname+, +:xmlns+, converter options (see +Converter+).
-      # +block+::   An anonymous class definition.
+      # [+name+]    Accessor name
+      # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+      # [+options+] <tt>:xmlname</tt>, <tt>:xmlns</tt>, converter options (see +Converter+).
+      # [+block+]   An anonymous class definition.
       #
       # === Example:
       #    class Cat
@@ -85,10 +83,10 @@ module XmlNuts #:nodoc:
       # Defines multiple elements mapping.
       #
       # === Arguments
-      # +name+::    Accessor name
-      # +type+::    Element type. +:string+ assumed if omitted (see +Converter+).
-      # +options+:: +:xmlname+, +:xmlns+, converter options (see +Converter+).
-      # +block+::   An anonymous class definition.
+      # [+name+]    Accessor name
+      # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+      # [+options+] <tt>:xmlname</tt>, <tt>:xmlns</tt>, converter options (see +Converter+).
+      # [+block+]   An anonymous class definition.
       #
       # === Example:
       #    class RichCat
@@ -109,9 +107,9 @@ module XmlNuts #:nodoc:
       # Defines attribute mapping.
       #
       # === Arguments
-      # +name+::    Accessor name
-      # +type+::    Element type. +:string+ assumed if omitted (see +Converter+).
-      # +options+:: +:xmlname+, +:xmlns+, converter options (see +Converter+).
+      # [+name+]    Accessor name
+      # [+type+]    Element type. <tt>:string</tt> assumed if omitted (see +Converter+).
+      # [+options+] <tt>:xmlname</tt>, <tt>:xmlns</tt>, converter options (see +Converter+).
       #
       # === Example:
       #    class Cat
@@ -128,13 +126,20 @@ module XmlNuts #:nodoc:
 
       #    mappings -> Array
       #
-      # Returns all XmlNuts mappings defined on a class.
+      # Returns all mappings defined on a class.
       def mappings
         @mappings ||= []
       end
 
       def parse(source, options = {})
-        backend.parse(source, options) {|node| new.parse_node(node) }
+        backend.parse(source, options) {|node| parse_node(new, node) }
+      end
+
+      def build(nut, result = :string, options = {})
+        options, result = result, :string if result.is_a?(Hash)
+        options[:xmlname] ||= root.xmlname
+        options[:xmlns_prefix] = namespaces.invert[options[:xmlns] ||= root.xmlns]
+        backend.build(result, options) {|node| build_node(nut, node) }
       end
 
       def build_node(nut, node) #:nodoc:
@@ -192,15 +197,14 @@ module XmlNuts #:nodoc:
     # Defines attribute mapping.
     #
     # === Arguments
-    # +destination+:: Can be given a symbol a backend-specific object,
-    #                 an instance of String or IO classes.
-    # - +:string+   -> will return an XML string.
-    # - +:document+ -> will return a backend specific document object.
-    # - +:object+   -> will return a backend specific object. New document will be created.
-    # - an instance of +String+:    the contents of the string will be replaced with
-    #                the generated XML.
-    # - an instance of +IO+: the IO will be written to.
-    # +options+::     Backend-specific options
+    # [+destination+]
+    #   Can be given a symbol a backend-specific object, an instance of String or IO classes.
+    #   [<tt>:string</tt>]   will return an XML string.
+    #   [<tt>:document</tt>] will return a backend specific document object.
+    #   [<tt>:object</tt>]   will return a backend specific object. New document will be created.
+    #   [an instance of +String+] the contents of the string will be replaced with the generated XML.
+    #   [an instance of +IO+]     the IO will be written to.
+    # [+options+] Backend-specific options
     #
     # === Example:
     #    cat = Cat.new
@@ -211,19 +215,7 @@ module XmlNuts #:nodoc:
     #    cat.build(doc)
     #    puts doc.to_s
     def build(result = :string, options = {})
-      options, result = result, :string if result.is_a?(Hash)
-      root = self.class.root
-      options[:xmlname] ||= root.xmlname
-      options[:xmlns_prefix] = self.class.namespaces.invert[options[:xmlns] ||= root.xmlns]
-      backend.build(result, options) {|node| build_node(node) }
-    end
-
-    def parse_node(node) #:nodoc:
-      self.class.parse_node(self, node)
-    end
-
-    def build_node(node) #:nodoc:
-      self.class.build_node(self, node)
+      self.class.build(self, result, options)
     end
   end
 end

data/test/parsing_test.rb

@@ -4,10 +4,12 @@ require 'test/unit'
 require 'shoulda'
 require 'lib/xmlnuts'
 
+
 class Cheezburger
   include XmlNuts::Nut
 
-  attribute :weight, :integer
+  attribute :weight, :float
+  attribute :price, :decimal
 end
 
 class Cat
@@ -21,7 +23,7 @@ class Cat
   attribute :ears, :integer
 
   element :ration, [:string], :xmlname => :eats, :xmlns => :kthnx
-  element :name, :string, :whitespace => :collapse, :xmlns => 'urn:x-lol:kthnx'
+  element :name, :string, :xmlns => 'urn:x-lol:kthnx'
   elements :paws, :string, :xmlname => :paw
 
   element :friends, :xmlname => :pals do
@@ -38,7 +40,6 @@ class ParsingTest < Test::Unit::TestCase
           <name xmlns='urn:x-lol:kthnx'>
               Silly
               Tom
-              Писта
           </name>
           <kthnx:eats>
             tigers
@@ -53,7 +54,7 @@ class ParsingTest < Test::Unit::TestCase
           <paw> two </paw>
           <paw>three</paw>
           <paw>four</paw>
-          <cheezburger weight='2' />
+          <cheezburger price='2.05' weight='14.5547' />
         </kitteh>
     EOS
     @cat = Cat.parse(@xml_fragment)
@@ -61,7 +62,7 @@ class ParsingTest < Test::Unit::TestCase
 
   context "A cat" do
     should 'be named Silly Tom' do
-      assert_equal 'Silly Tom Писта', @cat.name
+      assert_equal 'Silly Tom', @cat.name
     end
 
     should 'eat tigers and lions' do
@@ -77,12 +78,10 @@ class ParsingTest < Test::Unit::TestCase
     end
 
     should 'have tail' do
-      assert_equal true, @cat.has_tail
+      assert @cat.has_tail
     end
 
     should 'have four paws' do
-      assert_not_nil @cat.paws
-      assert_equal 4, @cat.paws.length
       assert_equal %w(one two three four), @cat.paws
     end
 
@@ -96,8 +95,12 @@ class ParsingTest < Test::Unit::TestCase
       @burger = @cat.cheezburger
     end
 
-    should 'weigh 2 pounds' do
-      assert_equal 2, @burger.weight
+    should 'weigh 14.5547 pounds' do
+      assert_equal 14.5547, @burger.weight
+    end
+
+    should 'cost $2.05' do
+      assert_equal BigDecimal('2.05'), @burger.price
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: pipa-xmlnuts
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Igor Gunko
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-16 00:00:00 -08:00
+date: 2008-12-17 00:00:00 -08:00
 default_executable: 
 dependencies: []