xml_stream_parser 0.3.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/History.txt

@@ -0,0 +1,7 @@
+=== 0.1.0 / 2009-06-10
+
+* initial release
+
+=== 0.2.0 / 2009-06-19
+
+* more dsl like syntax

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 mccraigmccraig
+
+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/Manifest.txt

@@ -0,0 +1,9 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+init.rb
+lib/instance_exec.rb
+lib/xml_stream_parser.rb
+spec/xml_stream_parser_spec.rb
+xml_stream_parser.gemspec

data/README.rdoc

@@ -0,0 +1,17 @@
+= xml_stream_parser
+
+Description goes here.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 mccraigmccraig. See LICENSE for details.

data/README.txt

@@ -0,0 +1,85 @@
+= xml_stream_parser
+
+this code was developed by trampoline systems [ http://trampolinesystems.com ]
+as part of its sonar platform and released under a BSD licence for community use
+
+http://www.github.com/mccraigmccraig/xml_stream_parser
+
+== DESCRIPTION:
+
+a basic library for pull parsing of large xml documents
+
+== FEATURES:
+
+ - pull parsing of large xml documents with no dom construction
+ - provides simple operations for constructing higher level parsers
+
+== PROBLEMS:
+
+ - it's very basic
+ - no validation
+
+== SYNOPSIS:
+
+require 'rubygems'
+require 'xml_stream_parser'
+
+# parse xml stream data, possibly never ending, and do things with it
+
+doc = <<-EOF
+<people>
+  <person name="alice">likes cheese</person>
+  <person name="bob">likes music</person>
+  <person name="charles">likes alice</person>
+</people>
+EOF
+
+# can be parsed with
+
+people = {}
+XmlStreamParser.new.parse_dsl(doc) do
+  element "people" do |name,attrs|
+    elements "person" do |name, attrs|
+      people[attrs["name"]] = text
+    end
+  end
+end
+
+== REQUIREMENTS:
+
+Ruby or JRuby
+
+== INSTALL:
+
+sudo gem sources -a http://gems.github.com
+sudo gem install mccraigmccraig-xml_stream_parser
+
+== LICENSE:
+
+(The BSD License)
+
+Copyright (c) 2009, Trampoline Systems Ltd, http://trampolinesystems.com/
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+  * Neither the name of the <ORGANIZATION> nor the names of its contributors may
+    be used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "xml_stream_parser"
+    gem.summary = %Q{simple xml stream parser for ruby}
+    gem.description = %Q{easily parse xml documents of any size with ruby}
+    gem.email = "craig@trampolinesystems.com"
+    gem.homepage = "http://github.com/mccraigmccraig/xml_stream_parser"
+    gem.authors = ["mccraigmccraig"]
+    gem.add_development_dependency "rspec", ">= 1.2.8"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "xml_stream_parser #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/init.rb

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require File.join( File.dirname(__FILE__), "lib", "xml_stream_parser" )

data/lib/instance_exec.rb

@@ -0,0 +1,34 @@
+# defines Object.instance_exec to permit call of a Proc with params
+# in the context of an instance : instance.instance_exec( foo, bar, &proc )
+# taken from rails 2.2
+#
+class Object
+  unless defined? instance_exec # 1.9
+    module InstanceExecMethods #:nodoc:
+      @mutex = Mutex.new
+      class << self
+        attr_reader :mutex
+      end
+    end
+    include InstanceExecMethods
+
+    # Evaluate the block with the given arguments within the context of
+    # this object, so self is set to the method receiver.
+    #
+    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
+    def instance_exec(*args, &block)
+      method_name = InstanceExecMethods.mutex.synchronize do
+        n = 0
+        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
+        InstanceExecMethods.module_eval { define_method(method_name, &block) }
+        method_name
+      end
+
+      begin
+        send(method_name, *args)
+      ensure
+        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+      end
+    end
+  end
+end

data/lib/xml_stream_parser.rb

@@ -0,0 +1,203 @@
+require 'stringio'
+require 'rexml/document'
+require 'rexml/parsers/pullparser'
+require File.join( File.dirname(__FILE__), 'instance_exec')
+
+module REXML
+  module Parsers
+    class PullEvent
+      # PullEvent is missing the end_document? method, even tho 
+      # the BaseParser produces the event
+      def end_document?
+        @contents[0] == :end_document
+      end
+    end
+  end
+end
+
+class XmlStreamParser
+
+  VERSION = "0.2.0"
+
+  class Sentinel
+    def to_s
+      self.class.to_s
+    end
+  end
+
+  class Nothing < Sentinel
+  end
+
+  class EndContext < Sentinel
+  end
+
+  module Sentinels
+    NOTHING = Nothing.new
+    END_CONTEXT = EndContext.new
+  end
+
+  include Sentinels
+
+  # the REXML::Parsers::PullParser used internally
+  attr_reader :pull_parser
+  attr_reader :dsl
+
+  # parse retaining block context... permitting
+  # the parse to easily be split over multiple methods
+  def parse(data, &block)
+    parse_dsl(data, false, &block)
+  end
+
+  # parse with optional dsl mode
+  # if dsl is true [ default ] then the block will be instance_exec'd in
+  # the context of the parser, if dsl is false the block will be called
+  # retaining it's current context
+  def parse_dsl(data, dsl=true, &block)
+    io = case data
+         when IO
+           data
+         when StringIO
+           data
+         when String
+           StringIO.new(data)
+         end
+
+    @pull_parser = REXML::Parsers::PullParser.new( io )
+    @dsl = dsl
+    if self.dsl
+      self.instance_exec(&block)
+    else
+      block.call(self)
+    end
+  ensure
+    @pull_parser = nil
+  end
+
+  # find an element with name in element_names : inter-element whitespace is ignored
+  # - encountering end_element terminates and returns END_CONTEXT, leaving parser on end_element
+  # - encountering end_document terminates and returns END_CONTEXT
+  # - encountering start_element for an element not in element_names NOTHING, parser on start_element
+  # - encountering start_element for an element in element_names returns element name, parser on start_element
+  def find_element( element_names )
+    element_names = [ *element_names ]
+
+    while( true )
+      e = @pull_parser.peek
+      if e.start_element?
+        if element_names.include?( e[0] )
+          return e[0]
+        else
+          return NOTHING
+        end
+      elsif e.end_element?
+        return END_CONTEXT
+      elsif e.end_document?
+        return END_CONTEXT
+      elsif e.text? 
+        # ignore whitespace between elements
+        raise "unexpected text content: #{e.inspect}" if e[0] !~ /[[:space:]]/
+        @pull_parser.pull
+      end
+    end
+  end
+
+  # parse and throw away content until we escape the current context, either
+  # through end_element, or end_document
+  def discard()
+    element_stack = []
+
+    while(true)
+      e = @pull_parser.peek
+      name = e[0]
+      if e.start_element?
+        element_stack.push(name)
+      elsif e.end_element?
+        return nil if element_stack.size == 0
+        raise "mismatched end_element. expected </#{element_stack.last}>, got: #{e.inspect}" if name != element_stack.last
+        element_stack.pop
+      elsif e.end_document?
+        return nil if element_stack.size ==0
+        raise "mismatched end_element. expected </#{element_stack.last}>, got: #{e.inspect}"
+      end
+      @pull_parser.pull
+    end
+  end
+
+  # consume an element
+  # - if optional is false the element must be present
+  # - if optional is true and the element is not present then NOTHING/END_CONTEXT
+  #   will be returned
+  # - consumes start_element, calls block on content, consumes end_element
+  def element( element_names, optional=false, &block )
+    element_names = [ *element_names ]
+
+    f = find_element(element_names)
+    e = @pull_parser.peek
+
+    if f.is_a? Sentinel
+      if optional
+        return f
+      else
+        raise "expected start element: <#{element_names.join('|')}, got: #{e.inspect}>"
+      end
+    end
+
+    e = @pull_parser.pull # consume the start tag
+    name = e[0]
+    attrs = e[1]
+    
+    # block should consume all element content, and leave parser on end_element, or
+    # whitespace before it
+    err=false
+    begin
+      if self.dsl
+        v = self.instance_exec(name, attrs, &block)
+      else
+        v = block.call(name,attrs)
+      end
+      return v if ! v.is_a? Sentinel # do not propagate Sentinels. they confuse callers
+    rescue
+      err=true  # note that we are erroring, so as not to mask the exception from ensure block
+      raise
+    ensure  
+      if !err # if return was called in the block, ensure we consume the end_element
+        e = @pull_parser.pull
+        e = @pull_parser.pull if e.text? && e[0] =~ /[[:space:]]/
+        raise "expected end tag: #{name}, got: #{e.inspect}" if ! e.end_element? || e[0] != name
+      end
+    end
+  end
+
+  # find and consume elements, calling block on each one found
+  # return result of last find : NOTHING or END_CONTEXT sentinel
+  def elements( element_names, &block )
+    while true
+      break if element(element_names, true, &block).is_a? Sentinel
+    end
+
+    return nil
+  end
+
+  # consume text element
+  # returns the text, or nil if none
+  def text( &block )
+    e = @pull_parser.peek
+    raise "expected text node, got #{e.inspect}" if ! e.text? && ! e.end_element?
+    text = if e.text?
+             @pull_parser.pull
+             e[0]
+           else
+             nil
+           end
+    if block
+      if self.dsl
+        text = self.instance_exec( text , &block)
+      else
+        text = block.call(text)
+      end
+    end
+    text
+  end
+
+end
+

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'xml_stream_parser'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

data/spec/xml_stream_parser_spec.rb

@@ -0,0 +1,414 @@
+#!/usr/bin/env spec
+
+require 'rubygems'
+require 'spec'
+require 'set'
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe XmlStreamParser do
+  it "should work on a StringIO" do
+    io = StringIO.new( "<foo/>")
+    XmlStreamParser.new.parse_dsl(io) do
+      element("foo") do |name,attrs|
+        name.should ==("foo")
+        name
+      end
+    end.should ==("foo")
+  end
+
+  it "should parse a simple one element document" do
+    XmlStreamParser.new.parse_dsl( "<foo></foo>" ) do
+      called = false
+      element("foo") { |name,attrs|
+        called = true
+        name.should ==("foo")
+        attrs.should ==({})
+      }
+      called.should ==(true)
+    end
+  end
+  
+  describe "find_element" do
+    
+    it "should skip whitespace to find an element" do
+      XmlStreamParser.new.parse_dsl( "   \n\n\n<foo></foo>") do
+        name = find_element("foo")
+        name.should ==("foo")
+        e = pull_parser.pull
+        e.start_element?.should ==(true)
+        e[0].should == "foo"
+        e[1].should == {}
+      end
+    end
+
+    it "should return NOTHING on unexpected elements" do
+      XmlStreamParser.new.parse_dsl( "<foo></foo>") do
+        find_element("bar")
+      end.should ==(XmlStreamParser::NOTHING)
+    end
+
+    it "should match one of multiple elements" do
+      XmlStreamParser.new.parse_dsl( "<foo></foo>" ) do
+        find_element( ["bar","foo" ] )
+      end.should ==("foo")
+    end
+
+
+    it "should return END_CONTEXT if element context terminates" do
+      called = false
+      XmlStreamParser.new.parse_dsl( '<foo></foo>' ) do
+        element("foo") do |name,attrs|
+          name.should ==("foo")
+
+          n = find_element("bar")
+          n.should ==(XmlStreamParser::END_CONTEXT)
+
+          e = pull_parser.peek
+          e.end_element?.should ==(true)
+          e[0].should ==("foo")
+
+          called = true
+        end
+      end
+      called.should ==(true)
+    end
+
+    it "should return END_CONTEXT if document ends" do
+      XmlStreamParser.new.parse_dsl( '<foo></foo>') do
+        element("foo") do |name,attrs|
+        end
+        f = find_element("bar")
+        f.should ==( XmlStreamParser::END_CONTEXT )
+      end
+    end
+  end
+
+  describe "discard" do
+    
+    it "should discard text content of an element" do
+      XmlStreamParser.new.parse_dsl( '<foo>blah blah blah</foo>') do
+        element("foo") do |name,attrs|
+          discard
+          "foo"
+        end
+      end.should ==("foo")
+    end
+
+    it "should discard element content of an element" do
+      XmlStreamParser.new.parse_dsl( '<foo><bar/><foobar></foobar></foo>') do
+        element("foo") do |name,attrs|
+          discard
+          "foo"
+        end
+      end.should ==("foo")
+    end
+
+    it "should discard mixed content of an element" do
+      XmlStreamParser.new.parse_dsl( '<foo><bar/>blah blah<foobar></foobar> blah blah </foo>') do
+        element("foo") do |name,attrs|
+          discard
+          "foo"
+        end
+      end.should ==("foo")
+    end
+
+  end
+
+  describe "element" do
+
+    it "should return NOTHING if optional and element not found" do
+      XmlStreamParser.new.parse_dsl( '<foo><foofoo/></foo>' ) do
+        element("foo") do |name,attrs|
+          element("bar",true) do |name,attrs|
+            "bar"
+          end.should ==(XmlStreamParser::NOTHING)
+          element("foofoo") do |name,attrs|
+            "foofoo"
+          end
+        end
+      end.should ==("foofoo" )
+    end
+
+    it "should return END_CONTEXT if optional and context ends" do
+      XmlStreamParser.new.parse_dsl( '<foo></foo>' ) do
+        element("foo") do |name,attrs|
+          element("bar",true) do |name,attrs|
+            "bar"
+          end.should ==(XmlStreamParser::END_CONTEXT)
+          "foofoo"
+        end
+      end.should ==("foofoo")
+    end
+
+    it "should not propagate sentinel values up the call hierarchy" do
+      called = false
+      XmlStreamParser.new.parse_dsl( '<foo></foo>' ) do
+        element("foo") do |name,attrs|
+          called = true
+          element("bar",true) do |name,attrs|
+            "bar"
+          end.should ==(XmlStreamParser::END_CONTEXT)
+        end
+      end.should_not ==(XmlStreamParser::END_CONTEXT)
+      called.should == (true)
+    end
+
+    class Foo
+      def self.parse_bar( p )
+        p.element("bar") do |name,attrs|
+          return "barbar"
+        end
+      end
+    end
+
+    it "should consume the end tag even if block calls return" do
+      XmlStreamParser.new.parse_dsl( '<foo><bar/></foo>') do
+        element( "foo" ) do |name, attrs|
+          Foo.parse_bar( self )
+        end
+      end.should ==("barbar" )
+    end
+
+    it "should consume the end tag even if block calls break" do
+      XmlStreamParser.new.parse_dsl( '<foo><bar/></foo>') do
+        element( "foo" ) do |name, attrs|
+          element( "bar" ) do |name, attrs|
+            break
+          end
+          "foo"
+        end
+      end.should ==( "foo" )
+    end
+
+    it "should raise on premature document termination" do
+      lambda {
+        XmlStreamParser.new.parse_dsl( '<foo>' ) do
+          element("foo") do |name,attrs|
+            element("bar",false) do |name,attrs|
+              "bar"
+            end
+          end
+        end
+      }.should raise_error(RuntimeError)
+    end
+
+    it "should raise on premature context termination" do
+      lambda {
+        XmlStreamParser.new.parse_dsl( '<foo></foo>' ) do
+          element("foo") do |name,attrs|
+            element("bar",false) do |name,attrs|
+              "bar"
+            end
+          end
+        end
+      }.should raise_error(RuntimeError)
+    end
+
+    it "should consume an element, giving name and attributes to the provided block and returning block result" do
+      XmlStreamParser.new.parse_dsl( '<foo a="one" b="two"></foo>') do
+        element( "foo" ) do |name, attrs|
+          name.should ==("foo")
+          attrs.should ==({ "a"=>"one", "b"=>"two" })
+          "blockresult"
+        end.should ==("blockresult")
+        e = pull_parser.peek
+        e.end_document?.should ==(true)
+        "foofoo"
+      end.should ==("foofoo")
+    end
+
+    it "should consume one of many element names, giving name and attrs to block and returning block result" do
+      XmlStreamParser.new.parse_dsl( '<foo a="one" b="two"></foo>') do
+        element( ["bar","foo"] ) do |name, attrs|
+          name.should ==("foo")
+          attrs.should ==({ "a"=>"one", "b"=>"two" })
+          "blockresult"
+        end
+      end.should ==("blockresult")
+    end
+
+    it "should ignore whitespace inside element" do
+      XmlStreamParser.new.parse_dsl( '<foo a="one" b="two">  \n  \n</foo>') do
+        element( "foo" ) do |name, attrs|
+          name.should ==("foo")
+          attrs.should ==({ "a"=>"one", "b"=>"two" })
+          "blockresult"
+        end.should ==("blockresult")
+        e = pull_parser.peek
+        e.end_document?.should ==(true)
+        "foofoo"
+      end.should ==("foofoo")
+    end
+
+  end
+
+  describe "text" do
+    it "should consume an element with text content and give it's name, attrs, text to the block and return the block result" do
+      XmlStreamParser.new.parse_dsl( '<foo a="bar">hello mum</foo>') do
+        element( "foo" ) do |name, attrs|
+          name.should ==("foo")
+          attrs.should ==({ "a"=>"bar" })
+          text
+        end
+      end.should ==("hello mum")
+    end
+
+    it "should raise if the element contains element content" do
+      lambda {
+        XmlStreamParser.new.parse_dsl( '<foo a="bar"><bar/></foo>') do
+          element("foo") do |name,attrs|
+            text()
+          end
+        end
+      }.should raise_error(RuntimeError)
+    end
+
+    it "should raise if the element contains mixed content" do
+      lambda {
+        XmlStreamParser.new.parse_dsl( '<foo a="bar">some <bar/> text</foo>') do
+          element("foo") do |name,attrs|
+            text()
+          end
+        end
+      }.should raise_error(RuntimeError)
+    end
+  end
+
+  describe "elements" do
+    it "should consume multiple elements" do
+      el_counts = Hash.new(0)
+      XmlStreamParser.new.parse_dsl( '<foo><bar/><bar/><foobar/></foo>') do
+        element("foo") do |name,attrs|
+          elements( ["bar","foobar"] ) do |name,attrs|
+            el_counts[name] += 1
+          end
+        end
+      end
+      el_counts.should ==({ "bar"=>2, "foobar"=>1 })
+    end
+
+    it "should not complain if there are no matching elements" do
+      XmlStreamParser.new.parse_dsl( '<foo></foo>') do
+        element("foo") do |name,attrs|
+          elements( ["bar","foobar"] ) do |name,attrs|
+            el_counts[name] += 1
+          end
+        end
+      end
+    end
+    
+  end
+
+  describe "non-DSL mode" do
+    it "should pass the parser to the parse() block" do
+      def foo()
+        "foo"
+      end
+
+      XmlStreamParser.new.parse( '<foo></foo>') do |p|
+        p.should_not ==(nil)
+        foo()
+      end.should =="foo"
+    end
+
+    it "should retain contenxt for element blocks" do
+      def foo()
+        "foo"
+      end
+      XmlStreamParser.new.parse( '<foo></foo>') do |p|
+        p.element('foo') do |name,attrs|
+          name.should =='foo'
+          attrs.should == {}
+          foo()
+        end
+      end.should =="foo"
+    end
+
+    it "should retain context for text blocks" do
+      def bar()
+        "barbar"
+      end
+      XmlStreamParser.new.parse( '<foo>bar</foo>') do |p|
+        p.element('foo') do |name,attrs|
+          p.text{ |t| t.should =='bar' ; t }
+          bar()
+        end
+      end.should =='barbar'
+    end
+  end
+
+  describe "some more complex examples" do
+
+    it "should parse a list of people" do
+      doc = <<-EOF
+<people>
+  <person name="alice">likes cheese</person>
+  <person name="bob">likes music</person>
+  <person name="charles">likes alice</person>
+</people>
+EOF
+
+      people = {}
+
+      XmlStreamParser.new.parse_dsl(doc) do
+        element("people") do |name,attrs|
+          elements("person") do |name, attrs|
+            people[attrs["name"]] = text
+          end
+        end
+      end
+
+      people.should ==({ "alice"=>"likes cheese",
+                      "bob"=>"likes music",
+                      "charles"=>"likes alice"})
+    end
+
+    it "should parse a list of people and their friends" do
+      doc = <<-EOF
+<people>
+  <person name="alice">
+    <friend name="bob"/>
+    <likes>cheese</likes>
+    <friend name="charles"/>
+  </person>
+  <person name="bob">
+    <friend name="alice"/>
+    <likes>wolf dogs</likes>
+  </person>
+  <person name="charles">
+    <friend name="alice"/>
+    <likes>bach</likes>
+  </person>
+</people>
+EOF
+      
+      people = Hash.new{ |h,k| h[k] = {:friends=>Set.new([]), :likes=>Set.new([]) } }
+
+      XmlStreamParser.new.parse_dsl(doc) do
+        element("people") do |name,attrs|
+          elements("person") do |name, attrs|
+            person_name = attrs["name"]
+            people[person_name]
+
+            elements(["friend","likes"]) do |name,attrs|
+              case name
+              when "friend" then
+                people[person_name][:friends] << attrs["name"]
+              when "likes" then
+                people[person_name][:likes] << text
+              end
+            end
+          end
+        end
+      end
+
+      people.should ==( { 
+                       "alice"=>{ :friends=>Set.new(["bob","charles"]), :likes=>Set.new(["cheese"])},
+                       "bob"=>{ :friends=>Set.new(["alice"]), :likes=>Set.new(["wolf dogs"])},
+                       "charles"=>{ :friends=>Set.new(["alice"]), :likes=>Set.new(["bach"])}
+                     }) 
+
+    end
+
+  end
+end

data/xml_stream_parser.gemspec

@@ -0,0 +1,61 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{xml_stream_parser}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["mccraigmccraig"]
+  s.date = %q{2010-06-24}
+  s.description = %q{easily parse xml documents of any size with ruby}
+  s.email = %q{craig@trampolinesystems.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc",
+     "README.txt"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "Manifest.txt",
+     "README.rdoc",
+     "README.txt",
+     "Rakefile",
+     "VERSION",
+     "init.rb",
+     "lib/instance_exec.rb",
+     "lib/xml_stream_parser.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/xml_stream_parser_spec.rb",
+     "xml_stream_parser.gemspec"
+  ]
+  s.homepage = %q{http://github.com/mccraigmccraig/xml_stream_parser}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{simple xml stream parser for ruby}
+  s.test_files = [
+    "spec/spec_helper.rb",
+     "spec/xml_stream_parser_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.8"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.8"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.8"])
+  end
+end
+

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification 
+name: xml_stream_parser
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- mccraigmccraig
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-24 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 8
+        version: 1.2.8
+  type: :development
+  version_requirements: *id001
+description: easily parse xml documents of any size with ruby
+email: craig@trampolinesystems.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+- README.txt
+files: 
+- .document
+- .gitignore
+- History.txt
+- LICENSE
+- Manifest.txt
+- README.rdoc
+- README.txt
+- Rakefile
+- VERSION
+- init.rb
+- lib/instance_exec.rb
+- lib/xml_stream_parser.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/xml_stream_parser_spec.rb
+- xml_stream_parser.gemspec
+has_rdoc: true
+homepage: http://github.com/mccraigmccraig/xml_stream_parser
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: simple xml stream parser for ruby
+test_files: 
+- spec/spec_helper.rb
+- spec/xml_stream_parser_spec.rb