traverse 0.0.3 → 0.1.0

data/README.md

@@ -1,12 +1,20 @@
 # Traverse
 
-Traverse is a simple tool that makes it easy to traverse XML. 
+```bash
+gem install traverse
+```
+
+## Introduction
+
+Traverse is a simple tool that makes it easy to traverse XML and JSON.
 
-Let's say you're messing around with Twitter's
+Let's say you're messing around with Twitter's XML
 [public timeline](http://api.twitter.com/statuses/public_timeline.xml).
 Traverse let's you do things like this:
  
 ```ruby
+require 'open-uri'
+
 timeline = Traverse::Document.new(open "http://api.twitter.com/statuses/public_timeline.xml")
 
 timeline.statuses.each do |status|
@@ -14,6 +22,18 @@ timeline.statuses.each do |status|
 end
 ```
 
+Or, let's say you're foolin' with Spotify's JSON [Search
+API](http://ws.spotify.com/search/1/track.json?q=like+a+virgin).
+
+```ruby
+search = Traverse::Document.new(open "http://ws.spotify.com/search/1/track.json?q=like+a+virgin")
+
+search.tracks.each do |track|
+  puts "Track: #{track.name}"
+  puts "Album: #{track.album.name}"
+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.
@@ -22,8 +42,6 @@ pulled from Major League Baseball's public API.
 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'
@@ -36,3 +54,158 @@ boxscore.pitchings.find do |pitching|
   pitching.team_flag == 'away'
 end.out # => '24'
 ```
+
+## Traverse's XML API
+
+When in doubt, check the spec file.
+
+### Children
+
+Let's say you're working with the following node of XML:
+
+```xml
+<foo>
+  <bar ...>
+    ...
+  </bar>
+</foo>
+```
+
+Assuming you've wrapped the XML in a `Traverse::Document` named `foo`, you can
+traverse to the `bar` node with a simple method call:
+
+```ruby
+foo.bar # => returns a representation of the bar node
+```
+
+If there are in fact many `bar`s inside `foo`, Traverse will transparently
+collect them in an array. You can access that array by pluralizing the name of
+the individual nodes:
+
+```ruby
+foo.bars # => an array containing all of the bars
+foo.bars.first # => grab the first bar
+```
+
+Traverse will also do its best to transparently collect singularly-named nodes
+inside of pluralized parents. Example:
+
+```xml
+<foo>
+  <bars>
+    <bar ...>
+      ...
+    </bar>
+    ...
+    <bar ...>
+      ...
+    </bar>
+  </bars>
+</foo>
+```
+```ruby
+foo.bars # => an array of all of the bars
+foo.bars.first # => the first bar
+```
+
+This won't work if the pluralized parent node has attributes or if its children
+aren't all singularized versions of itself! Twitter's timeline is an example;
+the parent node's name is `statuses`, and its children are all named
+`status`, but the `statuses` node has an attribute.
+
+### Attributes
+
+If your XML node has an attribute named `foo`, you can access that attribute
+with a simple method call:
+
+```ruby
+my_node.foo # => return the attribute's value
+```
+
+Notice that there might be a conflict if your node has both an attribute named
+`foo` _and_ a child `foo`. Traverse puts children first, so the attribute `foo`
+will get clobbered.
+
+To get around this, Traverse provides a backdoor for when you really want the
+attribute:
+
+```ruby
+my_node.foo # => grabs the child named foo
+my_node['foo'] # => grabs the attribute named foo
+```
+
+### Text
+
+If you traverse to a node that has no attributes and contains only text, you
+can grab that text with a simple method call. Let's suppose you have the
+following XML:
+
+```xml
+<foo>
+  <bar>
+    This bar rocks!
+  </bar>
+</foo>
+```
+
+You can grab the text like this:
+
+```ruby
+foo.bar # => "This bar rocks!"
+```
+
+What if `bar` does have attributes? Then you'll need to use the `text` method:
+
+```xml
+<foo>
+  <bar baz="quux">
+    This bar rocks!
+  </bar>
+</foo>
+```
+```ruby
+foo.bar # => grabs a representation of the node, not the text!
+foo.bar.text # => "This bar rocks!"
+```
+
+I know what you're thinking: what the hell do I do if my node has text inside
+it but I want to grab its attribute named `text`???
+
+```ruby
+foo.bar['text'] # => grab bar's attribute named 'text'
+foo.bar.text # => grab bar's text contents
+```
+
+## Traverse's JSON API
+
+Again, when in doubt, check the spec file.
+
+Traverse doesn't really do anything magical with JSON data; under the hood, it
+uses `YAJL` to parse JSON into a `Hash`, and hashes are alredy pretty
+traversable in Ruby. But, to maintain consistency with the XML API, you can
+happily traverse JSON using method calls instead of querying a hash.
+
+## Helper methods
+Traverse provides a few helper methods to help with traversal.
+
+If you're traversing some JSON, the ```_keys_``` method will be available. It
+returns an array containing the names of the JSON object's keys.
+
+```ruby
+search._keys_.count
+# =>  2
+
+search.first._keys_
+# =>  ["user","favorited","source","id","text","created_at"]
+```
+
+If you're looking at XML, the ```_children_``` and ```_attributes_``` methods
+will be available. The ```_children_``` method gives you an array of
+traversable child nodes, and ```_attributes_``` gives you a hash of
+attribute-name/attribute-value pairs.
+
+## Contributors!
+
+Traverse wouldn't be possible without help from friends. Thanks!
+
+- [muffs](https://github.com/muffs)

data/Rakefile

@@ -2,5 +2,7 @@ require 'bundler/gem_tasks'
 
 desc 'run the spec'
 task "spec" do
-  load './spec/spec.rb'
+  Dir.glob('spec/*.rb') do |spec|
+    load spec
+  end
 end

data/lib/traverse.rb

@@ -1,10 +1,53 @@
 require "traverse/version"
 require 'nokogiri'
-require 'open-uri'
+require 'yajl'
 require 'active_support/inflector'
 
 module Traverse
   class Document
+    def initialize document
+      if xml? document
+        @proxy = XML.new document
+      elsif json? document
+        @proxy = JSON.new document
+      end
+    end
+
+    private
+      def method_missing m, *args, &block
+        @proxy.send m, *args, &block
+      end
+
+      def xml? document
+        begin
+          Nokogiri::XML(document) do |config|
+            config.options = Nokogiri::XML::ParseOptions::STRICT
+          end
+          true
+        rescue Nokogiri::XML::SyntaxError
+          false
+        ensure
+          document.rewind if document.respond_to? :read
+        end
+      end
+
+      def json? document
+        begin
+          Yajl::Parser.new.parse(document)
+          true
+        rescue Yajl::ParseError
+          false
+        ensure
+          document.rewind if document.respond_to? :read
+        end
+      end
+
+      def to_s
+        "<Traverse::Document...>"
+      end
+  end
+
+  class XML
     def initialize document
       setup_underlying_document document
 
@@ -23,7 +66,7 @@ module Traverse
             end
           else
             define_singleton_method name do 
-              Document.new child
+              XML.new child
             end
           end
         else
@@ -32,7 +75,7 @@ module Traverse
               if text_only_node? child
                 child.content.strip
               else
-                Document.new child
+                XML.new child
               end
             end
           end
@@ -43,7 +86,7 @@ module Traverse
         define_singleton_method pluralized_child.name do
           pluralized_child.children.reject do |baby|
             baby.class == Nokogiri::XML::Text
-          end.map { |child| Document.new child }
+          end.map { |child| XML.new child }
         end
       end
 
@@ -53,15 +96,15 @@ module Traverse
       @document.get_attribute attr
     end
 
-    def attributes
+    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 }
+    def _children_
+      real_children.map { |child| XML.new child }
     end
 
     private
@@ -145,4 +188,61 @@ module Traverse
         "<Traversable... >"
       end
   end
+
+  class JSON
+
+    def initialize json
+
+      setup_underlying_json json
+
+      if @json.is_a? Array
+        @proxy = @json.map do |item|
+          JSON.new item
+        end
+      elsif @json.is_a? Hash
+        @json.each_pair do |k,v|
+          define_singleton_method k do
+            if v.is_a? Hash
+              JSON.new(v)
+            elsif v.is_a? Array
+              v.map { |i| JSON.new(i) }
+            else
+              v
+            end
+          end
+          define_singleton_method "_keys_" do
+            @json.keys
+          end
+        end
+      elsif @json.is_a? Array
+        @json.map! { |i| JSON.new i }
+      end
+    end
+
+    private
+      def method_missing m, *args, &block
+        if @proxy
+          @proxy.send m, *args, &block
+        else
+          super
+        end
+      end
+      
+      def setup_underlying_json document
+        if document.is_a? String
+          @json = Yajl::Parser.new.parse document
+        elsif document.respond_to? :read # Tempfile / StringIO
+          begin
+            parser = Yajl::Parser.new
+            @json = parser.parse(document)
+          rescue
+            nil
+          ensure
+            document.rewind
+          end
+        elsif document.is_a? Hash
+          @json = document
+        end
+      end
+  end
 end

data/lib/traverse/version.rb

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

data/spec/json.rb

@@ -0,0 +1,43 @@
+require 'traverse'
+
+gem 'minitest'
+require 'minitest/autorun'
+require 'minitest/pride'
+
+json = %{
+  {
+    "menu": {
+      "id": "file",
+      "value": "File",
+      "popup": {
+        "menuitem": [
+          {"value": "New", "onclick": "CreateNewDoc()"},
+          {"value": "Open", "onclick": "OpenDoc()"},
+          {"value": "Close", "onclick": "CloseDoc()"}
+        ]
+      }
+    }
+  }
+}
+
+describe Traverse::Document do
+  before do
+    @doc = Traverse::Document.new json
+  end
+
+  describe "Grabbing simple attributes" do
+    it "helps you access attributes" do
+      @doc.menu.id.must_equal "file"
+    end
+  end
+
+  describe "Grabbing attributes that are arrays" do
+    it "knows how to handle json arrays" do
+      @doc.menu.popup.menuitem.count.must_equal 3
+    end
+
+    it "traversifies the elements of json arrays" do
+      @doc.menu.popup.menuitem.last.value.must_equal "Close"
+    end
+  end
+end

data/spec/{spec.rb → xml.rb}

@@ -1,4 +1,3 @@
-$:.push '../'
 require 'traverse'
 
 gem 'minitest'
@@ -38,7 +37,7 @@ xml = %{
         expert. Not a genius, exactly, more like an idiot savant with X-ray
         vision.
       </quotation>
-    </quotes>
+    </quotations>
     <review reviewer="Salman Rushdie">
       What is interesting is to have before us, at the end of the Greed
       Decade, that rarest of birds: a major political novel about what
@@ -59,66 +58,70 @@ describe Traverse::Document do
     @book = Traverse::Document.new xml
   end
 
-  it "helps you access attributes" do
-    @book.title.must_equal "Vineland"
-  end
+  describe "Grabbing attributes" do
+    it "helps you access attributes" do
+      @book.title.must_equal "Vineland"
+    end
 
-  it "also helps you access attributes shadowed by children" do
-    @book.author.wont_equal "Thomas Pynchon"
-    @book['author'].must_equal "Thomas Pynchon"
-    @book.author.name.must_equal "Thomas Pynchon"
-  end
+    it "also lets you access attributes shadowed by children" do
+      @book.author.wont_equal "Thomas Pynchon"
+      @book.author.class.wont_equal String
 
-  describe "support for enumerable" do
+      @book['author'].must_equal "Thomas Pynchon"
+    end
+  end
 
-    it "gives you access to the current node's attributes" do
-      @book.attributes.any? do |name, value|
-        value == "Vineland"
-      end.must_equal true
+  describe "Traversing to children" do
+    it "helps you traverse to child nodes" do
+      @book.review.reviewer.must_equal "Salman Rushdie"
+      @book.epigraph.author.must_equal "Johnny Copeland"
     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
+    it "knows to collect children with the same name" do
+      @book.author.books.class.must_equal Array
+      @book.author.books.count.must_equal 8
+      assert @book.author.books.all? do |book|
+        book.is_a? String
       end
     end
 
+    it "knows to collect singularized children of a pluralized parent" do
+      @book.quotations.count.must_equal 2
+      @book.quotations.last.text.must_match(/more like an idiot savant/)
+    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
+  describe "Dealing with text nodes" do
+    it "handles annoying text nodes transparently" do
+      @book.epigraph.text.must_match(/Every dog has his day/)
+      @book.review.text.must_match(/that rarest of birds/)
+    end
 
-  it "knows when a node contains only text" do
-    assert @book.epigraph.send(:text_node?)
-  end
+    it "nevertheless handles attributes named 'text'" do
+      @book.text['text'].must_match(/seriously/)
+      @book.text.text.must_match(/rilly/)
+    end
 
-  it "handles annoying text nodes transparently" do
-    @book.epigraph.text.must_match(/Every dog has his day/)
-    @book.review.text.must_match(/that rarest of birds/)
+    it "handles nodes with only text and no attributes" do
+      @book.pagecount.must_equal "385"
+    end
   end
 
-  it "nevertheless handles attributes named 'text'" do
-    @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
-    @book.pagecount.must_equal "385"
-  end
+  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 "knows to collect children with the same name" do
-    @book.author.books.count.must_equal 8
-    assert @book.author.books.all? do |book|
-      book.is_a? String
+    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 "knows to collect children of a pluralized parent" do
-    @book.quotations.count.must_equal 2
-    @book.quotations.last.text.must_match(/more like an idiot savant/)
-  end
 end

data/traverse.gemspec

@@ -5,11 +5,11 @@ require "traverse/version"
 Gem::Specification.new do |s|
   s.name        = "traverse"
   s.version     = Traverse::VERSION
-  s.authors     = ["happy4crazy"]
+  s.authors     = ["happy4crazy", "muffs"]
   s.email       = ["alan.m.odonnell@gmail.com"]
   s.homepage    = "https://github.com/happy4crazy/traverse"
-  s.summary     = %q{Easily traverse an XML document.}
-  s.description = %q{Easily traverse an XML document.}
+  s.summary     = %q{Easily traverse XML and JSON.}
+  s.description = %q{Easily traverse XML and JSON.}
 
   s.rubyforge_project = "traverse"
 
@@ -18,5 +18,9 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_development_dependency 'minitest'
   s.add_dependency 'nokogiri', '~> 1.5'
+  s.add_dependency 'active_support'
+  s.add_dependency 'i18n'
+  s.add_dependency 'yajl-ruby'
 end

metadata

@@ -1,20 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: traverse
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
 - happy4crazy
+- muffs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-08-05 00:00:00.000000000 -04:00
+date: 2011-08-18 00:00:00.000000000 -04:00
 default_executable: 
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &2157763120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2157763120
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2152908620 !ruby/object:Gem::Requirement
+  requirement: &2157762620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,8 +34,41 @@ dependencies:
         version: '1.5'
   type: :runtime
   prerelease: false
-  version_requirements: *2152908620
-description: Easily traverse an XML document.
+  version_requirements: *2157762620
+- !ruby/object:Gem::Dependency
+  name: active_support
+  requirement: &2157762200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2157762200
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: &2152011700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152011700
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: &2152011280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152011280
+description: Easily traverse XML and JSON.
 email:
 - alan.m.odonnell@gmail.com
 executables: []
@@ -36,7 +81,8 @@ files:
 - Rakefile
 - lib/traverse.rb
 - lib/traverse/version.rb
-- spec/spec.rb
+- spec/json.rb
+- spec/xml.rb
 - traverse.gemspec
 has_rdoc: true
 homepage: https://github.com/happy4crazy/traverse
@@ -62,6 +108,7 @@ rubyforge_project: traverse
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: Easily traverse an XML document.
+summary: Easily traverse XML and JSON.
 test_files:
-- spec/spec.rb
+- spec/json.rb
+- spec/xml.rb