tiny_xpath_helper 0.1.8

data/README.rdoc

@@ -0,0 +1,116 @@
+= TinyXPathHelper
+
+== Description
+
+Very light syntax for using XPaths on XML documents or REXML nodes
+
+== Examples
+
+TinyXPathHelper.new takes one parameter: an XML document (as a string or IO) or a REXML element
+  >> xpath = TinyXPathHelper.new( File.open( 'test/xml/sample.xml' ) )
+
+Then, to find the string values of matching nodes, there's a super-light syntax:
+  >> xpath[ 'node/' ]
+  => ["one", "two", "three\n    "]
+
+It works on attributes, too
+  >> xpath[ 'node/@style' ]
+  => ["first"]
+
+If you prefer, you can use #all instead of square brackets
+  >> xpath.all( 'node/@style' )
+  => ["first"]
+
+If you just want the first match, use #first
+  >> xpath.first( 'node/' )
+  => "one"
+
+A slightly more elaborate API is available as #find_xpath
+  >> xpath.find_xpath( 'node/@style', :format => :rexml, :find => :first )
+  => style='first'
+
+Where :format can be :text (returns a string), or :rexml (returns a REXML element),
+and :find can be :first or :all
+  >> xpath.find_xpath( 'node/@style', :format => :rexml, :find => :all )
+  => [style='first']
+
+If you want to filter the output, you can pass something that can be to_proc'd as :format
+(Note that this acts on the string value of the element, not the REXML node)
+  >> xpath[ 'node/@style', :to_i ]
+  => [0]
+
+  >> xpath[ 'node/@style', :length ]
+  => [5]
+
+  >> xpath[ 'node', lambda{|x| x.strip.split(//) } ]
+  => [["o", "n", "e"], ["t", "w", "o"], ["t", "h", "r", "e", "e"]]
+
+If you only need to set :format, you may pass just the symbol instead of an options hash
+This is especially convenient using the [] syntax since a bug in ruby1.8
+prevents using => inside of []
+  >> xpath[ 'node/@style', :rexml ]
+  => [style='first']
+
+Actually, formats :rexml and :text are aliases for the :auto_text parameter, which takes a bool,
+and defaults to true.
+  >> xpath.all( 'node/@style', :auto_text => false )
+  => [style='first']
+
+If you find yourself writing iterative xpaths, you may want to use :format => :tiny_xpath_helper
+  >> node_xpath = xpath.first( 'node', :format => :tiny_xpath_helper)
+  >> node_xpath.first('@style')
+  => style='first'
+
+Option defaults can be passed to TinyXPathHelper#new
+  >> xpath_with_options = TinyXPathHelper.new( File.open( 'test/xml/sample.xml' ), :format => :to_i, :find => :all )
+  >> xpath_with_options.find_xpath( 'node' )
+  => [0,0,0]
+
+You can access the default options for the TinyXMLHelper Class or any instance with #default_options
+  >> TinyXPathHelper.default_options
+  => {:format => nil,   :auto_text => true, :find => :first}
+  >> xpath_with_options.default_options
+  => {:format => :to_i, :auto_text => true, :find => :all}
+
+You can also pass a block, which will get called on the entire return value, but
+only if at least one element is found
+  >> xpath.all( 'node' ){ |nodes| nodes.count } # nodes is an array of strings
+  => 3
+
+  >> xpath.first( 'node' ){ |node| node.reverse } # node is a string
+  => "eno"
+
+  >> xpath.all( 'node', &:count )
+  => 3
+
+  >> xpath.all( 'nothing' ){ |nodes| raise "this will not run" }
+  => []
+  
+If you really want shortcut for the case where you want to run something
+over the array of matching REXML nodes, set :auto_text to false when calling TinyXpathHelper#new
+  >> rexml_xpath = TinyXPathHelper.new( File.open( 'test/xml/sample.xml' ), :auto_text => false )
+  >> rexml_xpath[ 'node', :name ]
+  => ['node', 'node', 'node']
+
+The output from :format => :rexml is suitable for passing to another TinyXPathHelper
+  >> node_tree = xpath.find_xpath( 'node/three', :format => :rexml )
+  >> deeper_xpath = TinyXPathHelper.new( node_tree )
+  >> deeper_xpath[ 'b/@beta' ]
+  => ["true"]
+
+If you want empty documents to not raise an error
+  >> empty_xpath = TinyXPathHelper.new( String.new, :allow_empty_document => true )
+  >> empty_xpath[ 'b/@beta' ]
+  => []
+
+If you want to call to_s on the xpath argument
+  >> xpath_with_indifferent_access = TinyXPathHelper.new( File.open( 'test/xml/sample.xml' ), :with_indifferent_access => true )
+  >> xpath_with_indifferent_access[ :node ]
+  => ["one", "two", "three\n    "]
+  
+  
+--
+doctest_require: 'lib/tiny_xpath_helper.rb'
+++
+
+Copyright (c) 2009 raSANTIAGO + Associates LLC

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :rubydoctest
+
+desc 'Test the tiny_xpath_helper plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'ruby rubydoctest'
+task :rubydoctest do
+  results = `rubydoctest README.rdoc`
+  raise results if results =~ /FAIL/
+  puts results
+end
+
+desc 'Generate documentation for the tiny_xpath_helper plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TinyXPathHelper'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), "lib", "tiny_xpath_helper")

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/tiny_xpath_helper.rb

@@ -0,0 +1,139 @@
+require 'rexml/document'
+
+class TinyXPathHelper
+  attr :node
+
+  def initialize(xml, options = {})
+    @xml  = xml
+    @node = self.class.xml_node_for_xmlish(xml, options)
+    @options = options.freeze
+  end
+
+  def default_options
+    self.class.default_options.dup.update(@options)
+  end
+
+  def with_options(*options)
+    r = default_options.dup
+
+    options.reverse.each do |option|
+      if not option.is_a?( Hash )
+        option = {:format => option}
+      end
+      r.update(option)
+    end
+
+    return r
+  end
+
+  def find_xpath(xpath_expr, options = {}, &blk)
+    self.class.find_xpath_from( node, xpath_expr, with_options(options), &blk)
+  end
+
+  def first(xpath_expr, options = {}, &blk)
+    self.find_xpath( xpath_expr, with_options(options, :find => :first), &blk)
+  end
+  alias at first
+
+  def all(xpath_expr, options = {}, &blk)
+    self.find_xpath( xpath_expr, with_options(options, :find => :all), &blk)
+  end
+  alias [] all
+
+  def self.io_stream_classes
+    [ IOStream ] rescue [ IO, StringIO ] # thoughtbot-paperclip fixes the ducktype mess in StringIO
+  end
+
+  def self.classes_that_are_xmlish
+    io_stream_classes + [ String, REXML::Document ]
+  end
+
+  def self.xml_node_for_xmlish( xml, options = {} )
+    if io_stream_classes.any?{|k| xml.is_a?(k) }
+      xml = xml.read
+    end
+    if xml.is_a?(String)
+      xml = REXML::Document.new(xml)
+    end
+    if xml.is_a?(REXML::Document)
+      if options[:allow_empty_document] and ! xml.root
+        xml = xml
+      else
+        xml = xml.root
+      end
+    end
+    if not xml.is_a?(REXML::Element)
+      raise TypeError.new("Expected REXML::Element, got #{xml.class}")
+    end
+    return xml
+  end
+
+  def self.xml_node_to_text(node)
+    if(node.respond_to? :text)
+      # XML::Elements don't to_s in the way we want
+      val = node.text
+    else
+      val = node.to_s
+    end
+  end
+
+  def self.default_options
+    {:format => nil, :auto_text => true, :find => :first}.freeze
+  end
+
+  def self.find_xpath_from(element, path, options = {}, &blk)
+    if options[:with_indifferent_access]
+      path = path.to_s
+    end
+
+    options = self.default_options.dup.update(options)
+    format    = options[:format]
+    auto_text = options[:auto_text]
+    count     = options[:find]
+
+    if format == :array
+      count     = :all
+      format    = nil
+    elsif format == :text
+      auto_text = true
+      format    = nil
+    elsif format == :xml or format == :rexml
+      auto_text = false
+      format    = nil
+    elsif format == :xpath_helper or format == :tiny_xpath_helper
+      auto_text = false
+      format    = self.method(:new)
+    end
+
+    filter1 = auto_text ? self.method(:xml_node_to_text) : nil
+    filter2 = format
+
+    if count   == :all
+      elements = REXML::XPath.match(element, path)
+
+    elsif count == :first
+      elements  = [ REXML::XPath.first(element, path) ].compact # Haskell hacker wishing for the Maybe monad
+
+    else 
+      raise "I don't know how to find #{count.inspect}"
+    end
+
+    elements = elements.map(&filter1).map(&filter2)
+
+    if count == :all
+      r = elements
+    elsif count == :first
+      r = elements.first
+    end
+
+    if(blk and elements.length > 0)
+      return blk.call( r )
+    end
+
+    return r
+
+  end
+
+end
+
+TinyXpathHelper = TinyXPathHelper

data/tasks/tiny_xpath_helper_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :tiny_xpath_helper do
+#   # Task goes here
+# end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'
+require 'test/unit'
+require 'tiny_xpath_helper.rb'

data/test/tiny_xpath_helper_test.rb

@@ -0,0 +1,13 @@
+require 'test_helper'
+
+class TinyXPathHelperTest < ActiveSupport::TestCase
+  test "find first returns nil if there is no match" do
+    xpath = TinyXPathHelper.new("<xml/>")
+    assert xpath.first('*').nil?
+  end
+
+  test "find_xpath with :format => :array doesn't crash" do
+    xpath = TinyXPathHelper.new("<xml><a/></xml>")
+    assert xpath.find_xpath('*', :format => :array)
+  end
+end

data/test/xml/sample.xml

@@ -0,0 +1,9 @@
+<xml>
+  <node style="first">one</node>
+  <node>two</node>
+  <node>three
+    <three>
+      <a/><b beta="true"/><c/>
+    </three>
+  </node>
+</xml>

data/tiny_xpath_helper.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{tiny_xpath_helper}
+  s.version = "0.1.8"
+
+  s.authors = ["Jesse Wolfe"]
+  s.date = %q{2009-06-01}
+  s.description = %q{Very light syntax for using XPaths on XML documents or REXML nodes}
+  s.email = %q{jesse@rasantiago.com}
+  s.files = %w[ uninstall.rb init.rb Rakefile lib/tiny_xpath_helper.rb tiny_xpath_helper.gemspec README.rdoc tasks/tiny_xpath_helper_tasks.rake install.rb test/tiny_xpath_helper_test.rb test/xml test/xml/sample.xml test/test_helper.rb ]
+  s.has_rdoc = false
+  s.homepage = %q{http://github.com/rasantiago/tiny_xpath_helper}
+  s.rdoc_options = ["--inline-source", "--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Very light syntax for using XPaths on XML documents or REXML nodes}
+end
+

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+name: tiny_xpath_helper
+version: !ruby/object:Gem::Version 
+  version: 0.1.8
+platform: ruby
+authors: 
+- Jesse Wolfe
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-01 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Very light syntax for using XPaths on XML documents or REXML nodes
+email: jesse@rasantiago.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- uninstall.rb
+- init.rb
+- Rakefile
+- lib/tiny_xpath_helper.rb
+- tiny_xpath_helper.gemspec
+- README.rdoc
+- tasks/tiny_xpath_helper_tasks.rake
+- install.rb
+- test/tiny_xpath_helper_test.rb
+- test/xml/sample.xml
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/rasantiago/tiny_xpath_helper
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Very light syntax for using XPaths on XML documents or REXML nodes
+test_files: []
+