representative 0.1.3 → 0.2.0

data/README.markdown

@@ -37,15 +37,18 @@ Given a Ruby data-structure:
 Representative::Xml can be used to generate XML, in a declarative style:
 
     xml = Builder::XmlMarkup.new(:indent => 2)
-    representative = Representative::Xml.new(xml)
-
-    representative.list_of!(:books, books) do |_book|
-      _book.title
-      _book.list_of!(:authors)
-      _book.published do |_published|
-        _published.by
-        _published.year
+
+    Representative::Xml.new(xml) do |r|
+    
+      r.list_of :books, books do
+        r.element :title
+        r.list_of :authors
+        r.element :published do
+          r.element :by
+          r.element :year
+        end
       end
+      
     end
 
     puts xml.target!
@@ -85,18 +88,18 @@ The resulting XML looks like this:
 
 Notice that:
 
-- Representative generates elements for each object-attribute you name (and not the ones you don't).
 - The structure of the XML mirrors the structure described by the nested Ruby blocks.
-- Using `list_of!` for a collection attribute generates an "array" element, which plays nicely
+- Representative walks the object-graph for you.
+- Using `list_of` for a collection attribute generates an "array" element, which plays nicely
   with most Ruby XML-to-hash converters.
 - Where a named object-attribute is nil, you get an empty element.
 
 Installation
 ------------
 
-Representative is packaged as a Gem, hosted on [gemcutter](http://gemcutter.org/gems/representative).  Install with:
+Representative is packaged as a Gem.  Install with:
 
-    sudo gem install representative
+    gem install representative
 
 Copyright
 ---------

data/examples/xml_demo.rb

@@ -29,15 +29,15 @@ books = [
 ]
 
 xml = Builder::XmlMarkup.new(:indent => 2)
-representative = Representative::Xml.new(xml)
-
-representative.list_of!(:books, books) do |_book|
-  _book.title
-  _book.list_of!(:authors)
-  _book.published do |_published|
-    _published.by
-    _published.year
+Representative::Xml.new(xml) do |r|
+  r.list_of :books, books do
+    r.element :title
+    r.list_of :authors
+    r.element :published do
+      r.element :by
+      r.element :year
+    end
   end
 end
 
-puts xml.target!
+puts xml.target!

data/lib/representative/version.rb

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

data/lib/representative/xml.rb

@@ -15,61 +15,40 @@ module Representative
       yield self if block_given?
     end
 
-    def method_missing(name, *args, &block)
-      if name.to_s =~ /!$/
-        super
-      else
-        attribute!(name, *args, &block)
+    def represent(subject)
+      @subjects.push(subject)
+      begin
+        yield subject
+      ensure
+        @subjects.pop
       end
     end
-
-    def subject!
+    
+    def subject
       @subjects.last
     end
     
-    def attribute!(subject_attribute_name, *args, &block)
+    def element(name, *args, &block)
 
       element_attributes = args.extract_options!
       value_generator = if args.empty? 
         lambda do |subject|
-          @inspector.get_value(subject, subject_attribute_name)
+          @inspector.get_value(subject, name)
         end
       else 
         args.shift
       end
       raise ArgumentError, "too many arguments" unless args.empty?
 
-      element_name = subject_attribute_name.to_s.dasherize
-
       value = resolve_value(value_generator)
       resolved_element_attributes = resolve_element_attributes(element_attributes, value)
-      resolved_element_attributes.merge!(@inspector.get_metadata(subject!, subject_attribute_name))
+      resolved_element_attributes.merge!(@inspector.get_metadata(subject, name))
 
-      element!(element_name, value, resolved_element_attributes, &block)
+      emit_element(name, value, resolved_element_attributes, &block)
 
     end
 
-    def element!(element_name, subject, options, &block)
-      content = content_generator = nil
-      if block && subject
-        unless block == Representative::EMPTY
-          content_generator = Proc.new do
-            @subjects.push(subject)
-            begin
-              block.call(self)
-            ensure
-              @subjects.pop
-            end
-          end
-        end
-      else
-        content = subject
-      end
-      tag_args = [content, options].compact
-      @xml.tag!(element_name, *tag_args, &content_generator)
-    end
-
-    def list_of!(attribute_name, *args, &block)
+    def list_of(attribute_name, *args, &block)
 
       options = args.extract_options!
       value_generator = args.empty? ? attribute_name : args.shift
@@ -90,19 +69,34 @@ module Representative
       @xml.tag!(list_name, resolved_list_element_attributes.merge(:type => "array")) do
         items.each do |item|
           resolved_item_element_attributes = resolve_element_attributes(item_element_attributes, item)
-          element!(item_name, item, resolved_item_element_attributes, &block)
+          emit_element(item_name, item, resolved_item_element_attributes, &block)
         end
       end
 
     end
 
-    def empty!(attribute_name, *args)
-      attribute!(attribute_name, *args, &Representative::EMPTY)
+    def empty
+      Representative::EMPTY
     end
-      
+    
     private 
 
-    def resolve_value(value_generator, subject = subject!)
+    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
       elsif value_generator.respond_to?(:to_proc)

data/spec/representative/xml_spec.rb

@@ -10,8 +10,8 @@ describe Representative::Xml do
     @xml = Builder::XmlMarkup.new
   end
 
-  def represent
-    @xml_representative
+  def r
+    @representative ||= Representative::Xml.new(@xml, @subject)
   end
 
   def resulting_xml
@@ -22,38 +22,37 @@ describe Representative::Xml do
 
     before do
       @subject = OpenStruct.new(:name => "Fred", :width => 200, :vehicle => OpenStruct.new(:year => "1959", :make => "Chevrolet"))
-      @xml_representative = Representative::Xml.new(@xml, @subject)
     end
 
-    describe "calling a method" do
+    describe "#element" do
 
       it "generates an element with content extracted from the subject" do
-        represent.name
+        r.element :name
         resulting_xml.should == %(<name>Fred</name>)
       end
 
-      it "dasherizes the method name" do
+      it "dasherizes the property name" do
         @subject.full_name = "Fredrick"
-        represent.full_name
+        r.element :full_name
         resulting_xml.should == %(<full-name>Fredrick</full-name>)
       end
 
-      describe "with an attribute" do
+      describe "with attributes" do
 
         it "generates attributes on the element" do
-          represent.name(:lang => "fr")
+          r.element :name, :lang => "fr"
           resulting_xml.should == %(<name lang="fr">Fred</name>)
         end
 
         it "dasherizes the attribute name" do
-          represent.name(:sourced_from => "phonebook")
+          r.element :name, :sourced_from => "phonebook"
           resulting_xml.should == %(<name sourced-from="phonebook">Fred</name>)
         end
 
         describe "whose value supports #to_proc" do
 
           it "calls the Proc on the subject to generate a value" do
-            represent.name(:rev => :reverse)
+            r.element :name, :rev => :reverse
             resulting_xml.should == %(<name rev="derF">Fred</name>)
           end
 
@@ -62,7 +61,7 @@ describe Representative::Xml do
         describe "with value nil" do
 
           it "omits the attribute" do
-            represent.name(:lang => nil)
+            r.element :name, :lang => nil
             resulting_xml.should == %(<name>Fred</name>)
           end
 
@@ -70,17 +69,17 @@ describe Representative::Xml do
 
       end
 
-      describe "with a non-Hash argument" do
+      describe "with an explicit value" do
 
         it "generates an element with explicitly provided content" do
-          represent.name("Bloggs")
+          r.element :name, "Bloggs"
           resulting_xml.should == %(<name>Bloggs</name>)
         end
 
-        describe "AND a Hash argument" do
+        describe "AND attributes" do
 
           it "generates attributes on the element" do
-            represent.name("Bloggs", :lang => "fr")
+            r.element :name, "Bloggs", :lang => "fr"
             resulting_xml.should == %(<name lang="fr">Bloggs</name>)
           end
 
@@ -88,37 +87,37 @@ describe Representative::Xml do
 
       end
 
-      describe "with an argument that supports #to_proc" do
+      describe "with a value argument that supports #to_proc" do
 
         it "calls the Proc on the subject to generate a value" do
-          represent.name(:width)
+          r.element :name, :width
           resulting_xml.should == %(<name>200</name>)
         end
 
       end
 
-      describe "with argument :self" do
+      describe "with value argument :self" do
 
         it "doesn't alter the subject" do
-          represent.info(:self) do |info|
-            info.name
+          r.element :info, :self do
+            r.element :name
           end
           resulting_xml.should == %(<info><name>Fred</name></info>)
         end
         
       end
 
-      describe "with a nil argument" do
+      describe "with value argument nil" do
 
         it "builds an empty element" do
-          represent.name(nil)
+          r.element :name, nil
           resulting_xml.should == %(<name/>)
         end
 
-        describe "and a Hash entry value that supports #to_proc" do
+        describe "and attributes" do
 
-          it "omits the attribute" do
-            represent.name(nil, :size => :size)
+          it "omits the attributes" do
+            r.element :name, nil, :size => :size
             resulting_xml.should == %(<name/>)
           end
 
@@ -127,8 +126,8 @@ describe Representative::Xml do
         describe "and a block" do
 
           it "doesn't call the block" do
-            represent.name(nil) do |name|
-              name.foo
+            r.element :name, nil do
+              raise "hell"
             end
             resulting_xml.should == %(<name/>)
           end
@@ -140,41 +139,47 @@ describe Representative::Xml do
       describe "with a block" do
 
         it "generates nested elements" do
-          represent.vehicle do |vehicle|
-            vehicle.year
-            vehicle.make
+          r.element :vehicle do
+            r.element :year
+            r.element :make
           end
           resulting_xml.should == %(<vehicle><year>1959</year><make>Chevrolet</make></vehicle>)
         end
 
+        it "yields each new subject" do
+          r.element :vehicle do |vehicle|
+            vehicle.should == @subject.vehicle
+          end
+        end
+
       end
-      
-    end
 
-    describe "#empty!" do
-      
-      it "generates an empty element" do
-        represent.empty!(:vehicle, :year => :year)
-        resulting_xml.should == %(<vehicle year="1959"/>)
+      describe "with an EMPTY block" do
+
+        it "generates an empty element" do
+          r.element :vehicle, :year => :year, &r.empty
+          resulting_xml.should == %(<vehicle year="1959"/>)
+        end
+
       end
 
     end
     
-    describe "#list_of!" do
+    describe "#list_of" do
 
       before do
         @subject.nick_names = ["Freddie", "Knucklenose"]
       end
 
       it "generates an array element" do
-        represent.list_of!(:nick_names)
+        r.list_of(:nick_names)
         resulting_xml.should == %(<nick-names type="array"><nick-name>Freddie</nick-name><nick-name>Knucklenose</nick-name></nick-names>)
       end
 
       describe "with :list_attributes" do
         
         it "attaches attributes to the array element" do
-          represent.list_of!(:nick_names, :list_attributes => {:color => "blue", :size => :size})
+          r.list_of(:nick_names, :list_attributes => {:color => "blue", :size => :size})
           array_element_attributes = REXML::Document.new(resulting_xml).root.attributes
           array_element_attributes["type"].should == "array"
           array_element_attributes["color"].should == "blue"
@@ -187,7 +192,7 @@ describe Representative::Xml do
       describe "with :item_attributes" do
 
         it "attaches attributes to each item element" do
-          represent.list_of!(:nick_names, :item_attributes => {:length => :size})
+          r.list_of(:nick_names, :item_attributes => {:length => :size})
           resulting_xml.should == %(<nick-names type="array"><nick-name length="7">Freddie</nick-name><nick-name length="11">Knucklenose</nick-name></nick-names>)
         end
         
@@ -195,7 +200,7 @@ describe Representative::Xml do
 
       describe "with an explicit :item_name" do
         it "uses the name provided" do
-          represent.list_of!(:nick_names, :item_name => :nick)
+          r.list_of(:nick_names, :item_name => :nick)
           resulting_xml.should == %(<nick-names type="array"><nick>Freddie</nick><nick>Knucklenose</nick></nick-names>)
         end
       end
@@ -203,7 +208,7 @@ describe Representative::Xml do
       describe "with an argument that resolves to nil" do
 
         it "omits the attribute" do
-          represent.list_of!(:flags)
+          r.list_of(:flags)
           resulting_xml.should == %(<flags/>)
         end
 
@@ -212,19 +217,28 @@ describe Representative::Xml do
       describe "with a block" do
 
         it "generates a nested element for each list element" do
-          represent.list_of!(:nick_names) do |nick_name|
-            nick_name.length
+          r.list_of(:nick_names) do
+            r.element :length
           end
           resulting_xml.should == %(<nick-names type="array"><nick-name><length>7</length></nick-name><nick-name><length>11</length></nick-name></nick-names>)
         end
 
       end
 
+      describe "with an EMPTY block" do
+
+        it "generates empty elements for each list element" do
+          r.list_of(:nick_names, :item_attributes => {:value => :to_s}, &r.empty)
+          resulting_xml.should == %(<nick-names type="array"><nick-name value="Freddie"/><nick-name value="Knucklenose"/></nick-names>)
+        end
+        
+      end
+      
       describe "with :item_attributes AND block" do
         
         it "generates attributes and nested elements" do
-          represent.list_of!(:nick_names, :item_attributes => {:length => :size}) do |nick_name|
-            nick_name.reverse
+          r.list_of(:nick_names, :item_attributes => {:length => :size}) do
+            r.element :reverse
           end
           resulting_xml.should == %(<nick-names type="array"><nick-name length="7"><reverse>eidderF</reverse></nick-name><nick-name length="11"><reverse>esonelkcunK</reverse></nick-name></nick-names>)
         end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 3
-  version: 0.1.3
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Mike Williams
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-24 00:00:00 +10:00
+date: 2010-07-02 00:00:00 +10:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency