happymapper-swanandp 0.4.0

data/License

@@ -0,0 +1,20 @@
+Copyright (c) 2008 John Nunemaker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,55 @@
+= happymapper
+
+== DESCRIPTION:
+
+XML to object mapping library. I have included examples to help get you going. The specs should also point you in the right direction.
+
+== FEATURES:
+
+* Easy to define xml attributes and elements for an object
+* Fast because it uses libxml-ruby under the hood
+* Automatic conversion of xml to defined objects
+
+== EXAMPLES:
+
+Here is a simple example that maps Twitter statuses and users.
+
+  class User
+    include HappyMapper
+
+    element :id, Integer
+    element :name, String
+    element :screen_name, String
+    element :location, String
+    element :description, String
+    element :profile_image_url, String
+    element :url, String
+    element :protected, Boolean
+    element :followers_count, Integer
+  end
+
+  class Status
+    include HappyMapper
+
+    element :id, Integer
+    element :text, String
+    element :created_at, Time
+    element :source, String
+    element :truncated, Boolean
+    element :in_reply_to_status_id, Integer
+    element :in_reply_to_user_id, Integer
+    element :favorited, Boolean
+    has_one :user, User
+  end
+
+See examples directory in the gem for more examples.
+
+http://github.com/jnunemaker/happymapper/tree/master/examples/
+
+== INSTALL:
+
+* gem install happymapper
+
+== DOCS:
+
+http://rdoc.info/projects/jnunemaker/happymapper

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'rake'
+require 'spec/rake/spectask'
+require File.expand_path('../lib/happymapper/version', __FILE__)
+
+Spec::Rake::SpecTask.new do |t|
+  t.ruby_opts << '-rubygems'
+  t.verbose = true
+end
+task :default => :spec
+
+desc 'Builds the gem'
+task :build do
+  sh "gem build happymapper.gemspec"
+end
+
+desc 'Builds and installs the gem'
+task :install => :build do
+  sh "gem install happymapper-#{HappyMapper::Version}"
+end
+
+desc 'Tags version, pushes to remote, and pushes gem'
+task :release => :build do
+  sh "git tag v#{HappyMapper::Version}"
+  sh "git push origin master"
+  sh "git push origin v#{HappyMapper::Version}"
+  sh "gem push happymapper-#{HappyMapper::Version}.gem"
+end
+
+desc 'Upload website files to rubyforge'
+task :website do
+  sh %{rsync -av website/ jnunemaker@rubyforge.org:/var/www/gforge-projects/happymapper}
+end

data/examples/amazon.rb

@@ -0,0 +1,34 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/pita.xml')
+
+# The document `pita.xml` contains both a default namespace and the 'georss'
+# namespace (for the 'point' element).
+module PITA
+  class Item
+    include HappyMapper
+    
+    tag 'Item' # if you put class in module you need tag
+    element :asin, String, :tag => 'ASIN'
+    element :detail_page_url, String, :tag => 'DetailPageURL'
+    element :manufacturer, String, :tag => 'Manufacturer', :deep => true
+    # this is the only element that exists in a different namespace, so it
+    # must be explicitly specified
+    element :point, String, :tag => 'point', :namespace => 'georss'
+  end
+
+  class Items
+    include HappyMapper
+    
+    tag 'Items' # if you put class in module you need tag
+    element :total_results, Integer, :tag => 'TotalResults'
+    element :total_pages, Integer, :tag => 'TotalPages'
+    has_many :items, Item
+  end
+end
+
+item = PITA::Items.parse(file_contents, :single => true)
+item.items.each do |i|
+  puts i.asin, i.detail_page_url, i.manufacturer, ''
+end

data/examples/current_weather.rb

@@ -0,0 +1,21 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/current_weather.xml')
+
+class CurrentWeather
+  include HappyMapper
+  
+  tag 'ob'
+  namespace 'http://www.aws.com/aws'
+  element :temperature, Integer, :tag => 'temp'
+  element :feels_like, Integer, :tag => 'feels-like'
+  element :current_condition, String, :tag => 'current-condition', :attributes => {:icon => String}
+end
+
+CurrentWeather.parse(file_contents).each do |current_weather|
+  puts "temperature: #{current_weather.temperature}"
+  puts "feels_like: #{current_weather.feels_like}"
+  puts "current_condition: #{current_weather.current_condition}"
+  puts "current_condition.icon: #{current_weather.current_condition.icon}"
+end

data/examples/dashed_elements.rb

@@ -0,0 +1,20 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/commit.xml')
+
+module GitHub
+  class Commit
+    include HappyMapper
+
+    tag "commit"
+    element :url, String
+    element :tree, String
+    element :message, String
+    element :id, String
+    element :'committed-date', Date
+  end
+end
+
+commit = GitHub::Commit.parse(file_contents)
+puts commit.committed_date, commit.url, commit.id

data/examples/multi_street_address.rb

@@ -0,0 +1,30 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/multi_street_address.xml')
+
+class MultiStreetAddress
+  include HappyMapper
+  
+  tag 'address'
+  
+  # allow primitive type to be collection
+  has_many :street_address, String, :tag => "streetaddress"
+  element :city, String
+  element :state_or_province, String, :tag => "stateOrProvince"
+  element :zip, String
+  element :country, String
+end
+
+multi = MultiStreetAddress.parse(file_contents)
+
+puts "Street Address:"
+
+multi.street_address.each do |street|
+  puts street
+end
+
+puts "City: #{multi.city}"
+puts "State/Province: #{multi.state_or_province}"
+puts "Zip: #{multi.zip}"
+puts "Country: #{multi.country}"

data/examples/post.rb

@@ -0,0 +1,19 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/posts.xml')
+
+class Post
+  include HappyMapper
+  
+  attribute :href, String
+  attribute :hash, String
+  attribute :description, String
+  attribute :tag, String
+  attribute :time, DateTime
+  attribute :others, Integer
+  attribute :extended, String
+end
+
+posts = Post.parse(file_contents)
+posts.each { |post| puts post.description, post.href, post.extended, '' }

data/examples/twitter.rb

@@ -0,0 +1,37 @@
+dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require File.join(dir, 'happymapper')
+
+file_contents = File.read(dir + '/../spec/fixtures/statuses.xml')
+
+class User
+  include HappyMapper
+  
+  element :id, Integer
+  element :name, String
+  element :screen_name, String
+  element :location, String
+  element :description, String
+  element :profile_image_url, String
+  element :url, String
+  element :protected, Boolean
+  element :followers_count, Integer
+end
+
+class Status
+  include HappyMapper
+  
+  element :id, Integer
+  element :text, String
+	element :created_at, Time
+	element :source, String
+	element :truncated, Boolean
+	element :in_reply_to_status_id, Integer
+	element :in_reply_to_user_id, Integer
+	element :favorited, Boolean
+	has_one :user, User
+end
+
+statuses = Status.parse(file_contents)
+statuses.each do |status|
+  puts status.user.name, status.user.screen_name, status.text, status.source, ''
+end

data/lib/happymapper.rb

@@ -0,0 +1,321 @@
+require 'rubygems'
+require 'date'
+require 'time'
+require 'xml'
+
+class Boolean; end
+
+module HappyMapper
+
+  DEFAULT_NS = "happymapper"
+
+  def self.included(base)
+    base.instance_variable_set("@attributes", {})
+    base.instance_variable_set("@elements", {})
+    base.instance_variable_set("@registered_namespaces", {})
+    
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def attribute(name, type, options={})
+      attribute = Attribute.new(name, type, options)
+      @attributes[to_s] ||= []
+      @attributes[to_s] << attribute
+      attr_accessor attribute.method_name.intern
+    end
+
+    def attributes
+      @attributes[to_s] || []
+    end
+
+    def element(name, type, options={})
+      element = Element.new(name, type, options)
+      @elements[to_s] ||= []
+      @elements[to_s] << element
+      attr_accessor element.method_name.intern
+    end
+
+    def content(name)
+      @content = name
+      attr_accessor name
+    end
+
+    def raw_content(name)
+      @raw_content = name
+      attr_accessor name
+    end
+
+    def after_parse_callbacks
+      @after_parse_callbacks ||= []
+    end
+
+    def after_parse(&block)
+      after_parse_callbacks.push(block)
+    end
+
+    def elements
+      @elements[to_s] || []
+    end
+
+    def has_one(name, type, options={})
+      element name, type, {:single => true}.merge(options)
+    end
+
+    def has_many(name, type, options={})
+      element name, type, {:single => false}.merge(options)
+    end
+
+    # Specify a namespace if a node and all its children are all namespaced
+    # elements. This is simpler than passing the :namespace option to each
+    # defined element.
+    def namespace(namespace = nil)
+      @namespace = namespace if namespace
+      @namespace
+    end
+    
+    def register_namespace(namespace, ns)
+      @registered_namespaces.merge!(namespace => ns)
+    end
+
+    def tag(new_tag_name)
+      @tag_name = new_tag_name.to_s
+    end
+
+    def tag_name
+      @tag_name ||= to_s.split('::')[-1].downcase
+    end
+
+    def parse(xml, options = {})
+      if xml.is_a?(XML::Node)
+        node = xml
+      else
+        if xml.is_a?(XML::Document)
+          node = xml.root
+        else
+          node = XML::Parser.string(xml).parse.root
+        end
+
+        root = node.name == tag_name
+      end
+
+      namespace = @namespace || (node.namespaces && node.namespaces.default)
+      namespace = "#{DEFAULT_NS}:#{namespace}" if namespace
+
+      xpath = root ? '/' : './/'
+      xpath += "#{DEFAULT_NS}:" if namespace
+      xpath += tag_name
+
+      nodes = node.find(xpath, Array(namespace))
+      collection = nodes.collect do |n|
+        obj = new
+
+        attributes.each do |attr|
+          obj.send("#{attr.method_name}=",
+          attr.from_xml_node(n, namespace))
+        end
+
+        elements.each do |elem|
+          obj.send("#{elem.method_name}=",
+          elem.from_xml_node(n, namespace))
+        end
+
+        obj.send("#{@content}=", n.content) if @content
+        obj.send("#{@raw_content}=", n.inner_xml) if @raw_content
+
+        obj.class.after_parse_callbacks.each { |callback| callback.call(obj) }
+
+        obj
+      end
+
+      # per http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Document.html#M000354
+      nodes = nil
+
+      if options[:single] || root
+        collection.first
+      else
+        collection
+      end
+    end
+
+  end
+
+  #
+  # Create an xml representation of the specified class based on defined
+  # HappyMapper elements and attributes. The method is defined in a way
+  # that it can be called recursively by classes that are also HappyMapper
+  # classes, allowg for the composition of classes.
+  #
+  def to_xml(parent_node = nil, default_namespace = nil)
+
+    #
+    # Create a tag that uses the tag name of the class that has no contents
+    # but has the specified namespace or uses the default namespace
+    #
+    current_node = XML::Node.new(self.class.tag_name)
+
+
+    if parent_node
+      #
+      # if #to_xml has been called with a parent_node that means this method
+      # is being called recursively (or a special case) and we want to return
+      # the parent_node with the new node as a child
+      #
+      parent_node << current_node
+    else
+      #
+      # If #to_xml has been called without a Node (and namespace) that
+      # means we want to return an xml document
+      #
+      write_out_to_xml = true
+    end
+    
+    #
+    # Add all the registered namespaces to the current node and the current node's
+    # root element. Without adding it to the root element it is not possible to
+    # parse or use xpath to find elements.
+    #
+    if self.class.instance_variable_get('@registered_namespaces')
+      
+      # Given a node, continue moving up to parents until there are no more parents
+      find_root_node = lambda {|node| while node.parent? ; node = node.parent ; end ; node }
+      root_node = find_root_node.call(current_node)
+      
+      # Add the registered namespace to the found root node only if it does not already have one defined
+      self.class.instance_variable_get('@registered_namespaces').each_pair do |prefix,href|
+        XML::Namespace.new(current_node,prefix,href)
+        XML::Namespace.new(root_node,prefix,href) unless root_node.namespaces.find_by_prefix(prefix)
+      end
+    end
+
+    #
+    # Determine the tag namespace if one has been specified. This value takes
+    # precendence over one that is handed down to composed sub-classes.
+    #
+    tag_namespace = current_node.namespaces.find_by_prefix(self.class.namespace) || default_namespace
+    
+    # Set the namespace of the current node to the specified namespace
+    current_node.namespaces.namespace = tag_namespace if tag_namespace
+
+    #
+    # Add all the attribute tags to the current node with their namespace, if one
+    # is defined, or the namespace handed down to the node.
+    #
+    self.class.attributes.each do |attribute|
+      attribute_namespace = current_node.namespaces.find_by_prefix(attribute.options[:namespace]) || default_namespace
+      
+      value = send(attribute.method_name)
+
+      #
+      # If the attribute has a :on_save attribute defined that is a proc or
+      # a defined method, then call those with the current value.
+      #
+      if on_save_operation = attribute.options[:on_save]
+        if on_save_operation.is_a?(Proc)
+          value = on_save_operation.call(value)
+        elsif respond_to?(on_save_operation)
+          value = send(on_save_operation,value)
+        end
+      end
+      
+      current_node[ "#{attribute_namespace ? "#{attribute_namespace.prefix}:" : ""}#{attribute.tag}" ] = value
+    end
+
+    #
+    # All all the elements defined (e.g. has_one, has_many, element) ...
+    #
+    self.class.elements.each do |element|
+
+      tag = element.tag || element.name
+      
+      element_namespace = current_node.namespaces.find_by_prefix(element.options[:namespace]) || tag_namespace
+      
+      value = send(element.name)
+
+      #
+      # If the element defines an :on_save lambda/proc then we will call that
+      # operation on the specified value. This allows for operations to be 
+      # performed to convert the value to a specific value to be saved to the xml.
+      #
+      if on_save_operation = element.options[:on_save]
+        if on_save_operation.is_a?(Proc)
+          value = on_save_operation.call(value)
+        elsif respond_to?(on_save_operation)
+          value = send(on_save_operation,value)
+        end
+      end
+
+      #
+      # Normally a nil value would be ignored, however if specified then
+      # an empty element will be written to the xml
+      #
+      if value.nil? && element.options[:state_when_nil]
+        current_node << XML::Node.new(tag,nil,element_namespace)
+      end
+
+      #
+      # To allow for us to treat both groups of items and singular items
+      # equally we wrap the value and treat it as an array.
+      #
+      if value.nil?
+        values = []
+      elsif value.respond_to?(:to_ary) && !element.options[:single]
+        values = value.to_ary
+      else
+        values = [value]
+      end
+
+
+      values.each do |item|
+
+        if item.is_a?(HappyMapper)
+
+          #
+          # Other HappyMapper items that are convertable should not be called
+          # with the current node and the namespace defined for the element.
+          #
+          item.to_xml(current_node,element_namespace)
+
+        elsif item
+
+          #
+          # When a value exists we should append the value for the tag
+          #
+          current_node << XML::Node.new(tag,item.to_s,element_namespace)
+
+        else
+          
+          #
+          # Normally a nil value would be ignored, however if specified then
+          # an empty element will be written to the xml
+          #
+          current_node << XML.Node.new(tag,nil,element_namespace) if element.options[:state_when_nil]
+
+        end
+
+      end
+
+    end
+
+
+    #
+    # Generate xml from a document if no node was passed as a parameter. Otherwise
+    # this method is being called recursively (or special case) and we should
+    # return the node with this node attached as a child.
+    #
+    if write_out_to_xml
+      document = XML::Document.new
+      document.root = current_node
+      document.to_s
+    else
+      parent_node
+    end
+
+  end
+
+
+end
+
+require File.dirname(__FILE__) + '/happymapper/item'
+require File.dirname(__FILE__) + '/happymapper/attribute'
+require File.dirname(__FILE__) + '/happymapper/element'