graft 0.2.0 → 0.2.1

data/README.rdoc

@@ -2,7 +2,7 @@
 
 == Description
 
-Graft provides an easy way to map XML data onto your Ruby classes.
+Graft provides an easy way to map XML and JSON data onto your Ruby classes.
 
 == Installation
 
@@ -12,11 +12,105 @@ Stable:
     
 Bleeding edge:
 
-    $ sudo gem install reagent-graft --source=http://gems.github.com
+    $ git clone git://github.com/reagent/graft.git
+    $ cd graft && rake gem
+    $ sudo gem install pkg/graft-<version>.gem
 
 == Usage
 
-TBD
+When interacting with APIs, it's quite often the case that the data returned as
+part of the response is represented either as XML or JSON.  The Graft library makes
+turning that data into Ruby objects pretty simple.  This code was an extraction from
+my work on both the Fleakr[http://reagent.github.com/fleakr] and 
+Etsy[http://github.com/reagent/etsy] gems.
+
+=== Mapping XML
+
+If you want to use Graft in XML mode, you'll need to include the right library:
+
+    require 'rubygems'
+    require 'graft/xml'
+
+Once that is set up, you can take an XML string like this:
+
+    <rsp>
+      <user nsid="3">reagent</user>
+      <name>Patrick Reagan</name>
+    </rsp>
+
+And map it onto a Ruby class:
+
+    class User
+      include Graft
+
+      attribute :name  
+      attribute :username, :from => 'user'
+      attribute :id, :from => 'user@nsid', :type => :integer
+    end
+    
+There are a couple of ways to pull this data into the +User+ object.  The simplest
+is from the constructor:
+
+    user = User.new(xml)
+    
+There is also a +populate_from+ instance method that will do the same:
+
+    user = User.new
+    user.populate_from(xml)
+    
+This second method is useful if the data you want in your Ruby object comes from 2
+separate XML files.  Accessing it is simple:
+
+    >> user.name      # => "Patrick Reagan"
+    >> user.username  # => "reagent"
+    >> user.id        # => 3
+
+=== Mapping JSON
+
+The process of mapping JSON is similar to XML, except:
+
+* You don't need to declare the type of the attribute
+* You need to provide a full path to the JSON value
+
+To get started, include the correct library:
+
+    require 'rubygems'
+    require 'graft/json'
+    
+Then for simple JSON data:
+
+    {
+        "rsp": {
+            "user_id": 3,
+            "username": "reagent",
+            "name": "Patrick Reagan"
+        }
+    }
+
+You can map it in a similar way:
+
+    class User
+      include Graft
+  
+      attribute :name, :from => 'rsp/name'
+      attribute :username, :from => 'rsp/username'
+      attribute :id, :from => 'rsp/user_id'
+    end
+
+Again, you can initialize the values from both the constructor:
+
+    user = User.new(json)
+    
+Or the +populate_from+ method:
+
+    user = User.new
+    user.populate_from(json)
+    
+The results are the same:
+
+    >> user.name      # => "Patrick Reagan"
+    >> user.username  # => "reagent"
+    >> user.id        # => 3
 
 == License
 

data/Rakefile

@@ -12,7 +12,7 @@ spec = Gem::Specification.new do |s|
   s.has_rdoc         = true
   s.extra_rdoc_files = %w(README.rdoc)
   s.rdoc_options     = %w(--main README.rdoc)
-  s.summary          = "Simple XML to attribute mapping for your Ruby classes"
+  s.summary          = "Graft provides an easy way to map XML and JSON data onto your Ruby classes"
   s.author           = 'Patrick Reagan'
   s.email            = 'reaganpr@gmail.com'
   s.homepage         = 'http://sneaq.net/'

data/lib/graft/version.rb

@@ -3,7 +3,7 @@ module Graft
     
     MAJOR = 0
     MINOR = 2
-    TINY  = 0
+    TINY  = 1
     
     def self.to_s # :nodoc:
       [MAJOR, MINOR, TINY].join('.')

data/lib/graft/xml.rb

@@ -3,7 +3,15 @@ $:.unshift File.dirname(__FILE__) + '/..'
 require 'hpricot'
 require 'builder'
 require 'tzinfo'
-require 'active_support/core_ext/blank'
+
+begin
+  # ActiveSupport < 2.3.5
+  require 'active_support/core_ext/blank'
+rescue NameError
+  # ActiveSupport >= 2.3.5 will raise a NameError exception
+  require 'active_support/core_ext/object/blank'
+end
+
 require 'active_support/time_with_zone'
 require 'active_support/inflector'
 

data/lib/graft/xml/attribute.rb

@@ -41,7 +41,10 @@ module Graft
       def value_from(document)
         values = sources.map do |source|
           node = node_for(document, source)
-          (node.attributes[attribute(source)] || node.inner_text) unless node.nil?
+          if !node.nil?
+            possible_values = [node.attributes[attribute(source)], node.inner_text]
+            possible_values.detect {|value| !value.blank? }
+          end
         end
 
         type_class.new(values.compact.first).value

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: graft
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Patrick Reagan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-07 00:00:00 -04:00
+date: 2010-01-25 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -115,9 +115,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.4
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Simple XML to attribute mapping for your Ruby classes
+summary: Graft provides an easy way to map XML and JSON data onto your Ruby classes
 test_files: []