kind_dom 0.9.2 → 0.9.3

data/README

@@ -1,32 +1,11 @@
-KindDom provides fail-safe access to the the DOM of an XML document using
-three methods: 
-- #collection_of to select a collection of nodes
-- #first_of to select one node
-- #content_for to get node content.
-
-The original libxml behavior of the parsed document is preserved.
-
-As a contrived example, in the controller:
-   @results = KindDom.new(xml_data)
-
-In the view:
-   <% @results.first_of('//item') do |item| -%>
-    <!-- this block is only executed if `item` is found -->
-    
-     <% item.content_for('title') do |title| -%>
-       <!-- this block is only executed if `title` has content -->
-       <p><%=h title %></p>
-     <% end -%>
-     
-     <% item.content_for('description') do |description| -%>
-       <!-- this block is only executed if `description` has content -->
-       <p><%=h description %></p>
-     <% end -%>
-   <% end -%>
+KindDom provides graceful access to the the DOM of an XML document, while preserving the original libxml behavior of the parsed document.
+
+See the source code comments, rdoc or ri for usage details; the tests also demonstrate use cases.
 
 Project Home http://code.google.com/p/ruby-kind-dom/
 
-(The MIT License)
+
+Licensed under The MIT License.
 
 Copyright (c) 2008 Scout Labs Inc. http://scoutlabs.com
 

data/lib/kind_dom.rb

@@ -3,11 +3,11 @@ require 'active_support'
 require 'xml/libxml'
 
 
-# KindDom provides fail-safe access to the the DOM of an XML document using
-# three methods: 
-# - #collection_of to select a collection of nodes
-# - #first_of to select one node
-# - #content_for to get node content.
+# KindDom provides graceful access to the the DOM of an XML document using
+# three methods of Kindness: 
+# - <tt>#collection_of</tt> to select a collection of nodes
+# - <tt>#first_of</tt> to select one node
+# - <tt>#content_for</tt> to get node content.
 #
 # The original libxml behavior of the parsed document is preserved.
 #
@@ -15,17 +15,18 @@ require 'xml/libxml'
 #    @results = KindDom.new(xml_data)
 # 
 # In the view:
+#    
 #    <% @results.first_of('//item') do |item| -%>
-#     <!-- this block is only executed if `item` is found -->
-#   
+#      <p>(This block is only executed if `item` is found.)</p>
+#    
 #      <% item.content_for('title') do |title| -%>
-#        <!-- this block is only executed if `title` has content -->
-#        <p><%=h title %></p>
+#        <h2><%=h title %></h2>
+#        <p>(This block is only executed if `title` has content.)</p>
 #      <% end -%>
-#    
+#     
 #      <% item.content_for('description') do |description| -%>
-#        <!-- this block is only executed if `description` has content -->
 #        <p><%=h description %></p>
+#        <p>(This block is only executed if `description` has content.)</p>
 #      <% end -%>
 #    <% end -%>
 #
@@ -50,12 +51,10 @@ class KindDom < ObjectProxy
     #
     # Optional second argument is the default value to return if the DOM find fails.
     #
-    # When a block is provided, it will be used to transform the found content 
+    # When a block is provided, it will be called with the found content 
     # (or default) before returning.
     #
-    # The block should except one argument: the content to tranform.
-    #
-    def content_for(xpath, default=nil)
+    def content_for(xpath, default=nil)       # :yields: found_content
       node = case self.class.to_s
       when 'XML::Document' then
         root.find_first(xpath)
@@ -82,10 +81,10 @@ class KindDom < ObjectProxy
     #
     # Each node is extended with Kindness to support #content_for, #collection_of & #first_of.
     #
-    # When a block is provided, it will be used to transform the found collection 
+    # When a block is provided, it will be called with the found collection 
     # (or default) before returning.
     #
-    def collection_of(xpath, default=nil)
+    def collection_of(xpath, default=nil)      # :yields: found_collection
       c = find(xpath).collect {|n| n.extend Kindness }
     rescue NoMethodError
     ensure
@@ -101,10 +100,10 @@ class KindDom < ObjectProxy
     #
     # The node is extended with Kindness to support #content_for, #collection_of & #first_of.
     #
-    # When a block is provided, it will be used to transform the found node 
+    # When a block is provided, it will be called with the found node 
     # (or default) before returning.
     #
-    def first_of(xpath, default=nil)
+    def first_of(xpath, default=nil)      # :yields: found_node
       n = case self.class.to_s
       when 'XML::Document' then
         root.find_first(xpath)

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: kind_dom
 version: !ruby/object:Gem::Version 
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors: 
 - Mars Hall
-autorequire: kind_dom
+autorequire: 
 bindir: bin
 cert_chain: []