digestr 0.0.2

data/TODO

@@ -0,0 +1,10 @@
+= DigestR project -- Todo list
+
+Most of the following ideas will probably be implemented at some point.
+Send any suggestions or patches (preferably as/with tests) to:
+
+  rosco <at> roscopeco <dot> co <dot> uk
+
+* Namespace support
+* Many standard rule types remain to be implemented
+

data/install.rb

@@ -0,0 +1,35 @@
+require 'rbconfig'
+require 'find'
+require 'ftools'
+
+include Config
+
+$ruby = CONFIG['ruby_install_name']
+$sitedir = CONFIG["sitelibdir"]
+unless $sitedir
+  version = CONFIG["MAJOR"]+"."+CONFIG["MINOR"]
+  $libdir = File.join(CONFIG["libdir"], "ruby", version)
+  $sitedir = $:.find {|x| x =~ /site_ruby/}
+  if !$sitedir
+    $sitedir = File.join($libdir, "site_ruby")
+  elsif $sitedir !~ Regexp.quote(version)
+    $sitedir = File.join($sitedir, version)
+  end
+end
+
+if (destdir = ENV['DESTDIR'])
+  $sitedir = destdir + $sitedir  
+  File::makedirs($sitedir)
+end
+
+# The library files
+
+files = Dir.chdir('lib') { Dir['**/*.rb'] }
+for fn in files
+  fn_dir = File.dirname(fn)
+  target_dir = File.join($sitedir, fn_dir)
+  if ! File.exist?(target_dir)
+    File.makedirs(target_dir)
+  end
+  File::install(File.join('lib', fn), File.join($sitedir, fn), 0644, true)
+end

data/lib/xml/digester.rb

@@ -0,0 +1,10 @@
+# === DigestR - Libxml2-based XML Digester similar to Jakarta Commons Digester.
+#
+# Copyright (c)2006 Ross Bamford (and contributors). All rights reserved.
+# See LICENSE for copyright and license information.
+#
+# Main documentation in XML::Digester
+#
+# $Id: digester.rb 4 2006-04-17 19:05:32Z roscopeco $
+
+require File.join(File.dirname(__FILE__),'digestr.rb')

data/lib/xml/digestr.rb

@@ -0,0 +1,810 @@
+# === DigestR - Libxml2-based XML Digester similar to Jakarta Commons Digester.
+#
+# Copyright (c)2006 Ross Bamford (and contributors). All rights reserved.
+# See LICENSE for copyright and license information.
+#
+# Main documentation in XML::Digester
+#
+# $Id: digestr.rb 6 2006-04-18 01:15:49Z roscopeco $
+
+require 'xml/libxml'
+
+module XML #:nodoc:
+
+  # Processes XML input according to a series of rules applied prior
+  # to the parse beginning. A Digester instance wraps an instance 
+  # of XML::SaxParser and uses it's own event callbacks to trigger
+  # the configured rules as appropriate.
+  #
+  # This API is based on the Jakarta Commons Digester library
+  # (http://jakarta.apache.org/commons/digester), and is intended
+  # to provide similar semantics to that package in a pleasingly
+  # Rubyish manner.
+  #
+  # ==== Notes
+  #
+  # * It's not yet as fast as I'd like.
+  # * There is currently no namespace support.  
+  class Digester
+    VERSION = "0.0.1"
+    
+    # Raised to signal errors in rule processing when +pedantic+ is
+    # true.
+    class Error < RuntimeError; end
+    
+    # Base-class for rule implementations. This class implements the
+    # standard (currently fnmatch-based) pattern matching logic and
+    # can be used as a base-class for custom rule implementations.
+    class RulesBase
+      attr_reader :pattern
+      attr_accessor :digester
+      
+      # Be sure to call through to here when subclassing RulesBase.
+      def initialize(pattern)
+        @pattern = pattern or raise ArgumentError, "No pattern given"
+        @pattern = '/' + @pattern unless @pattern[0] == ?/
+      end
+
+      # Called at start of matching element.
+      def begin(namespace, name, attrs); end
+
+      # Called when body text is encountered.
+      def body(txt); end
+
+      # Called at end of matching element (in reverse order
+      # of rule registration).
+      def end(namespace, name); end
+
+      # Called at the end of the parse (again, in reverse order).
+      def finish; end
+      
+      attr_accessor :next, :prev  #:nodoc:      
+    end
+
+    # Rule that executes the given block when matched. The
+    # supplied block should have a variable argument count,
+    # since it is used with different arguments by the
+    # different events, as follows:
+    #
+    #     begin : { |:begin, digester, namespace, name, attrs| ... }
+    #     body  : { |:body, digester, txt| ... }
+    #     end   : { |:end, digester, namespace, name| ... }
+    #     finish: { |:finish| ... }
+    class BlockRule < RulesBase
+      # call-seq:
+      #   BlockRule.new(pattern) { |*args| ... }
+      # 
+      # Create a new BlockRule with the supplied block.
+      def initialize(pattern, &blk)
+        super(pattern)
+        @blk = blk or raise ArgumentError, "No block given"
+      end
+      
+      def begin(namespace, name, attrs) #:nodoc:
+        @blk.call(:begin, @digester, namespace, name, attrs)
+      end
+
+      def body(txt) #:nodoc:
+        @blk.call(:body, @digester, txt)
+      end
+
+      def end(namespace, name) #:nodoc:
+        @blk.call(:end, @digester, namespace, name)
+      end
+
+      def finish #:nodoc:
+        @blk.call(:finish)
+      end
+    end
+
+    # Rule that creates an instance of the specified class (or alternatively
+    # obtains the result of a call to specified method on the specified 
+    # object, possibly with custom arguments) and pushes it onto the stack
+    # in the *begin* event, and pops it off again in the *end* event.
+    # This combines the functionality of both ObjectCreateRule and 
+    # FactoryCreateRule from commons digester.
+    #
+    # It is also possible to supply a block, in which case it will be
+    # executed when the rule is triggered (in *begin*) and the result
+    # from that pushed. In this case, any class/message will be ignored.
+    class ObjectCreateRule < RulesBase
+      # call-seq:
+      #   ObjectCreateRule.new(pattern, klass, message = :new, *args)
+      #   ObjectCreateRule.new(pattern, obj, message, *args)
+      #   ObjectCreateRule.new(pattern) { ... }
+      #
+      # Create a new ObjectCreateRule with the specified class,
+      # method call or block.
+      def initialize(pattern, klass = Object, msg = :new, *args, &blk)
+        super(pattern)
+        @klass, @msg, @args, @blk = klass, msg, args, blk
+      end
+      
+      def begin(namespace, name, attrs) #:nodoc:
+        @digester.push(if b = @blk 
+          b.call(*@args)
+        else
+          @klass.send(@msg, *@args)
+        end)
+      end
+
+      def end(namespace, name) #:nodoc:
+        @digester.pop
+      end      
+    end
+
+    # Rule that sets attributes on the top object on the 
+    # stack based on values from the current element's attributes. 
+    # This rule often follows an ObjectCreateRule with the same pattern
+    # in order to configure the newly created object. The attributes
+    # are set in the *begin* event.
+    class SetPropertiesRule < RulesBase
+      # call-seq:
+      #   SetPropertiesRule.new(pattern, [mapping])
+      #   SetPropertiesRule.new(pattern, [mapping]) { |target, attr, value| ... }
+      #
+      # Create a new SetPropertiesRule. The optional mapping 
+      # parameter allows a mapping between XML attribute names and 
+      # the corresponding ruby attribute name/type. It should quack
+      # like a hash, and return entries of the form:
+      #
+      #   xml_name => ruby_name
+      #   xml_name => coerce_type
+      #   xml_name => [ruby_name, coerce_type]
+      #
+      # where +ruby_name+ is the name of the attribute that is to be
+      # set, +coerce_type+ is the class (for which a coercion method must
+      # be defined on Kernel) the attribute value should be coerced to.
+      # The mapping may mix entries of the three forms.
+      #
+      # If a block is supplied, it is called (during *begin*) for
+      # each attribute that is to be set. The +target+ argument supplies
+      # the top stack object, while +attr+ and +value+ supply the attribute 
+      # name and value, processed according to the mapping rules.
+      def initialize(pattern, 
+                     mapping = Hash.new { |h,k| h[k] = k }, 
+                     &blk)
+        super(pattern)
+        @mapping = mapping
+        @blk = blk
+      end
+      
+      def begin(namespace, name, attrs) #:nodoc:
+        if (top = @digester.peek)
+          attrs.each do |k,v|
+            obj_attr, coerce = @mapping[k] || k
+            
+            # allow a single class to be specified if same
+            # name is to be used
+            if obj_attr.kind_of? Module
+              coerce, obj_attr = obj_attr, k
+            end
+              
+            if coerce && coerce != String
+              v = send(coerce.name, v)            
+            end
+            
+            unless obj_attr == :nil
+              if b = @blk
+                b.call(top,obj_attr,v)
+              else
+                setter = "#{obj_attr}="
+                begin
+                  top.send(setter,v)
+                rescue NoMethodError
+                  if @digester.pedantic?
+                    raise Error,
+                        "Unknown property attribute: #{name} for #{top.inspect}"
+                  end
+                  nil
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Rule that sets a single ruby attribute on the top stack object. The 
+    # attribute name and value to set are obtained from the specified XML 
+    # attributes. The attribute is set in the *begin* event.     
+    class SetPropertyRule < RulesBase
+      # call-seq:
+      #   SetPropertyRule.new(pattern, name_attr = 'name', value_attr = 'value', type = String)
+      #   SetPropertyRule.new(pattern, name_attr = 'name', value_attr = 'value', type = String) { |target, attr, value| ... }
+      #
+      # Create a new SetPropertyRule that will set the ruby attribute named by
+      # the 'name_attr' XML attribute to the value specified by the 'value_attr'
+      # XML attribute. Given, for example, a rule:
+      #
+      #   SetPropertyRule.new('*/a', 'foo_name', 'foo_val')
+      #
+      # And the following element:
+      #
+      #   <a foo_name='foo', foo_value='bar'/>
+      #
+      # The message sent to the top object on the stack would look like:
+      #
+      #   top.send(:foo=, 'bar')
+      #
+      # You may optionally specify a coercion type, which should be the class
+      # the value should be converted to. The same rules apply as with the
+      # SetPropertiesRule.   
+      # 
+      # If a block is supplied, it is called (during *begin*). The +target+ 
+      # argument supplies the top stack object, while +attr+ and +value+ 
+      # supply the attribute name and value, processed according to the mapping rules.
+      # The block should set the attribute appropriately.
+      def initialize(pattern, name_attr = 'name', value_attr = 'value', type = String, &blk)
+        super(pattern)
+        @name_attr, @value_attr, @blk = name_attr, value_attr, blk
+        @type = type
+      end
+      
+      def begin(namespace, name, attrs) #:nodoc:
+        dig = @digester
+        if name = attrs[@name_attr]
+          value = attrs[@value_attr]
+          
+          if ltype = @type   
+            begin
+              (value = send(ltype.name,value)) unless ltype == String
+            rescue ArgumentError, TypeError
+              if dig.pedantic?
+                raise Error, $!.message
+              end
+            end
+          end
+
+          if (top = dig.peek)
+            if b = @blk
+              b.call(top, name, value)
+            else
+              begin
+                top.send("#{name}=", value)
+              rescue NoMethodError
+                if dig.pedantic?
+                  raise Error,
+                      "Unknown property attribute: #{name} for #{top.inspect}"
+                end
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Rule that allows links to be made between the top two stack objects
+    # using a supplied block. See SetNextRule and SetTopRule for common-case
+    # specializations of this class. Operates within the *end* event.
+    class LinkRule < RulesBase
+      
+      # call-seq:
+      #   LinkRule.new(pattern) { |parent, child| ... }
+      #
+      # Create a new LinkRule that, when matched, will pass the top two
+      # elements (in order - see below) to the supplied block.
+      #
+      # The notion of 'parent' and 'child' is quite arbitrary, and merely
+      # reflects the common usage of this rule. Specifically, the 'parent'
+      # is the next-to-top stack element, while the 'child' is the top
+      # element itself.
+      def initialize(pattern, &blk)
+        super(pattern)
+        @blk = blk or raise ArgumentError, "No block given"
+      end
+
+      def end(namespace, name) #:nodoc:
+        stk = @digester.stack
+        if stk.length > 1
+          @blk.call(stk[-2], stk[-1])
+        else
+          if @digester.pedantic?
+            raise Error,
+              "Cannot link: no parent on stack: #{digester.stack.inspect}"
+          end
+        end
+      end      
+    end
+
+    # Rule that allows a parent -> child relationship to be created
+    # between the top two stack elements via a given method call.
+    # This is a specialized LinkRule that calls a method on the
+    # next-to-top stack element, passing in the top element as an argument.
+    # Often, the called method will have a name like 'add_child'. 
+    #
+    # Like LinkRule, this rule operates in the *end* event. See also
+    # SetTopRule.
+    class SetNextRule < LinkRule
+      # call-seq:
+      #   SetNextRule.new(pattern, msg, *additional_args)
+      #
+      # Create a new SetNextRule that will send the specified message
+      # to the next-to-top stack object, passing in the top object
+      # as the initial parameter, followed by any additional arguments
+      # supplied to this method.
+      def initialize(pattern, msg, *args)
+        super(pattern) do |parent, child| 
+          begin
+            parent.send(msg, child, *args) 
+          rescue NoMethodError
+            if digester.pedantic?
+              raise Error,
+                  "Cannot SetNext: no method #{msg} for #{parent.inspect}"
+            end
+            nil
+          end
+        end
+      end
+    end
+    
+    # Rule that allows a child -> parent relationship to be created
+    # between the top two stack elements via a given method call.
+    # This is a specialized LinkRule that calls a method on the
+    # top stack element, passing in the next-to-top element as an 
+    # argument. Often, the called method will have a name like 
+    # 'set_parent'. 
+    #
+    # Like LinkRule, this rule operates in the *end* event. See
+    # also SetNextRule.   
+    class SetTopRule < LinkRule
+      # call-seq:
+      #   SetTopRule.new(pattern, msg, *additional_args)
+      #
+      # Create a new SetTopRule that will send the specified message
+      # to the top stack object, passing in the next-to-top object
+      # as the initial parameter, followed by any additional arguments
+      # supplied to this method.
+      def initialize(pattern, msg, *args)
+        super(pattern) do |parent, child|
+          begin
+            child.send(msg, parent, *args)
+          rescue NoMethodError
+            if digester.pedantic?
+              raise Error,
+                  "Cannot SetTop: no method #{msg} for #{parent.inspect}"
+              nil
+            end
+          end
+        end
+      end
+    end
+
+    # Rule that allows a given method to be called on an object
+    # on the stack, with arguments collected from the stack or
+    # XML attributes (possibly on nested elements) and element 
+    # bodies using CallParamRule. The actual call is executed
+    # in the *end* event.
+    class CallMethodRule < RulesBase
+      # call-seq:
+      #   CallMethodRule.new(pattern, msg, target_ofs = 0, *extra_args)
+      #   CallMethodRule.new(pattern) { |target| ... }
+      #   CallMethodRule.new(pattern, nil, target_ofs, *extra_args) { |target, *args| ... }
+      #  
+      # Create a new CallMethodRule that will call the given method
+      # on the object at the given offset from the top of the stack
+      # (positive only, increasing distance from the stack top).
+      # Any additional arguments supplied are *suffixed* on the arguments
+      # collected from any nested CallParamRule matches, and passed
+      # to the method in the *end* event.
+      #
+      # If a block is supplied, this will be called instead of a method.
+      # In this case, the +msg+ argument will be ignored.
+      def initialize(pattern, msg = nil, target_ofs = 0,*args, &blk)
+        unless msg || blk
+          raise ArgumentError, "Either a message or block is required"
+        end
+        
+        super(pattern)
+        @msg, @target_ofs, @args, @blk = msg, target_ofs, args, blk
+      end
+      
+      def begin(namespace, name, attrs) #:nodoc:
+        @digester.rulestack.push([])
+      end
+
+      def end(namespace, name) #:nodoc:
+        dig = @digester
+        largs = dig.rulestack.pop + @args
+        targ = dig.stack[-(@target_ofs+1)]
+        if b = @blk
+          b.call(targ,*largs)
+        else
+          begin
+            targ.send(@msg, *largs)
+          rescue NoMethodError
+            if dig.pedantic?
+              raise Error,
+                "Cannot CallMethod: no method '#{@msg}' on #{targ.inspect}"
+            end
+          end
+        end
+      end      
+    end 
+    
+    # Rule that collects arguments for a previous CallMethodRule.
+    # CallParamRule is typically matched on elements nested within
+    # those that trigger CallMethodRule. Parameters are referenced
+    # by index and can take their value from XML attributes, element
+    # bodies, or objects on the digester's stack.
+    class CallParamRule < RulesBase
+      EMPTYSTR = "" #:nodoc:
+      
+      # call-seq:
+      #   CallParamRule.new(pattern, param_idx, attr_name, type = String)
+      #   CallParamRule.new(pattern, param_idx, stack_index, type = String)
+      #   CallParamRule.new(pattern, param_idx, nil, type = String)
+      #   CallParamRule.new(pattern, param_idx = 0)
+      # 
+      # Create a new CallParamRule that will take it's parameter value
+      # from the specified source, or the current element body if
+      # source is +nil+. When the enclosing CallMethodRule executes
+      # it's *end* event, the value will be passed as the param_idx'th
+      # argument.
+      #
+      # If a class is supplied for the type argument, the value will
+      # be coerced to that type prior to the method call. See the
+      # SetPropertiesRule rule for more on the coercion mechanism.
+      def initialize(pattern, param_idx = 0, source = nil, type = String)
+        super(pattern)
+        @param_idx, @type = param_idx, type
+        @bodytxt = ""
+        
+        # wierd shit happening here, trying to factor as much work
+        # out of the rulechain processing as possible.
+        @argproc = case source
+          when nil
+            # element body
+            bt = @bodytxt
+            lambda { bt.strip }
+          when Integer
+            # stack
+            stackidx = -(source+1)
+            lambda { @digester.stack[stackidx] }
+          else
+            # attribute
+            srcs = source.to_s
+            lambda { @attrs[srcs] }
+        end        
+      end
+
+      def begin(namespace, name, attrs) #:nodoc:
+        @attrs = attrs
+      end
+
+      def body(txt) #:nodoc:
+        @bodytxt << txt
+      end
+
+      def end(namespace, name) #:nodoc:
+        arg = @argproc.call
+
+        if ltype = @type
+          begin          
+            arg = send(ltype.name, arg)
+          rescue NoMethodError
+            if @digester.pedantic?
+              raise Error, "No coercion method for #{@type.name}"
+            end
+          rescue ArgumentError, TypeError
+            if @digester.pedantic?
+              raise Error, $!.message
+            end
+          end
+        end
+        
+        @digester.rulestack.last[@param_idx] = arg      
+        @bodytxt.replace(EMPTYSTR)
+      end
+    end
+ 
+    #### DIGESTER IMPL ####
+    
+    # Obtain the XML::SaxParser used by this Digester
+    attr_reader :parser
+    
+    # Obtain the _rulestack_ - an auxiliary stack provided for rule-specific
+    # state storage.
+    attr_reader :rulestack
+    
+    # Obtain the path to the current element in the form: /a/b/c
+    attr_reader :current_path
+    
+    # Determines whether rules are pedantic (e.g. raise Errors when
+    # some attributes cannot be matched, or when a method call fails).
+    attr_accessor :pedantic
+    alias :pedantic? :pedantic
+
+    # Obtain the _userstack_. This is the main stack used by the digester,
+    # and should be used read-only - you must use the mutators provided by
+    # this class (#push, #pop, etc) to ensure the digester state remains
+    # consistent.
+    attr_reader :userstack
+    alias :stack :userstack
+
+    # Create a new Digester. If a parser is supplied, be aware that
+    # some of it's callbacks will be replaced:
+    #
+    # * on_start_document
+    # * on_start_element
+    # * on_characters
+    # * on_cdata_block
+    # * on_end_element
+    # * on_end_document
+    #
+    def initialize(pedantic = false, parser = XML::SaxParser.new)
+      @parser = parser
+      @parser.on_start_document(&method(:cb_start_document))
+      @parser.on_end_document(&method(:cb_end_document))
+      @parser.on_start_element(&method(:cb_start_element))
+      @parser.on_characters(&method(:cb_characters))
+      @parser.on_cdata_block(&method(:cb_characters))
+      @parser.on_end_element(&method(:cb_end_element))
+      @pedantic = !!pedantic
+      @userstack = []
+    end
+    
+    # call-seq:
+    #   parse_string(xml) -> first_object
+    #
+    # Parse the specified XML string and trigger appropriate rules
+    # in this Digester. Returns the first element that was pushed 
+    # onto the stack. 
+    def parse_string(xml)
+      @parser.string = xml
+      do_parse
+    end
+
+    # call-seq:
+    #   parse_file(filename) -> first_object
+    #
+    # Parse the specified XML file and trigger appropriate rules
+    # in this Digester. Returns the first element that was pushed 
+    # onto the stack. 
+    def parse_file(filename)
+      @parser.filename = filename
+      do_parse
+    end
+
+    # Clear the user stack and reset the digester state.
+    def clear
+      @userstack.clear
+      @rulestack = []
+    end
+
+    # Retrieve a reference to the top user stack element, without
+    # actually popping it from the stack.
+    def peek
+      @userstack.last
+    end
+    
+    # Remove and return the top user stack element.
+    def pop
+      @userstack.pop
+    end
+    
+    # Push the supplied object +o+ onto the user stack.
+    def push(o)
+      @first ||= o
+      @userstack.push(o)
+    end
+    
+    # Obtain the name of the element currently being processed,
+    def current_element
+      stk = @current_path
+      stk.slice(stk.rindex('/')..-1)
+    end
+
+    ## ADD RULE METHODS ###
+    
+    # Add the specified rule to this digester.
+    def add_rule(rule)
+      rule.digester = self
+
+      if @first_rule
+        @last_rule.next, rule.prev = rule, @last_rule
+        @last_rule = rule
+      else
+        @first_rule = @last_rule = rule
+      end
+    end
+    
+    # call-seq:
+    #   add_block(pattern) { |*args| ... }
+    # 
+    # Add a new BlockRule with the supplied block. See BlockRule
+    # for details of the block's arguments.
+    def add_block(pattern, &blk)
+      add_rule(BlockRule.new(pattern, &blk))
+    end
+
+    # call-seq:
+    #   add_object_create(pattern, klass)
+    #   add_object_create(pattern, obj, message, *args)
+    #   add_object_create(pattern) { ... }
+    #
+    # Add a new ObjectCreateRule with the specified class,
+    # method call or block.
+    def add_object_create(pattern, klass = Object, msg = :new, *args, &blk)
+      add_rule(ObjectCreateRule.new(pattern,klass,msg,*args,&blk))
+    end
+    
+    # Compatibility alias for REXML-based xmldigester
+    alias :add_create_object :add_object_create
+    
+    # call-seq:
+    #   add_set_properties(pattern, [mapping])
+    #   add_set_properties(pattern, [mapping]) { |target, attr, value| ... }
+    #
+    # Add a new SetPropertiesRule. See SetPropertiesRule for details
+    # of the optional mapping format.
+    def add_set_properties(pattern, 
+                           mapping = Hash.new {|h,k| h[k] = k}, 
+                           &blk)
+      add_rule(SetPropertiesRule.new(pattern,mapping,&blk))
+    end
+
+    # call-seq:
+    #   add_set_property(pattern, name_attr = 'name', value_attr = 'value', type = String)
+    #   add_set_property(pattern, name_attr = 'name', value_attr = 'value', type = String) { |target, attr, value| ... }
+    #
+    # Add a new SetPropertyRule that will set the ruby attribute named by
+    # the 'name_attr' XML attribute to the value specified by the 'value_attr'
+    # XML attribute.
+    def add_set_property(pattern, name_attr, value_attr, type = String)
+      add_rule(SetPropertyRule.new(pattern,name_attr,value_attr,type))
+    end
+
+    # call-seq:
+    #   add_link(pattern) { |parent, child| ... }
+    #
+    # Add a new LinkRule that, when matched, will pass the top two
+    # elements (in order - see below) to the supplied block.
+    def add_link(pattern, &blk)
+      add_rule(LinkRule.new(pattern,&blk))
+    end
+
+    # call-seq:
+    #   add_set_next(pattern, msg, *additional_args)
+    #
+    # Add a new SetNextRule that will send the specified message
+    # to the next-to-top stack object, passing in the top object
+    # as the initial parameter, followed by any additional arguments
+    # supplied to this method.
+    def add_set_next(pattern, msg, *args)
+      add_rule(SetNextRule.new(pattern,msg,*args))
+    end
+
+    # call-seq:
+    #   add_set_top(pattern, msg, *additional_args)
+    #
+    # Add a new SetTopRule that will send the specified message
+    # to the top stack object, passing in the next-to-top object
+    # as the initial parameter, followed by any additional arguments
+    # supplied to this method.
+    def add_set_top(pattern, msg, *args)
+      add_rule(SetTopRule.new(pattern,msg,*args))
+    end
+
+    # call-seq:
+    #   add_call_method(pattern, msg, target_ofs = 0, *args)
+    #   add_call_method(pattern) { |target| ... }
+    #   add_call_method(pattern, nil, target_ofs, *args) { |target, *args| ... }
+    #  
+    # Add a new CallMethodRule that will call the given method
+    # on the object at the given offset from the top of the stack
+    # (positive only, increasing distance from the stack top).
+    def add_call_method(pattern, msg = nil, target_ofs = 0,*args, &blk)
+      add_rule(CallMethodRule.new(pattern,msg,target_ofs,*args,&blk))
+    end
+
+    # call-seq:
+    #   add_call_param(pattern, param_idx, attr_name, type = String)
+    #   add_call_param(pattern, param_idx, stack_index, type = String)
+    #   add_call_param(pattern, param_idx, nil, type = String)
+    #   add_call_param(pattern, param_idx = 0)
+    # 
+    # Add a new CallParamRule that will take it's parameter value
+    # from the specified source, or the current element body if
+    # source is +nil+.
+    def add_call_param(pattern, param_idx = 0, source = nil, type = String)
+      add_rule(CallParamRule.new(pattern,param_idx,source,type))
+    end
+    
+    # call-seq:
+    #   add_call_param_body(pattern, param_idx, type = String)
+    #   add_call_param_body(pattern, param_idx = 0)
+    # 
+    # Add a new CallParamRule that will take it's parameter value
+    # from the current element body. This just calls through to 
+    # +add_call_param+ and is provided for xmldigester compatibility.
+    def add_call_param_body(pattern, param_idx = 0, type = String)
+      add_call_param(pattern,param_idx,nil,type)
+    end
+    
+    # call-seq:
+    #   add_call_param_attribute(pattern, param_idx, attr_name, type = String)
+    #   add_call_param_attribute(pattern, param_idx, attr_name)
+    # 
+    # Add a new CallParamRule that will take it's parameter value
+    # from the named attribute on the current element. This just calls through to 
+    # +add_call_param+ and is provided for xmldigester compatibility.
+    def add_call_param_attribute(pattern, param_idx, attr_name, type = String)
+      add_call_param(pattern, param_idx, attr_name, type)
+    end
+    
+    # call-seq:
+    #   add_call_param_stack(pattern, param_idx, stack_ofs, type = nil)
+    #   add_call_param_stack(pattern, param_idx = 0, stack_ofs = 0)
+    # 
+    # Add a new CallParamRule that will take it's parameter value
+    # from the specified stack element. The stack offset should be a positive
+    # integer indicating the depth of the target object - zero (the default)
+    # indicates the top of the stack.
+    #
+    # This just calls through to +add_call_param+ and is provided for 
+    # xmldigester compatibility.
+    def add_call_param_stack(pattern, param_idx, stack_ofs = 0, type = nil)
+      add_call_param(pattern, param_idx, stack_ofs, type)
+    end   
+
+    private
+    
+    def do_parse
+      @parser.parse
+      f = @first
+      @first = nil
+      f
+    end    
+
+    #### PARSER CALLBACKS ####   
+    # lots of duplicate code here, but factoring it out
+    # made it too slow (mainly dealing with send and varargs)... 
+    def cb_start_document
+      @current_path = ""
+      @rulestack = []
+    end
+
+    def cb_end_document
+      rule = @last_rule
+      begin
+        rule.finish
+      end while rule = rule.prev
+    end
+
+    def cb_start_element(name, attrs)
+      cp = (@current_path << '/' << name)
+      rule = @first_rule
+      begin
+        if File.fnmatch(rule.pattern, cp)
+          rule.begin(nil,name,attrs)
+        end
+      end while rule = rule.next      
+    end
+
+    def cb_end_element(name)
+      rule = @last_rule
+      cp = @current_path
+      begin
+        if File.fnmatch(rule.pattern, cp)
+          rule.end(nil,name)
+        end
+      end while rule = rule.prev      
+      stk = @current_path
+      stk.reverse!.sub!(/^.*?\//,'').reverse!
+    end
+
+    def cb_characters(txt)
+      rule = @first_rule
+      cp = @current_path
+      begin
+        if File.fnmatch(rule.pattern, cp)
+          rule.body(txt)
+        end
+      end while rule = rule.next
+    end
+  end
+  
+  Digestr = Digester
+end