sawtooth 0.2.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in sawtooth.gemspec
+gemspec

data/README.md

@@ -0,0 +1,38 @@
+
+                                                                   __
+                                                       _____....--' .'
+                                          _..___...---'._ o      -`(
+                           _             | |  _         \   .--.  `\
+        ___  __ ___      _| |_ ___   ___ | |_| |__      |   \   \ `|
+       / __|/ _` \ \ /\ / / __/ _ \ / _ \| __| '_ \     |o o |  |  |
+       \__ \ (_| |\ V  V /| || (_) | (_) | |_| | | |     \___'.-`.  '.
+       |___/\__,_| \_/\_/  \__\___/ \___/ \__|_| |_|          |   `---'
+      '^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^'
+
+A companion for [nokogori](http://nokogiri.org) to parse XML files by rules,
+similar to [Apache Commons Digester](http://commons.apache.org/digester/).
+
+Converting XML structures into Ruby is most often an unsatisfying task, having
+to choose between implementing a SAX parser (for speed) or using _nokogiri_
+features like CSS selectors for ease of use. At it's base _sawtooth_ is parsing
+documents using SAX, but provides an interface to specify rules for the handling
+the document.
+
+    require 'open-uri'
+    require 'sawtooth'
+
+    rules = Sawtooth.rules do
+      before { |doc| doc << [] }                  # 1. create an array for all news items
+
+      on 'rss/channel/item' do
+        on_start  { |doc| doc << Hash.new }       # 2. on an item create hash
+        on_finish { |doc| doc.parent << doc.pop } # 3. when closing an item, pop from stack and
+      end                                         #    append to parent array (from step 1.)
+
+      on_text 'rss/channel/item/*'                # 4. add contents to hash
+    end
+
+    result = rules.parse(open('http://rss.cnn.com/rss/edition.rss')).root
+    p result #=> [{ 'title' => 'Some CNN News...', 'guid' =>, ...}, ...]
+
+This sample shows the DSL exposed to create the XML parsing rules for an RSS feed.

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the sawtooth gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/lib/sawtooth.rb

@@ -0,0 +1,8 @@
+require "sawtooth/rules"
+require "sawtooth/document"
+require "sawtooth/parser"
+require "sawtooth/builder"
+
+module Sawtooth
+  autoload :VERSION, "sawtooth/version"
+end

data/lib/sawtooth/builder.rb

@@ -0,0 +1,106 @@
+require 'sawtooth/parser'
+require 'sawtooth/rules'
+
+module Sawtooth
+
+  # Yield a builder instance and start working on pushing
+  # rules around like crazy.
+  #
+  def self.rules(&block)
+    Sawtooth::Builder.new(&block)
+  end
+
+  # Provides a nice and hopefully easy to use DSL to build rules and start
+  # parsing XML documents with ease.
+  #
+  class Builder
+
+    # Has access to a set of rules.
+    attr_reader :rules
+
+    # Creates a new instance.
+    def initialize(&block)
+      @rules = Sawtooth::Rules::Set.new
+      self.instance_eval(&block) if block_given?
+    end
+
+    # Get a parser instance with the same set of
+    # rules.
+    def parser
+      @parser ||= Sawtooth::Parser.new(:rules => self.rules)
+    end
+
+    # Shortcut method to parse some input, delegates to the
+    # parser.
+    def parse(thingy)
+      parser.parse(thingy)
+    end
+
+    # Called before the document starts.
+    def before(&block)
+      rules.add('@document:before', Sawtooth::Rules::CallRule.new(:start => block)) if block_given?
+    end
+
+    # Called after the document has ended.
+    def after(&block)
+      rules.add('@document:after', Sawtooth::Rules::CallRule.new(:finish => block)) if block_given?
+    end
+
+    def on_start(path, &block)
+      rules.add(path, Sawtooth::Rules::CallRule.new(:start => block)) if block_given?
+    end
+
+    # Called when the node has finished parsing, i.e. text and everything is available.
+    #
+    def on_finish(path, &block)
+      rules.add(path, Sawtooth::Rules::CallRule.new(:finish => block)) if block_given?
+    end
+    alias_method :on_node, :on_finish
+
+    # Perform a rule on a block, optionally pass in a custom rule instance.
+    def on(path, rule = nil, &block)
+      rule = block.arity <= 0 ? Sawtooth::Rules::CallRule.new(&block) : Sawtooth::Rules::CallRule.new(:start => block) if block_given?
+      rules.add(path, rule) if rule
+    end
+
+    # Use and set a nodes text to the top object in the stack.
+    #
+    #    # Simple mapping, sets "name"
+    #    on_text 'Person/Name'
+    #
+    #    # Custom mapping
+    #    on_text 'Person/Name' => :lastname
+    #
+    #    # Data Conversion
+    #    on_text('Person/Age') { |str| str.to_i }
+    #
+    #    # Multiple Mappings
+    #    on_text 'Person/Name' => :lastname, 'Person/FirstName' => :firstname
+    #
+    # The `TextRule` tries to set the value using a setter, or a hash
+    # accessor and the `document.top` object.
+    def on_text(mappings = {}, &block)
+      if mappings.respond_to?(:to_str)
+        rules.add(mappings.to_str, Sawtooth::Rules::TextRule.new(&block))
+      else
+        mappings.each do |path, name|
+          rules.add(path, Sawtooth::Rules::TextRule.new(name, &block))
+        end
+      end
+    end
+
+    def delegate(delegation = {})
+      path = delegation.keys.find { |k| k.to_s =~ %r{/\*\*?\z} }
+      cb_path = path.gsub(%r{/\*\*?\z}, '')
+      to = delegation[path]
+      prefix = delegation[:prefix] || path.gsub(%r{/?[^/]+/\*\*?\z}, '')
+
+      rule = Sawtooth::Rules::DelegateRule.new(:path => path, :rules => to.respond_to?(:rules) ? to.rules : to, :prefix => prefix)
+      rules.add(cb_path, rule.before_after_callbacks_rule)
+      rules.add(path, rule)
+    end
+
+    # Pretty print rules.
+    def to_pretty_s; rules.print_rules end
+  end
+end

data/lib/sawtooth/document.rb

@@ -0,0 +1,158 @@
+require 'nokogiri/xml/sax'
+
+module Sawtooth
+
+  # Provides the current parser stack, delegates
+  # basically all calles to the supplied parser.
+  #
+  # Also the document exposes methods which can be
+  # used to directly interact with the stack.
+  class Document < ::Nokogiri::XML::SAX::Document
+
+    # A simple Document Node representation, for the node stack.
+    Node = Struct.new(:namespace, :name, :attributes, :text) do
+      def to_s; name end
+    end
+
+    class Stack < Array
+      def peek(n = 0)
+        self[(n + 1) * -1]
+      end
+
+      def current; peek(0) end
+      alias_method :top, :current
+
+      def parent; peek(-1) end
+
+      def root; first end
+    end
+
+    # Special freaky node for the Document and Comments
+    DOCUMENT_NODE = [Node.new(nil, '@document')]
+    COMMENT_NAME  = '@comment'
+
+    # Both the stack and the delegate can be accessed.
+    attr_reader :stack, :stacks
+    attr_accessor :delegate
+
+    # Creates a new Document instance with an empty stack
+    # and the supplied delegate. The delegate is required to
+    # apply the rules.
+    def initialize(delegate = nil)
+      @delegate = delegate
+      reset!
+    end
+
+    # Allow an element to be pushed onto the stack
+    def <<(obj)
+      stack << obj
+      self
+    end
+    alias_method :push, :<<
+
+    # Pop an element of the stack
+    def pop
+      stack.pop
+    end
+
+    # Peek at an element in the stack, i.e. element 0 is the last
+    # element.
+    #
+    #    doc.peek     # => returns last element
+    #    doc.peek(1)  # => returns second last element
+    #
+    def peek(n = 0)
+      stack[(n + 1) * -1]
+    end
+
+    # Shortcut method for current, i.e. an alias of peek without
+    # an argument.
+    def current; peek(0) end
+    alias_method :top, :current
+
+    # Alias for `peek(1)`.
+    def parent; peek(1); end
+
+    # Alias for `stack.first`
+    def root; stack.first end
+
+    # Get current path stack.
+    def path; @path_stack end
+
+    # Get current node.
+    def node; @path_stack.last end
+
+    # Direct access to customizeable stacks
+    def [](key)
+      stacks[key]
+    end
+
+    # Resets path, stack and the current text.
+    def reset!
+      @path_stack = []
+      @stack = []
+      @stacks = Hash.new { |hsh, k| hsh[k] = Stack.new }
+      @text = nil
+    end
+
+    # Characters and CDATA will be appended the current text block, if any
+    def characters(str)
+      @text ||= ""
+      @text << str
+    end
+    alias_method :cdata_block, :characters
+
+    # Called when comments are encountered, empty implementation,
+    def comment(str)
+      cnode = Node.new(nil, COMMENT_NAME, {}, str)
+      delegate.comment((DOCUMENT_NODE + path + [cnode]).compact, self, cnode) if delegate.respond_to?(:comment)
+    end
+
+    # Called when document starts parsing, clears path and stack
+    # and calls with special @document path.
+    def start_document
+      reset!
+      delegate.start_document(DOCUMENT_NODE, self) if delegate.respond_to?(:start_document)
+    end
+
+    # Callend when document ends parsing, does call with
+    # special @document path.
+    def end_document
+      delegate.end_document(DOCUMENT_NODE, self) if delegate.respond_to?(:end_document)
+    end
+
+    # Called at the beginning of an element.
+    def start_element_namespace(name, attrs_ary = [], prefix = nil, uri = nil, ns = [])
+      @text = nil
+      node = Node.new(uri, name, attrs_ary.inject({}) { |hsh, a| hsh[a.localname] = a.value; hsh }, '')
+      path << node
+
+      # call delegate
+      delegate.start_element(path, self, node) if delegate.respond_to?(:start_element)
+    end
+
+    # Called at the end of an element.
+    def end_element_namespace(name, prefix = nil, uri = nil)
+      # fill text
+      node.text = @text.to_s.strip if @text
+
+      # call delegate
+      delegate.end_element(path, self, node) if delegate.respond_to?(:end_element)
+
+      # clear stack
+      @path_stack.pop
+      @text = nil
+    end
+
+    # Pass a warning along to the parser
+    def warning(string)
+      delegate.warning(path, self, string) if delegate.respond_to?(:warning)
+    end
+
+    # Pass an error along to the parser, parser should handle
+    # whether to continue or abort parsing.
+    def error(string)
+      delegate.error(path, self, string) if delegate.respond_to?(:error)
+    end
+  end
+end

data/lib/sawtooth/parser.rb

@@ -0,0 +1,67 @@
+require 'nokogiri'
+
+require 'sawtooth/document'
+require 'sawtooth/rules/set'
+
+module Sawtooth
+
+  # Default Parser implementation, can be used as a
+  # starting point for custom implementations.
+  #
+  class Parser
+
+    # Array of accessible rules.
+    attr_reader :rules
+
+    # Creates a new instance.
+    def initialize(options = {})
+      @rules = options[:rules] || Sawtooth::Rules::Set.new
+    end
+
+    # Delegates to `Rules::Set#add`.
+    def add(path, rule)
+      rules.add(path, rule)
+    end
+
+    # Recieved a comment node.
+    def comment(path, doc, str); end
+
+    # Start document callback
+    def start_document(path, doc)
+      rule = rules.find('@document:before')
+      rule.start(path.join('/'), doc, nil) if rule && rule.respond_to?(:start)
+    end
+
+    # End document callback
+    def end_document(path, doc)
+      rule = rules.find('@document:after')
+      rule.finish(path.join('/'), doc, nil) if rule && rule.respond_to?(:finish)
+    end
+
+    # Start element callback
+    def start_element(path, doc, node)
+      rule = rules.find(path)
+      rule.start(path.join('/'), doc, node) if rule && rule.respond_to?(:start)
+    end
+
+    # End document callback
+    def end_element(path, doc, node)
+      rule = rules.find(path)
+      rule.finish(path.join('/'), doc, node) if rule && rule.respond_to?(:finish)
+    end
+
+    def error(path, doc, message)
+      raise message
+    end
+
+    # Parses and XML thingy, a filename, path, IO or content
+    # from memory. Provides and optional encoding, which defaults
+    # to `UTF-8`.
+    def parse(thing, encoding = 'UTF-8')
+      Sawtooth::Document.new(self).tap do |doc|
+        sax_parser = Nokogiri::XML::SAX::Parser.new(doc, encoding)
+        sax_parser.parse(thing)
+      end
+    end
+  end
+end

data/lib/sawtooth/rules.rb

@@ -0,0 +1,6 @@
+require 'sawtooth/rules/base'
+require 'sawtooth/rules/set'
+
+Dir[File.dirname(__FILE__) + '/rules/*_rule.rb'].each do |rule|
+  require rule
+end

data/lib/sawtooth/rules/base.rb

@@ -0,0 +1,32 @@
+module Sawtooth
+  module Rules
+
+    # Base Rule, provides three unimplemented methods, which
+    # can be overriden by more specific rules - like the create
+    # or call rule etc.
+    #
+    class Base
+
+      # Called when the beginning of a matching XML node is encountered.
+      #
+      # - path, current (maybe rewritten) path
+      # - document, the current sawtooth parser stack (`Sawtooth::Document`)
+      # - node, the current node to process
+      def start(path, document, node)
+      end
+
+      # Called when the end of a matching XML node is encountered.
+      # If an element has no body, this method is called with an empty
+      # string instead.
+      #
+      # - path, current (maybe rewritten) path
+      # - document, the current sawtooth parser stack (`Sawtooth::Document`)
+      # - node, the current node
+      def finish(path, document, node)
+      end
+
+      # Basically calls inspect
+      def print_rule; self.class.name end
+    end
+  end
+end