peachy 0.1.2

data/README.rdoc

@@ -0,0 +1,54 @@
+= Peachy
+
+Peachy dynamically slurps XML from an underlying XML DOM, creating ruby methods 
+on the fly to match the elements and attributes of the XML.
+
+Source available at http://github.com/njpearman/Peachy
+
+== Install
+There is no gem available for Peachy yet.  This is the next bit of work to
+complete. In the meantime, if you wish to mess around with Peachy, download and
+include the source files in /lib within your project.
+
+== Usage
+The Peachy::Proxy is the key class in Peachy.  Create a new instance of a
+Peachy::Proxy passing in either a raw XML string, or a Nokogiri::XML instance
+
+    proxy = Peachy::Proxy.new :xml => '<xml><node>Peachy</node></xml>'
+
+or
+
+    proxy = Peachy::Proxy.new :nokogiri => Nokogiri::XML('<xml><node>Peachy</node></xml>')
+
+Once you have a Proxy, it's straightforward to drill down through the XML by
+node name:
+
+    puts 'Contents: ' + proxy.xml.node
+    -> Contents: Peachy
+
+Peachy expects method names to be called in the Ruby convention of lowercase with
+underscores.  It will do it's best to match method names to elements and attributes
+following different conventions (currently, this is camelCaseNames, PascalCaseNames
+or hyphen-separated-names)
+
+More detailed usage examples can be found in the .rb files in the /test directory.
+
+=== XML parsing
+
+Currently, Peachy is hard wired to use Nokogiri for XML parsing, but this will
+be abstracted out at some point.
+
+=== Elements and Attributes
+
+Currently, elements and attributes are accessed in exactly the same way; that is,
+call a method on your current node matching the attribute or element name that
+is required next.
+As Peachy is just for slurping XML, it makes it easy to know how to access
+the property that you're after if the conventions are the same for noth elements
+and attributes.
+
+=== No method name match
+
+Peachy is currently short-tempered, in that if no element or attribute match is
+found when drilling down through proxies, a NoMatchingXmlPart error will be
+raised.

data/lib/invalid_proxy_parameters.rb

@@ -0,0 +1,10 @@
+class InvalidProxyParameters < Exception
+  def initialize parameters_hash={}
+    parameters_string = []
+    parameters_hash.each {|pair| parameters_string << ":#{pair.first} = #{pair.last.nil?? 'nil' : pair.last}" }
+    super <<MESSAGE
+The parameters that you passed to the Proxy were invalid.
+#{parameters_string.sort * "\n"}
+MESSAGE
+  end
+end

data/lib/method_not_in_ruby_convention.rb

@@ -0,0 +1,12 @@
+class MethodNotInRubyConvention < Exception
+  def initialize method_name
+    super(MessageTemplate.gsub /method_name/, method_name.to_s)
+  end
+
+  private
+  
+  MessageTemplate = <<EOF
+You've tried to infer method_name using Peachy, but Peachy doesn't currently like defining methods that break Ruby convention.
+Please use methods matching ^[a-z]+(?:_[a-z]+)?{0,}$ and Peachy will try to do the rest with your XML.*/
+EOF
+end

data/lib/no_matching_xml_part.rb

@@ -0,0 +1,5 @@
+class NoMatchingXmlPart < Exception
+  def initialize method_name
+    super "#{method_name} is not contained as a child of this node."
+  end
+end

data/lib/peachy/childless_proxy_with_attributes.rb

@@ -0,0 +1,20 @@
+module Peachy
+  class ChildlessProxyWithAttributes < Proxy
+    def value
+      @nokogiri_node.content
+    end
+
+    private
+    def generate_method_for_xml method_name
+      check_for_convention(method_name)
+      match = find_match_by_attributes method_name, nokogiri_node
+      raise NoMatchingXmlPart.new method_name if match.nil?
+      return create_content_child(match) {|child| define_child method_name, child }
+    end
+
+    def find_match_by_attributes method_name, node
+      mapped = method_name.variations.map {|variation| node.attribute variation }
+      mapped.find {|match| match != nil }
+    end
+  end
+end

data/lib/peachy/convention_checks.rb

@@ -0,0 +1,11 @@
+module Peachy
+  module ConventionChecks
+    def check_for_convention method_name
+      raise MethodNotInRubyConvention.new(method_name) unless matches_convention(method_name)
+    end
+
+    def matches_convention method_name
+      method_name.to_s =~ /^[a-z]+(?:_[a-z]+){0,}$/
+    end
+  end
+end

data/lib/peachy/method_mask.rb

@@ -0,0 +1,11 @@
+module Peachy
+  module MethodMask
+    def hide_public_methods exceptions
+      methods_to_hide = public_instance_methods.clone
+      exceptions.each do |to_stay_public|
+        methods_to_hide.delete(to_stay_public)
+      end
+      private *methods_to_hide
+    end
+  end
+end

data/lib/peachy/method_name.rb

@@ -0,0 +1,31 @@
+module Peachy
+  class MethodName
+    include StringStyler
+
+    def initialize method_name
+      @method_name = method_name.to_s
+    end
+
+    # Returns an array of distinct valid variations in the method name.
+    # The valid varations are the underlying method name, plus all variations
+    # provided by methods defined in the StringStyler module.
+    def variations
+      (variation_methods.inject([@method_name]) do |array, method|
+        array << send(method)
+      end).uniq
+    end
+
+    def to_s
+      return @method_name
+    end
+
+    def to_sym
+      return @method_name.to_sym
+    end
+
+    private
+    def variation_methods
+      Peachy::StringStyler.private_instance_methods
+    end
+  end
+end

data/lib/peachy/proxy.rb

@@ -0,0 +1,150 @@
+require 'rubygems'
+require 'nokogiri'
+
+module Peachy
+  class Proxy
+    alias_method :original_method_missing, :method_missing
+    extend MethodMask
+    include ConventionChecks
+
+    # This hides all public methods on the class except for 'methods' and
+    # 'respond_to?' and 'inspect', which I've found are too useful to hide for
+    # the time being.
+    hide_public_methods ['methods', 'respond_to?', 'inspect']
+
+    # Takes a hash as an argument.  Valid keys are:
+    #   :xml -
+    #       used to pass raw XML into the Proxy, and the XML parser will be
+    #       created on the fly.
+    #   :nokogiri -
+    #       can be used to pass in a Nokogiri::XML instance, if one has
+    #       already been created.
+    def initialize arguments
+      @nokogiri_node = arguments[:nokogiri]
+      @xml = arguments[:xml]
+    end
+
+    # Overloaded so that calls to methods representative of an XML element or
+    # attribute can be generated dynamically.
+    #
+    # For example, if a proxy is referenced in code as proxy.first_node, and
+    # first_node does match a child of the DOM encapsulated by proxy, then
+    # first_node will be generated on proxy.
+    #
+    # However, if first_node does not represent a child in the underlying DOM
+    # then proxy will raise a NoMatchingXmlPart error.
+    #
+    # The method name used to access an XML node has to follow the standard Ruby
+    # convention for method names, i.e. ^[a-z]+(?:_[a-z]+)?{0,}$.  If an attempt
+    # is made to call a method on a Peachy::Proxy that breaks this convention,
+    # Peachy will simply raise a MethodNotInRubyConvention error.
+    #
+    # Any calls to undefined methods that include arguments or a block will be
+    # deferred to the default implementation of method_missing.
+    def method_missing method_name_symbol, *args, &block
+      original_method_missing method_name_symbol, args, &block if args.any? or block_given?
+      generate_method_for_xml MethodName.new(method_name_symbol)
+    end
+
+    private
+    def generate_method_for_xml method_name
+      check_for_convention(method_name)
+      attribute_content = create_from_parent_with_attribute method_name, nokogiri_node
+      return attribute_content unless attribute_content.nil?
+      create_method_for_child_or_content method_name, nokogiri_node
+    end
+
+    def nokogiri_node
+      raise InvalidProxyParameters.new(:xml => nil, :nokogiri => nil) if variables_are_nil?
+      @nokogiri_node ||= Nokogiri::XML(@xml)
+    end
+
+    def variables_are_nil?
+      @xml.nil? and @nokogiri_node.nil?
+    end
+
+    def create_method_for_child_or_content method_name, node
+      matches = find_matches(method_name, node)
+      return create_from_element_list method_name, matches if matches.size > 1
+      return create_from_element(matches[0]) {|child| define_child method_name, child }
+    end
+
+    # Runs the xpath for the method name against the underlying XML DOM, raising
+    # a NoMatchingXmlPart if no element or attribute matching the method name is
+    # found in the children of the current location in the DOM.
+    def find_matches method_name, node #=nokogiri_node
+      matches = node.xpath(xpath_for(method_name))
+      raise NoMatchingXmlPart.new(method_name) if matches.length < 1
+      return matches
+    end
+
+    def xpath_for method_name
+      method_name.variations.map {|variation| "./#{variation}" } * '|'
+    end
+
+    def create_from_parent_with_attribute method_name, node
+      if there_are_child_nodes?(node) and node_has_attributes?(node)
+        match = node.attribute(method_name.to_s)
+        create_content_child(match) {|child| define_child method_name, child } unless match.nil?
+      end
+    end
+
+    def create_from_element_list method_name, matches
+        define_method(method_name) { return matches_to_array matches }
+    end
+
+    def matches_to_array matches
+      matches.inject([]) {|array, child| array << create_from_element(child) }
+    end
+
+    def create_from_element match, &block
+      return create_proxy match, &block if there_are_child_nodes?(match)
+      return create_proxy_with_attributes match, &block if node_has_attributes?(match)
+      return create_content_child match, &block
+    end
+
+    def node_has_attributes? match
+      match.attribute_nodes.size > 0
+    end
+
+    # Determines whether the given element contains any child elements or not.
+    # The choice of implementation is based on performance tests between using
+    # XPath and a Ruby iterator.
+    def there_are_child_nodes? match
+      match.children.any? {|child| child.kind_of? Nokogiri::XML::Element }
+    end
+
+    def create_content_child match, &block
+      create_child match.content, &block
+    end
+
+    def create_proxy match, &block
+      create_child Proxy.new(:nokogiri => match), &block
+    end
+
+    def create_proxy_with_attributes match, &block
+      create_child ChildlessProxyWithAttributes.new(:nokogiri => match), &block
+    end
+
+    def create_child child
+      yield child if block_given?
+      return child
+    end
+
+    def define_child method_name, child
+      define_method(method_name) { return child }
+    end
+
+    # I don't like this hacky way of getting hold of the singleton class to define
+    # a method, but it's better than instance_eval'ing a dynamic string to define
+    # a method.
+    def define_method method_name, &block
+      get_my_singleton_class.class_eval { define_method method_name.to_sym, &block }
+      yield
+    end
+
+    def get_my_singleton_class
+      (class << self; self; end)
+    end
+  end
+end

data/lib/peachy/string_styler.rb

@@ -0,0 +1,28 @@
+module Peachy
+  # Included in Peachy::MethodName.  All methods in this module expect an instance
+  # variable named @method_name to be defined.
+  module StringStyler
+    private
+    module Stripper
+      # This is a bit rubbish.  Need to include the method somewhere other than
+      # the private instance block in StringStyler.
+      def strip_underscores_and_upcase string
+        string.gsub(/_([a-z])/){|s| s.upcase}.delete('_')
+      end
+    end
+
+    include Stripper
+
+    def as_camel_case
+      strip_underscores_and_upcase(@method_name)
+    end
+
+    def as_pascal_case
+      strip_underscores_and_upcase(@method_name.capitalize)
+    end
+
+    def as_hyphen_separated
+      @method_name.gsub(/_/, '-')
+    end
+  end
+end

data/lib/peachy/version.rb

@@ -0,0 +1,3 @@
+module Peachy
+  VERSION = '0.1.2'
+end

data/lib/peachy.rb

@@ -0,0 +1,12 @@
+require File.join(File.dirname(__FILE__), 'invalid_proxy_parameters')
+require File.join(File.dirname(__FILE__), 'method_not_in_ruby_convention')
+require File.join(File.dirname(__FILE__), 'no_matching_xml_part')
+require File.join(File.dirname(__FILE__), 'peachy/convention_checks')
+require File.join(File.dirname(__FILE__), 'peachy/string_styler')
+require File.join(File.dirname(__FILE__), 'peachy/method_name')
+require File.join(File.dirname(__FILE__), 'peachy/method_mask')
+require File.join(File.dirname(__FILE__), 'peachy/proxy')
+require File.join(File.dirname(__FILE__), 'peachy/childless_proxy_with_attributes')
+
+module Peachy
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: peachy
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 2
+  version: 0.1.2
+platform: ruby
+authors: 
+- NJ Pearman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-05 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 3
+        version: 1.3.3
+  type: :runtime
+  version_requirements: *id001
+description: |
+  Peachy is an XML slurper that sits on to of existing XML parsers.  It dynamically 
+  creates object-style hierachies for simple ingration of XML data sources.
+
+email: 
+- n.pearman@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/peachy/convention_checks.rb
+- lib/peachy/childless_proxy_with_attributes.rb
+- lib/peachy/method_name.rb
+- lib/peachy/method_mask.rb
+- lib/peachy/version.rb
+- lib/peachy/proxy.rb
+- lib/peachy/string_styler.rb
+- lib/no_matching_xml_part.rb
+- lib/invalid_proxy_parameters.rb
+- lib/method_not_in_ruby_convention.rb
+- lib/peachy.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/njpearman/peachy
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Peachy gives a very simple object-style interface on top of an XML DOM.
+test_files: []
+