objectify-xml 0.2.0

data/History.txt

@@ -0,0 +1,9 @@
+=== 0.2.0 / 2009-02-24
+
+* Initial public release.
+* Full suite of specs.
+
+=== 0.1.0 / 2009-02-22
+
+* Initial project creation.
+

data/Manifest.txt

@@ -0,0 +1,16 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/objectify_xml.rb
+lib/objectify_xml/atom.rb
+lib/objectify_xml/document_parser.rb
+lib/objectify_xml/dsl.rb
+lib/objectify_xml/element_parser.rb
+spec/spec_helper.rb
+spec/atom_spec.rb
+spec/document_parser_spec.rb
+spec/dsl_spec.rb
+spec/element_parser_spec.rb
+spec/objectify_xml_spec.rb
+spec/sample/wikipedia.atom

data/README.txt

@@ -0,0 +1,120 @@
+= Objectify::Xml
+
+* http://github.com/pangloss/objectify_xml
+
+== DESCRIPTION:
+
+Provides an easy to use DSL resembling ActiveRecord for defining objects
+representing any XML document, including deeply nested ones. This project was
+extracted from my ruby-picasa gem. You can find ruby-picasa at
+http://github.com/pangloss/ruby_picasa or available as a gem.
+
+The project also has significant (if not complete) Atom support.
+
+== FEATURES:
+
+* Capture and typecast standard attributes
+* Define both has_one and has_many nested element 'associations'
+* Significant (if not full) namespace support
+* Cleanly ignore unknown attributes and namespaces
+* Support documents that nest data unnecessarily without creating bogus
+  associated objects.
+* Inheritable object definitions
+
+== PROBLEMS:
+
+* None known.
+
+== SYNOPSIS:
+
+The following are functioning early definitions for some of the objects used in
+ruby-picasa in their entirety:
+
+require 'objectify_xml'
+require 'objectify_xml/atom' 
+module RubyPicasa
+  class PhotoUrl < Objectify::Xml::ElementParser
+    attr_accessor :url, :height, :width
+  end
+
+  class Album < Objectify::Xml::DocumentParser
+    attributes :id,
+      :published,
+      :updated,
+      :title,
+      :summary,
+      :rights,
+      :gphoto_id,
+      :name,
+      :access,
+      :numphotos, 
+      :total_results, 
+      :start_index,
+      :items_per_page,
+      :allow_downloads
+    has_many :links, Objectify::Atom::Link, 'link'
+    has_many :entries, :Photo, 'entry'
+    has_one :content, PhotoUrl, 'media:content'
+    has_many :thumbnails, PhotoUrl, 'media:thumbnail'
+    flatten 'media:group'
+    namespaces %w[openSearch gphoto media]
+  end
+
+  class Photo < Objectify::Xml::DocumentParser
+    attributes :id,
+      :published,
+      :updated,
+      :title,
+      :summary,
+      :gphoto_id,
+      :version, 
+      :position,
+      :albumid,
+      :width,
+      :height,
+      :description,
+      :keywords
+    has_many :links, Objectify::Atom::Link, 'link'
+    has_one :content, PhotoUrl, 'media:content'
+    has_many :thumbnails, PhotoUrl, 'media:thumbnail'
+    namespaces %w[gphoto media]
+    flatten 'media:group'
+  end
+end
+
+
+== REQUIREMENTS:
+
+* nokogiri
+* activeresource
+
+== INSTALL:
+
+* Installable either as a gem or vendored into a project.
+* gem install objectify-xml
+* gem install pangloss-objectify-xml --source http://gems.github.com
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Darrick Wiebe
+
+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/Rakefile

@@ -0,0 +1,15 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/objectify_xml.rb'
+
+Hoe.new('objectify-xml', Objectify::Xml::VERSION) do |p|
+  p.rubyforge_name = 'objectify-xml' # if different than lowercase project name
+  p.developer('pangloss', 'darrick@innatesoftware.com')
+  p.extra_deps = %w[nokogiri activesupport]
+  #p.extra_dev_deps = []
+  p.url = 'http://github.com/pangloss/objectify_xml'
+end
+
+# vim: syntax=Ruby

data/lib/objectify_xml.rb

@@ -0,0 +1,104 @@
+gem 'activesupport'
+require 'active_support'
+require 'active_support/inflections'
+require 'nokogiri'
+require File.join(File.dirname(__FILE__), 'objectify_xml/dsl')
+require File.join(File.dirname(__FILE__), 'objectify_xml/document_parser')
+require File.join(File.dirname(__FILE__), 'objectify_xml/element_parser')
+
+module Objectify
+  class Xml
+    VERSION = '0.2.0'
+
+    # When child nodes are created, they are given the name of the node
+    # that created them which is available here.
+    attr_reader :parent
+
+    # A hash containing the values of the xml document's nodes. The data is
+    # usually better accessed through the getter and setter methods that are
+    # created for all attributes, has_one and has_many associations.
+    attr_reader :attributes
+
+    def self.inherited(target)
+      # The Dsl module is added to every class that inherits from this
+      target.extend Dsl
+    end
+
+    def self.first_element(xml)
+      return if xml.nil?
+      if xml.is_a?(String) or xml.is_a?(File)
+        xml = Nokogiri::XML.parse(xml)
+      end
+      # skip the <?xml?> tag
+      xml = xml.child if xml.class == Nokogiri::XML::Document
+      while xml.class == Nokogiri::XML::Node
+        # skips past things like xml-stylesheet declarations.
+        xml = xml.next
+      end
+      xml
+    end
+
+    def initialize(xml, parent = nil)
+      @parent = parent
+      @attributes = {}
+      xml = self.class.first_element(xml)
+      primary_xml_element(xml) if xml
+    end
+
+    def inspect
+      begin
+        attrs = (attributes || {}).map do |k,v| 
+          if v.is_a? Objectify::Xml
+            "#{ k }:#{ v.class.name }"
+          elsif v.is_a? Array
+            "#{ k }:#{ v.length }"
+          else
+            k.to_s
+          end
+        end
+        "<#{ self.class.name } #{ attrs.join(', ') }>"
+      rescue => e
+        "<#{ self.class.name } Error inspecting class: #{ e.name } #{ e.message }>"
+      end
+    end
+
+    def pretty_print(q)
+      begin
+        q.object_group(self) do
+          q.breakable
+          q.seplist(attributes, nil, :each_pair) do |k, v|
+            q.text "#{ k.to_s }: "
+            if v.is_a? String and v.length > 200
+              q.text "#{ v[0..80] }...".inspect
+            else
+              q.pp v
+            end
+          end
+        end
+      rescue => e
+        q.text "<#{ self.class.name } Error inspecting class: #{ e.name } #{ e.message }>"
+      end
+    end
+
+    protected
+
+    def xml_text_to_value(value)
+      value = value.strip
+      case value
+      when 'true'
+        true
+      when 'false'
+        false
+      when /\A\d{4}-\d\d-\d\d(T(\d\d[:]){2}\d\d.*)?/
+        DateTime.parse(value) rescue value
+      when /\A\d+\Z/
+        value.to_i
+      when /\A\d+\.\d+\Z/
+        value.to_f
+      else
+        value
+      end
+    end
+
+  end
+end

data/lib/objectify_xml/atom.rb

@@ -0,0 +1,60 @@
+module Objectify
+  module Atom
+    class Link < ElementParser
+      attributes :rel, :type, :href
+    end
+
+
+    class Category < ElementParser
+      attributes :scheme, :term
+    end
+
+
+    class Content < ElementParser
+      attributes :type, :xml_lang, :xml_base, :src, :inner_html
+    end
+
+
+    class Generator < ElementParser
+      attributes :version, :uri, :inner_text
+    end
+
+
+    class Feed < DocumentParser
+      attributes :id,
+        :published,
+        :updated,
+        :title,
+        :subtitle,
+        :rights,
+        :icon
+      has_many :links, :Link, 'link'
+      has_many :entries, :Entry, 'entry'
+      has_one :generator, Generator, 'generator'
+    end
+
+
+    class Entry < DocumentParser
+      attributes :id,
+        :published,
+        :updated,
+        :title,
+        :summary
+      has_many :links, Link, 'link'
+      has_one :category, Category, 'category'
+      has_many :contents, Content, 'content'
+      has_one :author, :Author, 'author'
+      has_many :contributors, :Contributor, 'contributor'
+    end
+
+
+    class Author < DocumentParser
+      attributes :name, :uri, :email
+    end
+
+
+    class Contributor < DocumentParser
+      attributes :name
+    end
+  end
+end

data/lib/objectify_xml/document_parser.rb

@@ -0,0 +1,70 @@
+module Objectify
+  class DocumentParser < Xml
+    # The entry point to the parser, normally called by initialize after the 
+    # initialization is complete.
+    def primary_xml_element(xml)
+      parse_xml(xml.child)
+    end
+
+    private
+
+    def qualified_name(x)
+      qn = x.name
+      qn = "#{ x.namespace }:#{ x.name }" if x.namespace
+      qn
+    end
+
+    def attribute_type(x)
+      self.class.attribute_type qualified_name(x)
+    end
+
+    def flatten?(x)
+      self.class.flatten?(qualified_name(x))
+    end
+
+    def collection?(x)
+      self.class.collection?(qualified_name(x))
+    end
+
+    def namespace?(x)
+      if x.namespace
+        self.class.namespace?(x.namespace)
+      else
+        true
+      end
+    end
+
+    def attribute(x)
+      self.class.find_attribute(qualified_name(x), x.namespace, x.name)
+    end
+
+    def parse_xml(xml)
+      while xml
+        read_xml_element(xml)
+        xml = xml.next
+      end
+    end
+
+    def read_xml_element(x)
+      return if x.is_a? Nokogiri::XML::Text
+      return unless namespace?(x)
+      if flatten?(x)
+        parse_xml(x.child)
+      elsif type = attribute_type(x)
+        set_attribute(x) { type.new(x, self) }
+      else
+        set_attribute(x) { xml_text_to_value(x.text) }
+      end
+    end
+
+    def set_attribute(x)
+      if attr_name = attribute(x)
+        if collection?(x)
+          send(attr_name) << yield
+        else
+          send("#{attr_name}=", yield)
+        end
+      end
+    end
+  end
+end

data/lib/objectify_xml/dsl.rb

@@ -0,0 +1,156 @@
+module Objectify
+  class Xml
+    module Dsl
+      def self.extended(target)
+        target.init
+      end
+
+      def init
+        parent = ancestors[1]
+        unless /^Objectify::(Xml|ElementParser|DocumentParser)$/ =~ parent.name
+          @collections = parent.instance_variable_get('@collections').clone || []
+          @attributes = parent.instance_variable_get('@attributes').clone || []
+          @qualified_attributes = parent.instance_variable_get('@qualified_attributes').clone || {}
+          @flatten = parent.instance_variable_get('@flatten').clone || []
+          @namespaces = parent.instance_variable_get('@namespaces').clone || {}
+          @types = parent.instance_variable_get('@types').clone || {}
+        else
+          @collections = []
+          @attributes = []
+          @qualified_attributes = {}
+          @flatten = []
+          @namespaces = {}
+          @types = {}
+        end
+      end
+
+      def has_one(name, type, qualified_name)
+        set_type(qualified_name, type)
+        attribute name, qualified_name
+      end
+
+      def has_many(name, type, qualified_name)
+        set_type(qualified_name, type)
+        attribute name, qualified_name, true
+      end
+
+      def attributes(*names)
+        names.each { |n| attribute n }
+        @attributes + @qualified_attributes.keys
+      end
+
+      def attribute(name, qualified_name = nil, collection = false)
+        name = name.to_s.underscore
+        @qualified_attributes[qualified_name] = name if qualified_name
+        @collections << (qualified_name || name).to_s if collection
+        @attributes << name unless qualified_name
+        module_eval %{
+          def #{name}=(value)
+            @attributes['#{name}'] = value
+          end
+          def #{name}
+            @attributes['#{name}']#{ collection ? ' ||= []' : '' }
+          end
+        }
+        name
+      end
+
+      def find_attribute(qualified_name, namespace, name)
+        if qname = @qualified_attributes[qualified_name]
+          return qname
+        end
+        names = []
+        plural = collection?(qualified_name)
+        if plural
+          if namespace
+            names << "#{ namespace }_#{ name.pluralize }"
+          end
+          names << name.pluralize
+        end
+        if namespace
+          names << "#{ namespace }_#{ name }"
+        end
+        names << name
+        names.map { |n| n.underscore }.find do |n|
+          @attributes.include? n.underscore
+        end
+      end
+
+      def flatten(qualified_name)
+        @flatten << qualified_name.to_s
+      end
+
+      def flatten?(qualified_name)
+        @flatten.include? qualified_name
+      end
+
+      def namespace?(namespace)
+        @namespaces.keys.include? namespace
+      end
+
+      def namespaces(*namespaces)
+        namespaces.each do |ns|
+          namespace ns
+        end
+        @namespaces
+      end
+
+      def default_namespace(url)
+        @namespaces[''] = url
+      end
+
+      def namespace(name = nil, url = nil)
+        @namespaces[name.to_s] = url
+      end
+
+      def find_namespace(name = '')
+        @namespaces[name]
+      end
+
+      def attribute_type(qualified_name)
+        type = @types[qualified_name]
+        if type and not type.is_a? Class
+          type_name = type.to_s
+          begin
+            type = type_name.constantize
+          rescue
+            # Try to search the current object's namespace explicitly
+            sections = self.name.split(/::/)
+            while sections.length > 1
+              sections.pop
+              begin
+                sections.push(type_name)
+                type = sections.join('::').constantize
+                break
+              rescue
+                sections.pop
+              end
+            end
+          end
+          if type.nil?
+            raise "Unable to instantiate the constant '#{ type_name }'."
+          end
+          @types[qualified_name] = type
+        end
+        type
+      end
+
+      def set_type(qualified_name, type)
+        @types[qualified_name] = type
+      end
+
+      def collection?(qualified_name)
+        @collections.include?(qualified_name)
+      end
+
+      def metadata
+        { :attributes => @attributes, 
+          :qualified_attributes => @qualified_attributes, 
+          :collections => @collections, 
+          :flatten => @flatten, 
+          :namespaces => @namespaces, 
+          :types => @types }
+      end
+    end
+  end
+end