representative 0.2.0 → 0.2.1

data/lib/representative/version.rb

@@ -1,3 +1,3 @@
 module Representative
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.1".freeze
 end

data/lib/representative/xml.rb

@@ -6,8 +6,14 @@ require "representative/object_inspector"
 
 module Representative
 
-  class Xml < BlankSlate
-
+  # Easily generate XML while traversing an object-graph.
+  #
+  class Xml
+
+    # Create an XML-generating Representative.  The first argument should be an instance of
+    # Builder::XmlMarkup (or something that implements it's interface).  The second argument
+    # if any, is the initial #subject of representation.
+    #
     def initialize(xml_builder, subject = nil, options = {})
       @xml = xml_builder
       @subjects = [subject]
@@ -15,7 +21,18 @@ module Representative
       yield self if block_given?
     end
 
-    def represent(subject)
+    # Return the current "subject" of representation.  
+    #
+    # This object will provide element values where they haven't been 
+    # explicitly provided.
+    #
+    def subject
+      @subjects.last
+    end
+
+    # Evaluate a block with a specified object as #subject.
+    #
+    def representing(subject)
       @subjects.push(subject)
       begin
         yield subject
@@ -23,14 +40,42 @@ module Representative
         @subjects.pop
       end
     end
-    
-    def subject
-      @subjects.last
-    end
-    
+
+    # Generate an element.
+    #
+    # With two arguments, it generates an element with the specified text content.
+    # 
+    #   r.element :size, 42
+    #   # => <size>42</size>
+    #
+    # More commonly, though, the second argument is omitted, in which case the 
+    # element content is assumed to be the named property of the current #subject.
+    #
+    #   r.representing my_shoe do
+    #     r.element :size
+    #   end
+    #   # => <size>9</size>
+    #
+    # If a block is attached, nested elements can be generated.  The element "value"
+    # (whether explicitly provided, or derived from the current subject) becomes the
+    # subject during evaluation of the block.
+    #
+    #   r.element :book, book do
+    #     r.title
+    #     r.author
+    #   end
+    #   # => <book><title>Whatever</title><author>Whoever</author></book>
+    #
+    # Providing a final Hash argument specifies element attributes.
+    #
+    #   r.element :size, :type => "integer"
+    #   # => <size type="integer">9</size>
+    #
     def element(name, *args, &block)
 
-      element_attributes = args.extract_options!
+      attributes = args.extract_options!
+      attributes = attributes.merge(@inspector.get_metadata(subject, name))
+
       value_generator = if args.empty? 
         lambda do |subject|
           @inspector.get_value(subject, name)
@@ -38,64 +83,75 @@ module Representative
       else 
         args.shift
       end
+
       raise ArgumentError, "too many arguments" unless args.empty?
 
       value = resolve_value(value_generator)
-      resolved_element_attributes = resolve_element_attributes(element_attributes, value)
-      resolved_element_attributes.merge!(@inspector.get_metadata(subject, name))
+      return @xml.tag!(name) if value.nil?
+      
+      representing(value) do
+        
+        content_string = subject.to_s unless block
+        content_block = unless block.nil? || block == Representative::EMPTY
+          Proc.new do
+            block.call(subject)
+          end
+        end
+
+        resolved_attributes = resolve_attributes(attributes)
+        tag_args = [content_string, resolved_attributes].compact
 
-      emit_element(name, value, resolved_element_attributes, &block)
+        @xml.tag!(name.to_s.dasherize, *tag_args, &content_block)
+
+      end
 
     end
 
-    def list_of(attribute_name, *args, &block)
+    # Generate a list of elements from Enumerable data.
+    #
+    #   r.list_of :books, my_books do
+    #     r.element :title
+    #   end
+    #   # => <books type="array">
+    #   #      <book><title>Sailing for old dogs</title></book>
+    #   #      <book><title>On the horizon</title></book>
+    #   #      <book><title>The Little Blue Book of VHS Programming</title></book>
+    #   #    </books>
+    #
+    # Like #element, the value can be explicit, but is more commonly extracted
+    # by name from the current #subject.
+    #
+    def list_of(name, *args, &block)
 
       options = args.extract_options!
-      value_generator = args.empty? ? attribute_name : args.shift
+      value_generator = args.empty? ? name : args.shift
       raise ArgumentError, "too many arguments" unless args.empty?
 
-      list_name = attribute_name.to_s.dasherize
-      list_element_attributes = options[:list_attributes] || {}
-      item_name = options[:item_name] || list_name.singularize
-      item_element_attributes = options[:item_attributes] || {}
+      list_attributes = options[:list_attributes] || {}
+      item_name = options[:item_name] || name.to_s.singularize
+      item_attributes = options[:item_attributes] || {}
 
       items = resolve_value(value_generator)
-      if items.nil?
-        return @xml.tag!(list_name)
-      end
-
-      resolved_list_element_attributes = resolve_element_attributes(list_element_attributes, items)
-
-      @xml.tag!(list_name, resolved_list_element_attributes.merge(:type => "array")) do
+      element(name, items, list_attributes.merge(:type => "array")) do
         items.each do |item|
-          resolved_item_element_attributes = resolve_element_attributes(item_element_attributes, item)
-          emit_element(item_name, item, resolved_item_element_attributes, &block)
+          element(item_name, item, item_attributes, &block)
         end
       end
 
     end
 
+    # Return a magic value that, when passed to #element as a block, forces
+    # generation of an empty element.
+    #
+    #   r.element(:link, :rel => "me", :href => "http://dogbiscuit.org", &r.empty)
+    #   # => <link rel="parent" href="http://dogbiscuit.org"/>
+    #
     def empty
       Representative::EMPTY
     end
     
     private 
 
-    def emit_element(name, subject, options, &content_block)
-      content = content_generator = nil
-      if subject && content_block
-        unless content_block == Representative::EMPTY
-          content_generator = Proc.new do
-            represent(subject, &content_block)
-          end
-        end
-      else
-        content = subject
-      end
-      tag_args = [content, options].compact
-      @xml.tag!(name.to_s.dasherize, *tag_args, &content_generator)
-    end
-
     def resolve_value(value_generator, subject = subject)
       if value_generator == :self
         subject
@@ -106,9 +162,9 @@ module Representative
       end
     end
 
-    def resolve_element_attributes(element_attributes, subject)
-      if element_attributes
-        element_attributes.inject({}) do |resolved, (name, value_generator)|
+    def resolve_attributes(attributes)
+      if attributes
+        attributes.inject({}) do |resolved, (name, value_generator)|
           resolved_value = resolve_value(value_generator, subject)
           resolved[name.to_s.dasherize] = resolved_value unless resolved_value.nil?
           resolved

data/spec/representative/xml_spec.rb

@@ -148,8 +148,9 @@ describe Representative::Xml do
 
         it "yields each new subject" do
           r.element :vehicle do |vehicle|
-            vehicle.should == @subject.vehicle
+            r.element :year, vehicle.year
           end
+          resulting_xml.should == %(<vehicle><year>1959</year></vehicle>)
         end
 
       end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Mike Williams
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-02 00:00:00 +10:00
+date: 2010-07-04 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency