traverse 0.0.2 → 0.0.3

data/README.md

@@ -1,3 +1,38 @@
 # Traverse
 
-Traverse is a simple tool that makes it easy to traverse XML.
+Traverse is a simple tool that makes it easy to traverse XML. 
+
+Let's say you're messing around with Twitter's
+[public timeline](http://api.twitter.com/statuses/public_timeline.xml).
+Traverse let's you do things like this:
+ 
+```ruby
+timeline = Traverse::Document.new(open "http://api.twitter.com/statuses/public_timeline.xml")
+
+timeline.statuses.each do |status|
+  puts "#{status.user.name} says: #{status.text}"
+end
+```
+
+For a slightly more complicated example, take a look at a
+[boxscore](http://gd2.mlb.com/components/game/mlb/year_2011/month_03/day_31/gid_2011_03_31_detmlb_nyamlb_1/boxscore.xml)
+pulled from Major League Baseball's public API.
+
+```ruby
+url = "http://gd2.mlb.com/components/game/mlb/year_2011/month_03/day_31/gid_2011_03_31_detmlb_nyamlb_1/boxscore.xml"
+boxscore = Traverse::Document.new(open url)
+
+# let's start traversing!
+
+boxscore.game_id # => '2011/03/31/detmlb-nyamlb-1'
+
+boxscore.battings[0].batters[1].name_display_first_last # => 'Derek Jeter'
+
+boxscore.battings[0].batters.select do |batter|
+  batter.rbi.to_i > 0
+end.count # => 4
+
+boxscore.pitchings.find do |pitching|
+  pitching.team_flag == 'away'
+end.out # => '24'
+```

data/lib/traverse/version.rb

@@ -1,3 +1,3 @@
 module Traverse
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/traverse.rb

@@ -53,24 +53,26 @@ module Traverse
       @document.get_attribute attr
     end
 
+    def attributes
+      name_value_pairs = @document.attributes.map do |name, attribute|
+        [name, attribute.value]
+      end
+      Hash[ name_value_pairs ]
+    end
+
+    def children
+      real_children.map { |child| Document.new child }
+    end
+
     private
       def method_missing m, *args, &block
         self[m] or super
       end
 
-      def attributes
-        if @document.is_a? Nokogiri::XML::Document
-          []
-        else
-          @document.attributes
-        end
-      end
-
       def text_node?
-        num_children = @document.children.count
-        return false unless num_children == 1
-
-        @document.children.first.is_a? Nokogiri::XML::Text
+        @document.children.all? do |child|
+          child.is_a? Nokogiri::XML::Text
+        end
       end
 
       def text_only_node? node
@@ -103,7 +105,7 @@ module Traverse
         real_children.select do |child|
           child.children.all? do |baby|
             if baby.class == Nokogiri::XML::Text
-              true
+              true # ignore text children
             else
               baby.name == child.name.singularize
             end
@@ -111,12 +113,28 @@ module Traverse
         end
       end
 
+      def find_first_non_comment_node xml_string
+        Nokogiri::XML(xml_string).children.find do |child|
+          !child.comment?
+        end
+      end
+
       def setup_underlying_document document
         if document.is_a? String
           begin
-            @document = Nokogiri::XML(document)
+            @document = find_first_non_comment_node document
           rescue
-            return nil
+            nil
+          end
+        elsif document.respond_to? :read # is it file-like...
+          begin
+            @document = find_first_non_comment_node document.read
+          rescue
+            nil
+          end
+        elsif document.is_a? Nokogiri::XML::Document
+          @document = document.children.find do |child|
+            !child.comment?
           end
         else
           @document = document
@@ -127,18 +145,4 @@ module Traverse
         "<Traversable... >"
       end
   end
-
-  module Proxy
-    private
-      def proxy *args
-        if args.empty?
-          @proxy
-        else
-          @proxy = args.first
-          def method_missing m
-            @proxy.send m
-          end
-        end
-      end
-  end
 end

data/spec/spec.rb

@@ -56,51 +56,69 @@ xml = %{
 
 describe Traverse::Document do
   before do
-    @doc = Traverse::Document.new xml
+    @book = Traverse::Document.new xml
   end
 
   it "helps you access attributes" do
-    @doc.book.title.must_equal "Vineland"
+    @book.title.must_equal "Vineland"
   end
 
   it "also helps you access attributes shadowed by children" do
-    @doc.book.author.wont_equal "Thomas Pynchon"
-    @doc.book['author'].must_equal "Thomas Pynchon"
-    @doc.book.author.name.must_equal "Thomas Pynchon"
+    @book.author.wont_equal "Thomas Pynchon"
+    @book['author'].must_equal "Thomas Pynchon"
+    @book.author.name.must_equal "Thomas Pynchon"
   end
 
-  it "helps you get at child nodes" do
-    @doc.book.review.reviewer.must_equal "Salman Rushdie"
-    @doc.book.epigraph.author.must_equal "Johnny Copeland"
+  describe "support for enumerable" do
+
+    it "gives you access to the current node's attributes" do
+      @book.attributes.any? do |name, value|
+        value == "Vineland"
+      end.must_equal true
+    end
+
+    it "gives you access to the current node's children as traversable documents" do
+      assert @book.children.any? do |child|
+        child.attributes.any? do |name, value|
+          name == "reviewer" and value == "Salman Rushdie"
+        end
+      end
+    end
+
+  end
+
+  it "helps you traverse to child nodes" do
+    @book.review.reviewer.must_equal "Salman Rushdie"
+    @book.epigraph.author.must_equal "Johnny Copeland"
   end
 
   it "knows when a node contains only text" do
-    assert @doc.book.epigraph.send(:text_node?)
+    assert @book.epigraph.send(:text_node?)
   end
 
   it "handles annoying text nodes transparently" do
-    @doc.book.epigraph.text.must_match(/Every dog has his day/)
-    @doc.book.review.text.must_match(/that rarest of birds/)
+    @book.epigraph.text.must_match(/Every dog has his day/)
+    @book.review.text.must_match(/that rarest of birds/)
   end
 
   it "nevertheless handles attributes named 'text'" do
-    @doc.book.text['text'].must_match(/seriously/)
-    @doc.book.text.text.must_match(/rilly/)
+    @book.text['text'].must_match(/seriously/)
+    @book.text.text.must_match(/rilly/)
   end
 
   it "knows when a node has only text and no attributes" do
-    @doc.book.pagecount.must_equal "385"
+    @book.pagecount.must_equal "385"
   end
 
   it "knows to collect children with the same name" do
-    @doc.book.author.books.count.must_equal 8
-    assert @doc.book.author.books.all? do |book|
+    @book.author.books.count.must_equal 8
+    assert @book.author.books.all? do |book|
       book.is_a? String
     end
   end
 
   it "knows to collect children of a pluralized parent" do
-    @doc.book.quotations.count.must_equal 2
-    @doc.book.quotations.last.text.must_match(/more like an idiot savant/)
+    @book.quotations.count.must_equal 2
+    @book.quotations.last.text.must_match(/more like an idiot savant/)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traverse
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-03 00:00:00.000000000 -04:00
+date: 2011-08-05 00:00:00.000000000 -04:00
 default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2157314300 !ruby/object:Gem::Requirement
+  requirement: &2152908620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,7 +22,7 @@ dependencies:
         version: '1.5'
   type: :runtime
   prerelease: false
-  version_requirements: *2157314300
+  version_requirements: *2152908620
 description: Easily traverse an XML document.
 email:
 - alan.m.odonnell@gmail.com