rpath 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDRkNDdiZDc2YTVmOTBlNmY4MzMzN2VmNDU2NThlOTk1OTY4YzBjZQ==
+  data.tar.gz: !binary |-
+    MmE5NzkxYzg2MzdhNjJiYzNjN2U5NDhiMTAwNDBlYjBmYjg1YjZlNw==
+SHA512:
+  metadata.gz: !binary |-
+    ODIxNmI2NWM4MTUyYzc0MDA1ZTlhNjlmNzc5YWY1YjkyNWE1Nzk1OTc0Y2Ex
+    NWY0ZDQ3ODI4ODQ4ODVkZmU4MzFmOTQ2YTNjMzMwNWNiNjMyYjk0OTRmNmE1
+    YTM0ZmQ1NGQ4ODJiZWE4MWI0NjIwNWE0ZGRhNTZiMjFmMmZkNGE=
+  data.tar.gz: !binary |-
+    ZTk2ODMyMTc4NTI1OWU1MWI0NjY5YmZkZDI4NDljNTIxNWJiN2Y4OGY0MTZj
+    MTI1MDA2MzhjNjU4MjdmMjJiYjMzYjc3MWFmMWY5NWUzYTdmZWI2YWIzZTVl
+    MDQ5NmVjZWM4YjI5OTNlYzNiMWI5MmEyZGUzMzRhMGQ3MTA0NWI=

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jonah Burke
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# RPath
+
+"Don't do this." —[flavorjones](https://github.com/flavorjones) [[1]](http://www.nokogiri.org/tutorials/searching_a_xml_html_document.html)
+
+## Overview
+
+RPath lets you traverse 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.
+
+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.
+
+## Documentation
+
+This README provides an overview of RPath. Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/rpath).
+
+## Installation
+
+```bash
+gem install rpath
+```
+
+## Example
+
+Suppose we want the value of the `name` attribute in the following XML document:
+
+```ruby
+xml = Nokogiri::XML <<end
+  <places>
+    <place name="Green-Wood"/>
+  </places>
+end
+```
+
+First we tell RPath we'll be using Nokgiri:
+
+```ruby
+RPath.use :nokogiri
+```
+
+Then we create an RPath expression ...
+
+```ruby
+exp = RPath { places.place[:name] }
+```
+
+... and evaluate it on the document:
+
+```ruby
+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:
+
+```ruby
+RPath(xml) { places.place[:name] } # => "Green-Wood"
+```
+
+For even more succinct syntax, RPath adds to Nokogiri the `#rpath` method:
+
+```ruby
+xml.rpath { places.place[:name] } # => "Green-Wood"
+```
+
+## The Graph Model
+
+In an RPath [graph](http://en.wikipedia.org/wiki/Graph_(mathematics)),
+
+* There is an initial vertex (a "root"),
+* Each vertex has a name,
+* Each vertex has zero or more adjacent vertices,
+* 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.
+
+## 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`.
+
+### Selecting Vertices
+
+All vertices named "foo" adjacent to the root:
+
+```ruby
+RPath { foo }
+```
+
+The first "foo" adjacent to the root:
+
+```ruby
+RPath { foo[0] }
+```
+
+All vertices named "bar" adjacent to the first "foo":
+
+```ruby
+RPath { foo[0].bar }
+```
+
+Or, more succinctly (the first "foo" is assumed if the indexer is omitted):
+
+```ruby
+RPath { foo.bar }
+```
+
+_All_ vertices adjacent to the first "foo":
+
+```ruby
+RPath { foo.adjacent }
+```
+
+All vertices adjacent to the first "foo" named "adjacent" (`#named` lets us avoid collisions with built-in methods):
+
+```ruby
+RPath { foo.adjacent.named("adjacent") }
+```
+
+All "foos" with attribute "baz" equal to "qux":
+
+```ruby
+RPath { foo.where(baz: 'qux') }
+```
+
+Or simply:
+
+```ruby
+RPath { foo[baz: 'qux'] }
+```
+
+And finally, all "foos" meeting arbitrary criteria:
+
+```ruby
+RPath { foo.where { |vertex| some_predicate?(vertex) } } 
+```
+
+### Selecting Attributes
+
+Attribute values are selected by passing a string to `#[]`:
+
+```ruby
+# The "baz" attribute of the first vertex named "foo" adjacent to the root
+RPath { foo['baz'] }
+```
+
+### Selecting Content
+
+A vertex's content is selected with `#content`:
+
+```ruby
+# The content of the first vertex named "foo" adjacent to the root
+RPath { foo.content }
+```
+
+## Adapters
+
+### Nokogiri
+
+The Nokogiri adapter exposes XML elements as vertices and child elements as adjacent vertices:
+
+```ruby
+RPath.use :nokogiri
+
+xml = Nokogiri::XML <<end
+  <foo>
+    <bar baz="qux">Hello, RPath</bar>
+  </foo>
+end
+
+RPath(xml) { foo.bar[0] } # => #<Nokogiri::XML::Element ... >
+```
+
+XML attributes become RPath attributes:
+
+```ruby
+RPath(xml) { foo.bar['baz'] } # => "qux"
+```
+
+And text content is accessible with `#content`:
+
+```ruby
+RPath(xml) { foo.bar.content } # => "Hello, RPath"
+```
+
+An expression may be evaluated not just on an XML document but any `Nokogiri::XML::Node`. Non-element nodes such as processing instructions, alas, are not accessible.
+
+Finally, the convenience method `#rpath`, added to `Nokogiri::XML::Node`, allows for more compact syntax:
+
+```ruby
+xml.rpath { foo.bar.content } # => "Hello, RPath"
+```
+
+### REXML
+
+The REXML adapter is similar to the Nokogiri one. Expressions may be evaluated on any `REXML::Element`.
+
+```ruby
+RPath.use :rexml
+xml = REXML::Document.new('<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:
+
+```ruby
+RPath.use :filesystem
+
+# Note that we must specify the adapter because RPath can't infer it from '~'
+RPath('~', :filesystem) { where { |f| f =~ /bash/ } } # => ["~/.bash_history", "~/.bash_profile"]
+```
+
+Many file properties become RPath attributes:
+
+```ruby
+RPath('/', :filesystem) { etc.hostname[:mtime] } # => 2014-12-17 14:43:24 -0500
+```
+
+And file contents are accessible with `#content`:
+
+```ruby
+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.
+
+Register a custom adapter by passing an instance to `RPath.use`:
+
+```ruby
+RPath.use MapsAdapter.new
+```
+
+To use the adapter, pass the underscored, symbolized class name as the second argument to `RPath` or `RPath::Expression#eval`:
+
+```ruby
+RPath(map, :maps_adapter) { ... }
+```
+
+You can eliminate the need to specify the adapter by implementing `RPath::Adapter#adapts?`:
+
+```ruby
+class MapsAdapter < RPath::Adapter
+  def adapts?(graph)
+    graph.is_a? Map
+  end
+  ...
+end
+```
+
+Now RPath will select `MapsAdapter` when an expression is evaluated on a `Map`:
+
+```ruby
+RPath.use MapsAdapter.new
+RPath(Map.new) { ... }
+```
+
+## Contributing
+
+Please submit issues and pull requests to [jonahb/rpath](http://github.com/jonahb/rpath) on GitHub.
+

data/lib/rpath.rb

@@ -0,0 +1,101 @@
+%w{
+  adapter
+  adapters
+  expressions
+  registry
+  util
+  version
+}.each do |file|
+  require "rpath/#{file}"
+end
+
+module RPath
+  class << self
+    # Registers an adapter. Once an adapter is registered, RPath calls its
+    # {Adapter#adapts?} when trying to infer the adapter for an evaluation,
+    # and its id may be given to {#RPath}.
+    # @example Built-in adapter
+    #   RPath.use :nokogiri
+    # @example Custom adapter
+    #   RPath.use CustomAdapter.new
+    #   RPath(graph, :custom_adapter) { foo.bar }
+    # @example Custom adapter with custom ID
+    #   RPath.use CustomAdapter.new, :custom
+    #   RPath(graph, :custom) { foo.bar }
+    # @param [Symbol, Adapter] adapter
+    #   For built-in adapters, the underscored, symbolized class name (e.g.
+    #   +:nokogiri+). For custom adapters, an instance of the adapter class.
+    # @param [Symbol, nil] id
+    #   The identifier to be used in calls to {#RPath}. If +nil+, the
+    #   underscored, symbolized name of the adapter class is assumed.
+    # @return [void]
+    #
+    def use(adapter, id = nil)
+      if adapter.is_a?(Symbol)
+        class_names = [Util.camelcase(adapter.to_s), adapter.to_s.upcase]
+        class_ = Util.first_defined_const(RPath::Adapters, *class_names)
+
+        unless class_
+          raise "No adapter in RPath::Adapters with class name in #{class_names}"
+        end
+
+        adapter = class_.new
+      end
+
+      Registry.register adapter, id
+    end
+    alias_method :register, :use
+  end
+end
+
+# Constructs an RPath expression and optionally evaluates it on a graph.
+#
+# @overload RPath
+#   Constructs an RPath expression
+#   @example Construct an expression
+#     exp = RPath { foo.bar }
+#   @example Construct an expression beginning with an uppercase letter
+#     exp = RPath { |root| root.Users.alice }
+#   @yieldparam [RPath::Root] root
+#     The {RPath::Root} of the RPath expression. You should almost
+#     always omit this yield paramter. Use it only to avoid an exception if the
+#     first letter of your expression is uppercase. See the example above.
+#   @return [RPath::Expression]
+#   @see file:README.md
+#
+# @overload RPath(graph, adapter = nil)
+#   Constructs an RPath expression, evaluates it, and returns the result
+#   @example Construct and expression and evaluate it on an XML document
+#     RPath.use :nokogiri
+#     xml = Nokogiri::XML('<foo bar="baz"/>')
+#     RPath(xml) { foo['bar'] } # => "baz"
+#   @example Construct an expression and evaluate it with a custom adapter
+#     RPath(graph, CustomAdapter.new) { foo.bar }
+#   @example Construct an expression and evaluate it with a custom adapter that has been registered
+#     RPath(graph, :custom) { foo.bar }
+#   @example Construct an expression and evaluate it, letting RPath infer the adapter
+#     RPath(graph) { foo.bar }
+#   @param [Object] graph
+#     The graph on which to evaluate the expression.
+#   @param [RPath::Adapter, Symbol, nil] adapter
+#     The adapter with which to evaluate the expression. If the adapter has been
+#     registered with {RPath.use}, its id (a symbol) may be given as a 
+#     shortcut. If +nil+, RPath attempts to infer the adapter by calling
+#     {RPath::Adapter#adapts?} on registered adapters.
+#   @yieldparam [RPath::Root] root
+#     The {RPath::Root} of the RPath expression. You should almost
+#     always omit this yield parameter. Use it only to avoid an exception if the
+#     first letter of your expression is uppercase. See the example above.
+#   @return [Object]
+#   @see file:README.md
+#   @see RPath.use
+#
+def RPath(graph = nil, adapter = nil, &block)
+  exp = RPath::Root.new
+
+  if block_given?
+    exp = block.arity > 0 ? block.call(exp) : exp.instance_eval(&block)
+  end
+
+  graph ? exp.eval(graph, adapter) : exp
+end

data/lib/rpath/adapter.rb

@@ -0,0 +1,64 @@
+module RPath
+
+  # An RPath adapter makes it possible to evaluate RPath expressions on some
+  # type of graph. There are built-in adapters for Nokogiri, REXML, and the
+  # filesystem. To build an adapter for another graph type, inherit from
+  # {Adapter} and implement the abstract methods.
+  # @abstract
+  #
+  class Adapter
+    # Used to infer the adapter when {#RPath} is called without an explicit
+    # adapter. The first registered adapter whose {#adapts?} returns +true+
+    # is chosen. The default implementation returns +false+.
+    # @param [Object] graph
+    # @return [Boolean]
+    # @see #RPath
+    # @see RPath.use
+    def adapts?(graph)
+      false
+    end
+
+    # Returns the root of the given graph, the vertex where evaluation
+    # begins. The default implementation returns the given graph.
+    # the given graph.
+    # @param [Object] graph
+    # @return [Object]
+    def root(graph)
+      graph
+    end
+
+    # Returns the name of the given vertex
+    # @abstract
+    # @param [Object] vertex
+    # @return [String]
+    def name(vertex)
+      raise NotImplementedError
+    end
+
+    # Returns the vertices adjacent to the given vertex.
+    # @abstract
+    # @param [Object] vertex
+    # @return [Array]
+    def adjacent(vertex)
+      raise NotImplementedError
+    end
+
+    # Returns the value of attribute +name+ of +vertex+ or +nil+ if no such
+    # attribute exists.
+    # @abstract
+    # @param [Object] vertex
+    # @param [String, Symbol] name
+    # @return [Object, nil]
+    def attribute(vertex, name)
+      raise NotImplementedError
+    end
+
+    # Returns the content of +vertex+ or nil if no content exists.
+    # @abstract
+    # @param [Object] vertex
+    # @return [Object, nil]
+    def content(vertex)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/rpath/adapters.rb

@@ -0,0 +1,7 @@
+module RPath
+  module Adapters
+    autoload :Filesystem, 'rpath/adapters/filesystem'
+    autoload :Nokogiri, 'rpath/adapters/nokogiri'
+    autoload :REXML, 'rpath/adapters/rexml'
+  end
+end

data/lib/rpath/adapters/filesystem.rb

@@ -0,0 +1,108 @@
+require 'pathname'
+
+module RPath
+  module Adapters
+
+    class Filesystem < RPath::Adapter
+
+      # Always false. The filesystem adapter must be specified in calls to
+      # {#RPath}.
+      # @param [Object] graph
+      # @return [Boolean]
+      def adapts?(graph)
+        false
+      end
+
+      # @param [String] vertex
+      #   A filesystem path
+      # @return [String]
+      #   Returns the basename
+      def name(vertex)
+        File.basename vertex
+      end
+
+      # @param [String] vertex
+      #   A filesystem path
+      # @return [Array<String>]
+      #   Returns the expanded paths of the directory entries. An empty array
+      #   if +vertex+ is a file.
+      def adjacent(vertex)
+        begin
+          entries = Dir.entries(File.expand_path(vertex))
+        rescue SystemCallError
+          return []
+        end
+
+        entries.collect { |entry| File.join(vertex, entry) }
+      end
+
+      # @param [String] vertex
+      #   A filesystem path
+      # @param [String, Symbol] name
+      #   An attribute in {ATTRIBUTES}
+      # @return [Object, nil]
+      #   Returns the value of the attribute; +nil+ if the attribute is
+      #   invalid.
+      def attribute(vertex, name)
+        if ATTRIBUTES.include?(name.to_s)
+          begin
+            Pathname(File.expand_path(vertex)).send(name)
+          rescue SystemCallError
+            nil
+          end
+        else
+          nil
+        end
+      end
+
+      # @param [String] vertex
+      #   A filesystem path
+      # @return [String, nil]
+      #   Returns the contents if +vertex+ is a file; otherwise +nil+.
+      def content(vertex)
+        begin
+          File.read File.expand_path(vertex)
+        rescue SystemCallError
+          nil
+        end
+      end
+
+      # Attributes that may be passed as names to {#attribute}
+      ATTRIBUTES = %w{
+        blockdev?
+        chardev?
+        directory?
+        executable?
+        executable_real?
+        file?
+        grpowned?
+        owned?
+        pipe?
+        readable?
+        world_readable?
+        readable_real?
+        setgid?
+        setuid?
+        size
+        socket?
+        sticky?
+        symlink?
+        writable?
+        world_writable?
+        writable_real?
+        zero?
+        atime
+        birthtime
+        ctime
+        mtime
+        ftype
+        readlink
+        stat
+        lstat
+        dirname
+        extname
+        split }
+    end
+
+  end
+end

data/lib/rpath/adapters/nokogiri.rb

@@ -0,0 +1,60 @@
+require 'nokogiri'
+
+module RPath
+  module Adapters
+
+    class Nokogiri < RPath::Adapter
+
+      # Returns +true+ iff +graph+ is a +Nokogiri::XML::Node+.
+      # @param [Object] graph
+      # @return [Boolean]
+      def adapts?(graph)
+        graph.is_a? ::Nokogiri::XML::Node
+      end
+
+      # Returns the name of the given node
+      # @param [Nokogiri::XML::Node] vertex
+      # @return [String]
+      def name(vertex)
+        vertex.name
+      end
+
+      # Returns the child elements of the given node
+      # @param [Nokogiri::XML::Node] vertex
+      # @return [Array<Nokogiri::XML::Node>]
+      def adjacent(vertex)
+        vertex.children.to_a
+      end
+
+      # Returns the value of the named attribute on the given node.
+      # @param [Nokogiri::XML::Node] vertex
+      # @param [String, Symbol] name
+      # @return [String, nil]
+      def attribute(vertex, name)
+        vertex[name.to_s]
+      end
+
+      # Returns the text content of the given node.
+      # @param [Nokogiri::XML::Node] vertex
+      # @return [String, nil]
+      def content(vertex)
+        vertex.text
+      end
+    end
+
+  end
+end
+
+class Nokogiri::XML::Node
+  # Evaluates an expression on the element
+  # @example
+  #   RPath.use :nokogiri
+  #   xml = Nokogiri::XML('<foo bar="baz"/>')
+  #   xml.rpath { foo['bar'] } # => "baz"
+  # @see #RPath
+  # @return [Object]
+  #
+  def rpath(&block)
+    RPath self, :nokogiri, &block
+  end
+end

data/lib/rpath/adapters/rexml.rb

@@ -0,0 +1,60 @@
+require 'rexml/document'
+
+module RPath
+  module Adapters
+
+    class REXML < RPath::Adapter
+
+      # Returns +true+ iff +graph+ is an +REXML::Element+.
+      # @param [Object] graph
+      # @return [Boolean]
+      def adapts?(graph)
+        graph.is_a? ::REXML::Element
+      end
+
+      # Returns the name of the given element
+      # @param [REXML::Element] vertex
+      # @return [String]
+      def name(vertex)
+        vertex.name
+      end
+
+      # Returns the child elements of the given element
+      # @param [REXML::Element] vertex
+      # @return [Array<REXML::Element>]
+      def adjacent(vertex)
+        vertex.elements.to_a
+      end
+
+      # Returns the value of the named attribute on the given element.
+      # @param [REXML::Element] vertex
+      # @param [String, Symbol] name
+      # @return [String, nil]
+      def attribute(vertex, name)
+        vertex.attributes[name.to_s]
+      end
+
+      # Returns the text content of the given element.
+      # @param [REXML::Element] vertex
+      # @return [String, nil]
+      def content(vertex)
+        vertex.text
+      end
+    end
+
+  end
+end
+
+class REXML::Element
+  # Evaluates an expression on the element
+  # @example
+  #   RPath.use :rexml
+  #   xml = REXML::Document.new('<foo bar="baz"/>')
+  #   xml.rpath { foo['bar'] } # => "baz"
+  # @see #RPath
+  # @return [Object]
+  #
+  def rpath(&block)
+    RPath self, :rexml, &block
+  end
+end

data/lib/rpath/expressions.rb

@@ -0,0 +1,332 @@
+module RPath
+
+  # An RPath expression, given a graph, produces a value: a vertex, a vertex
+  # array, an attribute value, or a vertex's content.
+  # @abstract
+  class Expression
+
+    # Evaluates the expression on a graph
+    # @param [Object] graph
+    # @param [RPath::Adapter, Symbol, nil] adapter
+    #   An {Adapter} instance, the id symbol given when the adapter was
+    #   registered with {RPath.use}, or +nil+ if the adapter should be
+    #   inferred.
+    # @return [Object]
+    # @raise [RuntimeError]
+    #   The adapter can't be determined
+    # @ raise [ArgumentError]
+    #   +adapter+ is not an {Adapter}, Symbol, or nil
+    # @see #RPath
+    # @see RPath.use
+    #
+    def eval(graph, adapter = nil)
+      adapter = case adapter
+      when RPath::Adapter
+        adapter
+      when Symbol
+        Registry.find adapter.to_sym
+      when nil
+        Registry.infer graph
+      else
+        raise ArgumentError, "Adapter must be an RPath::Adapter, Symbol, or nil"
+      end
+
+      unless adapter
+        raise "Can't determine adapter"
+      end
+
+      do_eval graph, adapter
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      raise NotImplementedError
+    end
+  end
+
+
+  # An expression that evaluates to a vertex V
+  # @abstract
+  class VertexExpression < Expression
+    # Returns an expression that evaluates to V's adjacent vertices.
+    # @return [Adjacent]
+    def adjacent
+      Adjacent.new self
+    end
+
+    # Returns an expression that evaluates to V's content.
+    # @return [Content]
+    def content
+      Content.new self
+    end
+
+    # Returns an expression that evaluates to the value of an attribute of V
+    # @return [Attribute]
+    # @raise [ArgumentError]
+    #   +subscript+ is not a String or Symbol
+    def [](subscript)
+      unless subscript.is_a?(String) || subscript.is_a?(Symbol)
+        raise ArgumentError, "Subscript for expression producing a vertex must by a String or Symbol"
+      end
+      Attribute.new self, subscript
+    end
+
+    # Returns an expression that evaluates to V's adjacent vertices named
+    # +name+. Enables the basic RPath expression +RPath { foo }+.
+    # @return [Named]
+    def method_missing(name, *args, &block)
+      Named.new adjacent, name.to_s
+    end
+  end
+
+
+  # An expression that evaluates to a vertex array A
+  # @abstract
+  class VertexArrayExpression < Expression
+    # Returns an expression that evaluates to the vertices in A meeting certain
+    # conditions.
+    # @return [Where]
+    # @see Where#initialize
+    def where(*args, &block)
+      Where.new self, *args, &block
+    end
+
+    # Returns an expression that evaluates to the vertices in A named +name+.
+    # @param [String] name
+    # @return [Named]
+    def named(name)
+      Named.new self, name
+    end
+
+    # @overload [](index)
+    #   Returns an expression that evaluates to the vertex at index +index+ in
+    #   A.
+    #   @param [Integer] index
+    #   @return [At]
+    # @overload [](conditions)
+    #   Returns an expression that evaluates to the vertices in A meeting
+    #   certain conditions.
+    #   @param [Hash] conditions
+    #   @return [Where]
+    #   @see Where#initialize
+    # @overload [](attribute)
+    #   Returns an expression that evaluates to the value of an attribute of
+    #   the first vertex in A. Enables omitting the indexer in
+    #   +RPath { foo['bar'] }+
+    #   @param [String, Symbol] attribute
+    #   @return [Attribute]
+    # @raise [ArgumentError]
+    #   +subscript+ is not an Integer, Hash, String, or Symbol
+    def [](subscript)
+      case subscript
+      when Integer
+        At.new self, subscript
+      when Hash
+        Where.new self, subscript
+      when String, Symbol
+        self[0][subscript]
+      else
+        raise ArgumentError, "Subscript for expression producing a vertex must be an Integer, Hash, String, or Symbol"
+      end
+    end
+
+    # Constructs an {At} that evaluates to the first vertex in A;
+    # forwards the method invocation to this {At}. Enables omitting
+    # the indexer in expressions like +RPath { foo.bar }+.
+    def method_missing(name, *args, &block)
+      self[0].send name, *args, &block
+    end
+  end    
+
+
+  # Evaluates to the root of the graph.
+  class Root < VertexExpression
+    # @return [String]
+    def to_s
+      'root'
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      adapter.root graph
+    end
+  end
+
+
+  # Given a prior expression producing vertex V, evaluates to an array
+  # containing V's adjacent vertices.
+  class Adjacent < VertexArrayExpression
+    # @param [Expression] prior
+    #   An expression that evaluates to a vertex 
+    def initialize(prior)
+      super()
+      @prior = prior
+    end
+
+    # @return [String]
+    def to_s
+      "#{@prior}."
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertex = @prior.eval(graph, adapter)
+      vertex && adapter.adjacent(vertex)
+    end
+  end
+
+
+  # Given a prior expression producing vertex array A, evaluates to an array
+  # containing the vertices in A with a certain name.
+  class Named < VertexArrayExpression
+    # @param [Expression] prior
+    #   An expression that evaluates to a vertex array
+    # @param [String] name
+    def initialize(prior, name)
+      super()
+      @prior = prior
+      @name = name
+    end
+
+    # @return [String]
+    def to_s
+      "#{@prior}#{@name}"
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertices = @prior.eval(graph, adapter)
+      vertices && vertices.select { |vertex| @name == adapter.name(vertex) }
+    end
+  end
+
+
+  # Given a prior expression producing vertex array A, evaluates to an array
+  # containing the vertices in A that match certain conditions.
+  class Where < VertexArrayExpression
+    # @overload initialize(prior, conditions)
+    #   @param [Expression] prior
+    #     An expression that evaluates to a vertex array
+    #   @param [Hash{Symbol => Object}] conditions
+    #     A map of attribute keys to values.
+    # @overload initialize(prior)
+    #   @param [Expression] prior
+    #     An expression that evaluates to a vertex array
+    #   @yieldparam vertex [Object]
+    #   @yieldreturn [Boolean]
+    #     Whether the vertex should be selected
+    def initialize(prior, conditions = {}, &selector)
+      super()
+      @prior = prior
+      @selector = block_given? ? selector : nil
+      @conditions = block_given? ? nil : conditions
+    end
+
+    # @return [String]
+    def to_s
+      conditions = @selector ?
+        'selector' :
+        @conditions.map { |k, v| "#{k}: #{v}" }.join(', ')
+
+      "#{@prior}[#{conditions}]"
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertices = @prior.eval(graph, adapter)
+      return nil unless vertices
+
+      if @selector
+        vertices.select(&@selector)
+      else
+        vertices.select do |vertex|
+          @conditions.all? do |name, value|
+            adapter.attribute(vertex, name) == value
+          end
+        end
+      end
+    end
+  end
+
+
+  # Given a prior expression producing vertex array A, evaluates to the vertex
+  # in A at a given index.
+  class At < VertexExpression
+    # @param [Expression] prior
+    #   An expression that evaluates to a vertex array
+    # @param [Integer] index
+    #   The index of the vertex to produce
+    def initialize(prior, index)
+      super()
+      @prior = prior
+      @index = index
+    end
+
+    # @return [String]
+    def to_s
+      "#{@prior}[#{@index}]"
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertices = @prior.eval(graph, adapter)
+      vertices && vertices[@index]
+    end
+  end
+
+
+  # Given a prior expression producing a vertex V, evaluates to the value of
+  # the attribute of V with the given name.
+  class Attribute < Expression
+    # @param [Expression] prior
+    #   An expression that evaluates to a vertex
+    # @param [String] name
+    #   The name of the attribute
+    def initialize(prior, name)
+      super()
+      @prior = prior
+      @name = name
+    end
+
+    # @return [String]
+    def to_s
+      "#{@prior}[#{@name}]"
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertex = @prior.eval(graph, adapter)
+      vertex && adapter.attribute(vertex, @name)
+    end
+  end
+
+
+  # Given a prior expression producing vertex V, evaluates to V's content.
+  class Content < Expression
+    # @param [Expression] prior
+    #   An expression producing a vertex
+    def initialize(prior)
+      @prior = prior
+    end
+
+    # @return [String]
+    def to_s
+      "#{@prior}:content"
+    end
+
+    private
+
+    def do_eval(graph, adapter)
+      vertex = @prior.eval(graph, adapter)
+      vertex && adapter.content(vertex)
+    end
+  end
+
+end

data/lib/rpath/registry.rb

@@ -0,0 +1,52 @@
+module RPath
+
+  # @private
+  class Registry
+    class << self
+      # Registers an adapter. Once an adapter is registered, RPath calls its
+      # {#adapts?} when trying to infer the adapter for an evaluation, and its
+      # id, as opposed to an instance, may be given to {#RPath}.
+      # @param [Adapter] adapter
+      # @param [Symbol, nil] id
+      #   An id that can later be passed to {#RPath}. If omitted, the
+      #   symbolized, underscored name of the adapter class is assumed.
+      # @return [void]
+      def register(adapter, id = nil)
+        id ||= default_id(adapter)
+        id_to_adapter[id] = adapter
+      end
+      alias_method :use, :register
+
+      # Infers the adapter for a given graph. The first adapter whose
+      # {#adapts?} returns +true+ is chosen.
+      # @param [Object] graph
+      # @return [Adapter, nil]
+      def infer(graph)
+        id_to_adapter.each_value.find { |adapter| adapter.adapts?(graph) }
+      end
+
+      # Finds a registered adapter by id.
+      # @param [Symbol] id
+      # @return [Adapter, nil]
+      def find(id)
+        id_to_adapter[id]
+      end
+
+      # Unregisters all adapters
+      def clear
+        id_to_adapter.clear
+      end
+
+      private
+
+      def id_to_adapter
+        @id_to_adapter ||= {}
+      end
+
+      def default_id(adapter)
+        Util.underscore(adapter.class.name.split('::').last).to_sym
+      end
+    end
+  end
+
+end

data/lib/rpath/util.rb

@@ -0,0 +1,21 @@
+module RPath
+
+  # @private
+  module Util
+    class << self
+      def underscore(string)
+        string.gsub(/([^A-Z])([A-Z])/, '\1_\2').downcase
+      end
+
+      def camelcase(string)
+        string.gsub(/(?:^|_)([a-z])/) { $1.upcase }
+      end
+
+      def first_defined_const(module_, *consts)
+        const = consts.find { |c| module_.const_defined?(c) }
+        const && module_.const_get(const)
+      end
+    end
+  end
+
+end

data/lib/rpath/version.rb

@@ -0,0 +1,3 @@
+module RPath
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: rpath
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonah Burke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-03 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: 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: 
+email:
+- jonah@jonahb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rpath.rb
+- lib/rpath/adapter.rb
+- lib/rpath/adapters.rb
+- lib/rpath/adapters/filesystem.rb
+- lib/rpath/adapters/nokogiri.rb
+- lib/rpath/adapters/rexml.rb
+- lib/rpath/expressions.rb
+- lib/rpath/registry.rb
+- lib/rpath/util.rb
+- lib/rpath/version.rb
+homepage: http://github.com/jonahb/rpath
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: TBD
+test_files: []
+has_rdoc: