rpath 1.0.1 → 1.1.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MTRkMWY4ZDJmNzk1MGM0ZTg3MGNmZWNkMjM4YjUxNjAyM2FiYWIxYQ==
-  data.tar.gz: !binary |-
-    NDgxYmM5N2EzNjk0N2I3ZDFhM2M2MmU0ZTlmN2M2MjQ2NTA3MjBkOQ==
+SHA1:
+  metadata.gz: ca43180768c5384613ebf5bee029b8e05b7d0875
+  data.tar.gz: 7e86e33589477ab8d9a62e1ccf5dde9154fcf3fc
 SHA512:
-  metadata.gz: !binary |-
-    MmM5ZjE5MjE3MmVhMDkxYTIwODkxY2FhZWVhMjJkZGQwNjQ0NDk0MTBhYjU0
-    YzgyOWI0ZTFmYWFlNzlkNDNlNGE4ODRkMGI4MjRlN2RiNmEyYThlNTk0YzM3
-    MzVjNDYwM2RiZDNjYThiNmIwMjUwNTRjMmQ3ZGJjODI0ZGY4YmM=
-  data.tar.gz: !binary |-
-    MDIxOTQwM2RhMDYwODY1OWUzY2QyY2NjYzBjNjU1Y2M1Yzg3NzFiNzAyMzQw
-    NTFjMzNiZTg4Y2E5NDFmODQyZGVmY2Y5MTllNWY3YTdlYzgxODgzMTE3ZDEx
-    YjBjNDk3YzYwMmVhY2IwZWZhZTdlNDViODgwZTRkOWQ2ZDM4OTA=
+  metadata.gz: d703e513a8e18b418148812010799d76b140ddebf74f67505772d5ab8a4bfdce69ed65f90c83191d74a0a7831efca6781a40002439e6e8010e0aa3b91bcddc35
+  data.tar.gz: a3ebe23c2b83ca6f24a53ee78e7e04315e7ea5295a730723c678190e5a16b0e10f639ff254b88f9ef536e25caf296d382f573f3092e5b36dbdaaeb601ccdec36

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+-
+README.md
+LICENSE.txt

data/README.md

@@ -1,14 +1,15 @@
 # RPath
 
-"Don't do this." —[flavorjones](https://github.com/flavorjones) [[1]](http://www.nokogiri.org/tutorials/searching_a_xml_html_document.html)
+"Don't use this." —[flavorjones](https://github.com/flavorjones) [[1]](http://www.nokogiri.org/tutorials/searching_a_xml_html_document.html)
 
 [![Gem Version](https://badge.fury.io/rb/rpath.svg)](http://badge.fury.io/rb/rpath)
+[![Build Status](https://travis-ci.org/jonahb/rpath.svg?branch=master)](https://travis-ci.org/jonahb/rpath)
 
 ## Overview
 
-RPath lets you traverse graphs, such as XML documents, with just Ruby.
+RPath lets you query graphs, such as XML documents, with just Ruby.
 
-RPath can operate on [Nokogiri](http://www.nokogiri.org) documents, [REXML](http://www.germane-software.com/software/rexml/) documents, and the filesystem. Building adapters for other graphs is simple.
+RPath can operate on [Nokogiri](http://www.nokogiri.org) documents, [REXML](http://www.germane-software.com/software/rexml/) documents, [Oga](https://github.com/YorickPeterse/oga) documents, and the filesystem. Building adapters for other graphs is simple.
 
 Leading members of the Ruby community have [warned against](http://www.nokogiri.org/tutorials/searching_a_xml_html_document.html) RPath's approach. They're probably right! RPath is as much an experiment as a useful tool.
 
@@ -52,13 +53,13 @@ exp = RPath { places.place[:name] }
 exp.eval(xml) # => "Green-Wood"
 ```
 
-Or, if we only plan to use the expression once, we can combine the two lines above, passing the graph to `RPath`. RPath evaluates the expression and returns the result:
+If we only plan to use the expression once, we can pass the graph to `RPath`. RPath evaluates the expression and returns the result:
 
 ```ruby
 RPath(xml) { places.place[:name] } # => "Green-Wood"
 ```
 
-For even more succinct syntax, RPath adds to Nokogiri the `#rpath` method:
+Some adapters, such as the built-in Nokogiri adapter, may add convenience methods that make the syntax even prettier:
 
 ```ruby
 xml.rpath { places.place[:name] } # => "Green-Wood"
@@ -74,11 +75,11 @@ In an RPath [graph](http://en.wikipedia.org/wiki/Graph_(mathematics)),
 * Each vertex has zero or more named attributes, and
 * Each vertex may have associated data called "content."
 
-RPath expressions assume only this abstract model. They can be applied to any graph for which there is an adapter.
+Adapters implement this abstraction for a particular type of graph. RPath can operate on any graph for which there is an adapter.
 
 ## Expressions
 
-An RPath expression, given a graph, produces a value—a vertex, a vertex array, the value of an attribute, or a vertex's content. RPath expressions are constructed by chaining methods inside the block passed to `RPath`.
+An RPath expression, given a graph, selects a value—a vertex, a vertex array, the value of an attribute, or a vertex's content. RPath expressions are constructed by chaining methods inside the block passed to `RPath`.
 
 ### Selecting Vertices
 
@@ -202,6 +203,16 @@ xml = REXML::Document.new('<foo bar="baz"/>')
 xml.rpath { foo['bar'] } # => "baz"
 ```
 
+### Oga
+
+RPath expressions may be evaluated on an `Oga::XML::Document` or an `Oga::XML::Element`.
+
+```ruby
+RPath.use :oga
+xml = Oga.parse_xml('<foo bar="baz"/>')
+xml.rpath { foo['bar'] } # => "baz"
+```
+
 ### Filesystem
 
 The filesystem adapter exposes files and directories as vertices. Directory entries are adjacent to their directory. Expressions may be evaluated on any directory:
@@ -227,36 +238,44 @@ RPath('/', :filesystem) { etc.hostname.content } # => "jbook"
 
 ## Custom Adapters
 
-Custom adapters are subclasses of `RPath::Adapter`. They implement three abstract methods: `#adjacent`, `#attribute`, and `#content`. See the implementations in `RPath::Adapters` for examples.
+Custom adapters allow RPath expressions to operate on new types of graphs. To create a custom adapter, subclass `RPath::Adapter` and implement the abstract methods `#adjacent`, `#attribute`, `#content`, and `#name`. See the implementations in `RPath::Adapters` for examples.
+
+Once you've implemented a custom adapter, pass an instance to `#RPath`:
+
+```ruby
+RPath(graph, CustomAdapter.new) { foo.bar }
+```
 
-Register a custom adapter by passing an instance to `RPath.use`:
+To avoid creating an instance for every evaluation, register the adapter and pass the underscored, symbolized class to `RPath`:
 
 ```ruby
-RPath.use MapsAdapter.new
+RPath.use CustomAdapter.new
+RPath(graph, :custom_adapter) { foo.bar }
 ```
 
-To use the adapter, pass the underscored, symbolized class name as the second argument to `RPath` or `RPath::Expression#eval`:
+If that's too long, pass a custom ID to `RPath.use`:
 
 ```ruby
-RPath(map, :maps_adapter) { ... }
+RPath.use CustomAdapter.new, :custom
+RPath(graph, :custom) { foo.bar }
 ```
 
-You can eliminate the need to specify the adapter by implementing `RPath::Adapter#adapts?`:
+Or, to avoid specifying the adapter altogether—as the built-in XML adapters do—implement `#adapts?` in your adapter class:
 
 ```ruby
-class MapsAdapter < RPath::Adapter
+class CustomAdapter < RPath::Adapter
   def adapts?(graph)
-    graph.is_a? Map
+    graph.is_a? CustomGraph
   end
-  ...
+  # ...
 end
 ```
 
-Now RPath will select `MapsAdapter` when an expression is evaluated on a `Map`:
+Now RPath will select a registered `CustomAdapter` when an expression is evaluated on a `CustomGraph`:
 
 ```ruby
-RPath.use MapsAdapter.new
-RPath(Map.new) { ... }
+RPath.use CustomAdapter.new
+RPath(CustomGraph.new) { foo.bar }
 ```
 
 ## Contributing

data/lib/rpath/adapters.rb

@@ -2,6 +2,7 @@ module RPath
   module Adapters
     autoload :Filesystem, 'rpath/adapters/filesystem'
     autoload :Nokogiri, 'rpath/adapters/nokogiri'
+    autoload :Oga, 'rpath/adapters/oga'
     autoload :REXML, 'rpath/adapters/rexml'
   end
 end

data/lib/rpath/adapters/oga.rb

@@ -0,0 +1,79 @@
+require 'oga'
+
+module RPath
+  module Adapters
+
+    class Oga < RPath::Adapter
+
+      # Returns +true+ iff +graph+ is an Oga::XML::Document or an Oga::XML::Element
+      # @param [Object] graph
+      # @return [Boolean]
+      def adapts?(graph)
+        graph.is_a?(::Oga::XML::Element) || graph.is_a?(::Oga::XML::Document)
+      end
+
+      # Returns the name of the given node
+      # @param [Oga::XML::Document, Oga::XML::Element] vertex
+      # @return [String]
+      def name(vertex)
+        vertex.is_a?(::Oga::XML::Element) ? vertex.name : nil
+      end
+
+      # Returns the child elements of the given node
+      # @param [Oga::XML::Document, Oga::XML::Element] vertex
+      # @return [Array<Oga::XML::Element>]
+      def adjacent(vertex)
+        vertex.children.select { |child| child.is_a?(::Oga::XML::Element) }
+      end
+
+      # Returns the value of the named attribute on the given node.
+      # @param [Oga::XML::Document, Oga::XML::Element] vertex
+      # @param [String, Symbol] name
+      # @return [String, nil]
+      def attribute(vertex, name)
+        if vertex.is_a?(::Oga::XML::Element)
+          attr = vertex.attr(name)
+          attr && attr.value
+        else
+          nil
+        end
+      end
+
+      # Returns the text content of the given node.
+      # @param [Oga::XML::Document, Oga::XML::Element] vertex
+      # @return [String, nil]
+      def content(vertex)
+        vertex.is_a?(::Oga::XML::Element) ? vertex.text : nil
+      end
+    end
+
+  end
+end
+
+class Oga::XML::Document
+  # Evaluates an RPath expression on the document
+  # @example
+  #   RPath.use :oga
+  #   xml = Oga.parse_xml('<foo bar="baz"/>')
+  #   xml.rpath { foo['bar'] } # => "baz"
+  # @see #RPath
+  # @return [Object]
+  #
+  def rpath(&block)
+    RPath self, :oga, &block
+  end
+end
+
+class Oga::XML::Element
+  # Evaluates an RPath expression on the element
+  # @example
+  #   RPath.use :oga
+  #   xml = Oga.parse_xml('<foo><bar baz="qux"/></foo>')
+  #   xml.children.first.rpath { bar['baz'] } # => "qux"
+  # @see #RPath
+  # @return [Object]
+  #  
+  def rpath(&block)
+    RPath self, :oga, &block
+  end
+end

data/lib/rpath/expressions.rb

@@ -14,7 +14,7 @@ module RPath
     # @return [Object]
     # @raise [RuntimeError]
     #   The adapter can't be determined
-    # @ raise [ArgumentError]
+    # @raise [ArgumentError]
     #   +adapter+ is not an {Adapter}, Symbol, or nil
     # @see #RPath
     # @see RPath.use
@@ -24,7 +24,7 @@ module RPath
       when RPath::Adapter
         adapter
       when Symbol
-        Registry.find adapter.to_sym
+        Registry.find adapter
       when nil
         Registry.infer graph
       else

data/lib/rpath/version.rb

@@ -1,3 +1,3 @@
 module RPath
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,69 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: rpath
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonah Burke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-03 00:00:00.000000000 Z
+date: 2015-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.6.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: oga
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.7
 description: 
@@ -73,6 +87,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE.txt
 - README.md
 - lib/rpath.rb
@@ -80,6 +95,7 @@ files:
 - lib/rpath/adapters.rb
 - lib/rpath/adapters/filesystem.rb
 - lib/rpath/adapters/nokogiri.rb
+- lib/rpath/adapters/oga.rb
 - lib/rpath/adapters/rexml.rb
 - lib/rpath/expressions.rb
 - lib/rpath/registry.rb
@@ -95,12 +111,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
@@ -108,6 +124,6 @@ rubyforge_project:
 rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Graph traversal with just Ruby
+summary: Query XML with just Ruby
 test_files: []
 has_rdoc: