objectify-xml 0.2.1 → 0.2.2

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.2.2 / 2009-03-02
+
+* Improved type lookup to look in the object's scope before the general scope.
+* Added full documentation
+
 === 0.2.1 / 2009-03-02
 
 * Minor update to support the latest version of Nokogiri (1.2.1)

data/lib/objectify_xml.rb

@@ -7,8 +7,10 @@ require File.join(File.dirname(__FILE__), 'objectify_xml/document_parser')
 require File.join(File.dirname(__FILE__), 'objectify_xml/element_parser')
 
 module Objectify
+  # Base class inherited by the DocumentParser and ElementParser. Not intended
+  # for independent use.
   class Xml
-    VERSION = '0.2.1'
+    VERSION = '0.2.2'
 
     # When child nodes are created, they are given the name of the node
     # that created them which is available here.
@@ -24,6 +26,10 @@ module Objectify
       target.extend Dsl
     end
 
+    # Returns the first Nokogiri::XML::Element if any in the document.
+    #
+    # The xml attribute may be a string, a File object or a Nokogiri::XML
+    # object.
     def self.first_element(xml)
       return if xml.nil?
       if xml.is_a?(String) or xml.is_a?(File)
@@ -45,6 +51,8 @@ module Objectify
       primary_xml_element(xml) if xml
     end
 
+    # A short but informative indication of data type and which and how many
+    # elements are present.
     def inspect
       begin
         attrs = (attributes || {}).map do |k,v| 
@@ -62,6 +70,10 @@ module Objectify
       end
     end
 
+    # require 'pp'
+    #
+    # A more detailed recursive dump of the data in and associated to the
+    # object.
     def pretty_print(q)
       begin
         q.object_group(self) do
@@ -82,6 +94,7 @@ module Objectify
 
     protected
 
+    # Attempts to recognize and typecast xml element text values.
     def xml_text_to_value(value)
       value = value.strip
       case value

data/lib/objectify_xml/atom.rb

@@ -1,25 +1,43 @@
 module Objectify
+  # Given as an example of usage, but fully functional. Must be required
+  # separately: require 'objectify/atom'
   module Atom
+    #  attributes :rel, :type, :href
     class Link < ElementParser
       attributes :rel, :type, :href
     end
 
 
+    # attributes :scheme, :term
     class Category < ElementParser
       attributes :scheme, :term
     end
 
 
+    # attributes :type, :xml_lang, :xml_base, :src, :inner_html
     class Content < ElementParser
       attributes :type, :xml_lang, :xml_base, :src, :inner_html
     end
 
 
+    # attributes :version, :uri, :inner_text
     class Generator < ElementParser
       attributes :version, :uri, :inner_text
     end
 
 
+    # The root object of an Atom feed.
+    #
+    #   attributes :id,
+    #     :published,
+    #     :updated,
+    #     :title,
+    #     :subtitle,
+    #     :rights,
+    #     :icon
+    #   has_many :links, :Link, 'link'
+    #   has_many :entries, :Entry, 'entry'
+    #   has_one :generator, Generator, 'generator'
     class Feed < DocumentParser
       attributes :id,
         :published,
@@ -34,6 +52,18 @@ module Objectify
     end
 
 
+    # The feed has a collection of entries.
+    #
+    #   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'
     class Entry < DocumentParser
       attributes :id,
         :published,
@@ -48,11 +78,13 @@ module Objectify
     end
 
 
+    # attributes :name, :uri, :email
     class Author < DocumentParser
       attributes :name, :uri, :email
     end
 
 
+    # attributes :name
     class Contributor < DocumentParser
       attributes :name
     end

data/lib/objectify_xml/document_parser.rb

@@ -1,4 +1,5 @@
 module Objectify
+  # 
   class DocumentParser < Xml
     # The entry point to the parser, normally called by initialize after the 
     # initialization is complete.
@@ -8,24 +9,32 @@ module Objectify
 
     private
 
+    # Returns the given element's name as it would appear in the xml document,
+    # including namespace if present.
     def qualified_name(x)
       qn = x.name
       qn = "#{ x.namespace }:#{ x.name }" if x.namespace
       qn
     end
 
+    # Returns the type of the element's association if one is defined, otherwise nil.
     def attribute_type(x)
       self.class.attribute_type qualified_name(x)
     end
 
+    # Returns boolean to indicate if the children of the element should be
+    # treated as part of the current object's data.
     def flatten?(x)
       self.class.flatten?(qualified_name(x))
     end
 
+    # Returns boolean to indicate if the given element is defined as being one
+    # member of a collection.
     def collection?(x)
       self.class.collection?(qualified_name(x))
     end
 
+    # Returns boolean to indicate if the given element's namespace is supported.
     def namespace?(x)
       if x.namespace
         self.class.namespace?(x.namespace)
@@ -34,10 +43,13 @@ module Objectify
       end
     end
 
+    # Returns the attribute name representing the given element. If the element
+    # is not defined, returns nil.
     def attribute(x)
       self.class.find_attribute(qualified_name(x), x.namespace, x.name)
     end
 
+    # Parses the given xml element and all of its siblings.
     def parse_xml(xml)
       while xml
         read_xml_element(xml)
@@ -45,6 +57,8 @@ module Objectify
       end
     end
 
+    # Processes the given element and stores the resultant value if it is
+    # a defined attribute or association.
     def read_xml_element(x)
       return if x.is_a? Nokogiri::XML::Text
       return unless namespace?(x)
@@ -57,6 +71,7 @@ module Objectify
       end
     end
 
+    # Stores the value of the given attribute or association if it is defined.
     def set_attribute(x)
       if attr_name = attribute(x)
         if collection?(x)

data/lib/objectify_xml/dsl.rb

@@ -5,6 +5,8 @@ module Objectify
         target.init
       end
 
+      # Initializes required metadata variables when the module is included in a
+      # class or a class is inherited.
       def init
         parent = ancestors[1]
         unless /^Objectify::(Xml|ElementParser|DocumentParser)$/ =~ parent.name
@@ -24,21 +26,37 @@ module Objectify
         end
       end
 
+      # Define a typed association attribute. The type should be derived from
+      # either DocumentParser or ElementParser.
+      #
+      # If the type has not yet been defined at the point that the declaration
+      # is made, a String or Symbol may be used and will be looked up from
+      # the scope that the declaration is made in.
       def has_one(name, type, qualified_name)
         set_type(qualified_name, type)
         attribute name, qualified_name
       end
 
+      # Define an attribute as a collection of typed associations. The type
+      # should be derived from either DocumentParser or ElementParser.
+      #
+      # If the type has not yet been defined at the point that the declaration
+      # is made, a String or Symbol may be used and will be instantiated from
+      # the scope that the declaration is made in.
       def has_many(name, type, qualified_name)
         set_type(qualified_name, type)
         attribute name, qualified_name, true
       end
 
+      # Define a list of simple attributes.
       def attributes(*names)
         names.each { |n| attribute n }
         @attributes + @qualified_attributes.keys
       end
 
+      # Define a simple attribute or collection of simple attributes. This
+      # method can be used if the desired attribute name is different from the
+      # xml element name by specifying a qualified name.
       def attribute(name, qualified_name = nil, collection = false)
         name = name.to_s.underscore
         @qualified_attributes[qualified_name] = name if qualified_name
@@ -55,6 +73,8 @@ module Objectify
         name
       end
 
+      # Used internally to find the name of an attribute based on the name of
+      # the xml element.
       def find_attribute(qualified_name, namespace, name)
         if qname = @qualified_attributes[qualified_name]
           return qname
@@ -76,18 +96,23 @@ module Objectify
         end
       end
 
+      # Specify that an element should be recursed into while still associating
+      # its child elements with the current object.
       def flatten(qualified_name)
         @flatten << qualified_name.to_s
       end
 
+      # Used internally to determine whether an element has been flattened.
       def flatten?(qualified_name)
         @flatten.include? qualified_name
       end
 
+      # Used internally to determine whether a namespace is supported.
       def namespace?(namespace)
         @namespaces.keys.include? namespace
       end
 
+      # Specify a list of supported namespaces.
       def namespaces(*namespaces)
         namespaces.each do |ns|
           namespace ns
@@ -95,38 +120,45 @@ module Objectify
         @namespaces
       end
 
+      # Specify the url of the default namespace.
       def default_namespace(url)
         @namespaces[''] = url
       end
 
+      # Specify a namespace with its url.
       def namespace(name = nil, url = nil)
         @namespaces[name.to_s] = url
       end
 
+      # Return the url (if any) associated with a namespace.
       def find_namespace(name = '')
         @namespaces[name]
       end
 
+      # Returns the attribute type associated to an element name if any.
+      #
+      # Searches up the defining object's namespace to the root namespace for
+      # the definition of the constant.
       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
+          type = nil
+          # 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
-              begin
-                sections.push(type_name)
-                type = sections.join('::').constantize
-                break
-              rescue
-                sections.pop
-              end
             end
           end
+          if type.nil?
+            type = type_name.constantize rescue nil
+          end
           if type.nil?
             raise "Unable to instantiate the constant '#{ type_name }'."
           end
@@ -135,14 +167,19 @@ module Objectify
         type
       end
 
+      # Sets the associated type of an attribute. Generally used only internally
+      # via has_one or has_many.
       def set_type(qualified_name, type)
         @types[qualified_name] = type
       end
 
+      # Used internally to determine whether an element is represented by a
+      # collection.
       def collection?(qualified_name)
         @collections.include?(qualified_name)
       end
 
+      # Return the object's metadata for testing and debugging purposes.
       def metadata
         { :attributes => @attributes, 
           :qualified_attributes => @qualified_attributes, 

data/lib/objectify_xml/element_parser.rb

@@ -1,5 +1,10 @@
 module Objectify
   class ElementParser < Xml
+    # Stores the xml element's attribute values, inner_text and inner_html if
+    # they are defined.
+    #
+    # Attributes can be defined either with the attribute dsl method or by
+    # defining a name= method in the object.
     def primary_xml_element(xml)
       xml.attributes.keys.each do |name|
         method = "#{ name }="

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: objectify-xml
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors: 
 - pangloss