saxy 0.1.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,7 @@
+script: "bundle exec rspec ./spec/"
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - 1.8.7
+  - ree

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Michał Szajbe
+
+MIT License
+
+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/README.md

@@ -0,0 +1,74 @@
+# Saxy
+
+[![Build Status](https://secure.travis-ci.org/monterail/saxy.png)](http://travis-ci.org/monterail/saxy)
+
+Memory-efficient XML parser. Finds object definitions in XML and translates them into Ruby objects.
+
+It uses SAX parser under the hood, which means that it doesn't load the whole XML file into memory. It goes once though it and yields objects along the way.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'saxy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install saxy
+
+## Usage
+
+Assume the XML file:
+
+    <?xml version='1.0' encoding='UTF-8'?>
+    <webstore>
+      <name>Amazon</name>
+      <products>
+        <product>
+          <uid>FFCF177</uid>
+          <name>Kindle</name>
+          <description>The world's best-selling e-reader.</description>
+          <price>$109</price>
+          <images>
+            <thumb>http://amazon.com/kindle_thumb.jpg</thumb>
+            <large>http://amazon.com/kindle.jpg</large>
+          </images>
+        </product>
+      </products>
+    </webstore>
+
+You instantiate the parser by passing path to XML file and object-identyfing tag name as it's arguments.
+
+The following will parse the XML, find product definitions (inside `<product>` and `</product>` tags), build `OpenStruct`s and yield them inside the block:
+
+    Saxy.parse("filename.xml", "product").each do |product|
+      puts product.uid # => FFCF177
+      puts product.name # => "Kindle"
+      puts product.description # => "The world's best-selling e-reader."
+      puts product.price # => "$109"
+
+      # nested objects are build as well
+      puts product.images.thumb # => "http://amazon.com/kindle_thumb.jpg"
+    end
+
+Saxy supports Enumerable, so you can use it's goodies to your comfort without building intermediate arrays:
+
+    Saxy.parse("filename.xml", "product").map do |object|
+      # map OpenStructs to ActiveRecord instances, etc.
+    end
+
+You can also grab an Enumerator for external use (e.g. lazy evaluation, etc.):
+
+    enumerator = Saxy.parse("filename.xml", "product").each
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/saxy.rb

@@ -0,0 +1,18 @@
+require "saxy/element"
+require "saxy/parser"
+require "saxy/parsing_error"
+require "saxy/version"
+
+module Saxy
+  class << self
+    def parse(xml_file, object_tag, &blk)
+      parser = Parser.new(xml_file, object_tag)
+
+      if blk
+        parser.each(blk)
+      else
+        parser.each
+      end
+    end
+  end
+end

data/lib/saxy/element.rb

@@ -0,0 +1,32 @@
+require 'active_support/core_ext/string/inflections'
+require 'ostruct'
+
+module Saxy
+  class Element
+    attr_reader :attributes, :value
+
+    def initialize
+      @attributes = {}
+      @value = nil
+    end
+
+    def set_attribute(name, value)
+      attributes[attribute_name(name)] = value
+    end
+
+    def append_value(string)
+      unless (string = string.strip).empty?
+        @value ||= ""
+        @value << string
+      end
+    end
+
+    def as_object
+      attributes.any? ? OpenStruct.new(attributes) : value
+    end
+
+    def attribute_name(name)
+      name.underscore
+    end
+  end
+end

data/lib/saxy/parser.rb

@@ -0,0 +1,72 @@
+require 'nokogiri'
+
+module Saxy
+  class Parser < Nokogiri::XML::SAX::Document
+    include Enumerable
+
+    # Stack of XML tags built while traversing XML tree
+    attr_reader :tags
+
+    # Stack of elements built while traversing XML tree
+    #
+    # First element is pushed to the stack only after finding the object_tag in
+    # the XML tree.
+    attr_reader :elements
+
+    # Will yield objects inside the callback after they're built
+    attr_reader :callback
+
+    def initialize(xml_file, object_tag)
+      @xml_file, @object_tag = xml_file, object_tag
+      @tags, @elements = [], []
+    end
+
+    def start_element(tag, attributes=[])
+      @tags << tag
+
+      if tag == @object_tag || elements.any?
+        elements << Element.new
+      end
+    end
+
+    def end_element(tag)
+      tags.pop
+      if element = elements.pop
+        object = element.as_object
+
+        if current_element
+          current_element.set_attribute(tag, object)
+        elsif callback
+          callback.call(object)
+        end
+      end
+    end
+
+    def cdata_block(cdata)
+      current_element.append_value(cdata) if current_element
+    end
+
+    def characters(chars)
+      current_element.append_value(chars) if current_element
+    end
+
+    def error(message)
+      raise ParsingError.new(message)
+    end
+
+    def current_element
+      elements.last
+    end
+
+    def each(&blk)
+      if blk
+        @callback = blk
+
+        parser = Nokogiri::XML::SAX::Parser.new(self)
+        parser.parse_file(@xml_file)
+      else
+        (RUBY_VERSION =~ /^1\.8/ ? Enumerable::Enumerator : Enumerator).new(self, :each)
+      end
+    end
+  end
+end

data/lib/saxy/parsing_error.rb

@@ -0,0 +1,4 @@
+module Saxy
+  class ParsingError < ::Exception
+  end
+end

data/lib/saxy/version.rb

@@ -0,0 +1,3 @@
+module Saxy
+  VERSION = "0.1.1"
+end

data/saxy.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/saxy/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Michał Szajbe"]
+  gem.email         = ["michal.szajbe@gmail.com"]
+  gem.description   = %q{Saxy finds object definitions in XML files and translates them into Ruby objects. It uses SAX parser under the hood, which means that it doesn't load the whole XML file into memory. It goes once though it and yields objects along the way.}
+  gem.summary       = %q{Memory-efficient XML parser. Finds object definitions and translates them into Ruby objects.}
+  gem.homepage      = "http://github.com/monterail/saxy"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "saxy"
+  gem.require_paths = ["lib"]
+  gem.version       = Saxy::VERSION
+
+  gem.add_dependency "activesupport"
+  gem.add_dependency "nokogiri"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "ZenTest"
+end

data/spec/fixtures/webstore.xml

@@ -0,0 +1,26 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<webstore>
+  <name>Amazon</name>
+  <products>
+    <product>
+      <uid>FFCF177</uid>
+      <name>Kindle</name>
+      <description>The world's best-selling e-reader.</description>
+      <price>$109</price>
+      <images>
+        <thumb>http://amazon.com/kindle_thumb.jpg</thumb>
+        <large>http://amazon.com/kindle.jpg</large>
+      </images>
+    </product>
+    <product>
+      <uid>YD26NT</uid>
+      <name>Kindle Touch</name>
+      <description>Simple-to-use touchscreen with built-in WIFI.</description>
+      <price>$79</price>
+      <images>
+        <thumb>http://amazon.com/kindle_touch_thumb.jpg</thumb>
+        <large>http://amazon.com/kindle_touch.jpg</large>
+      </images>
+    </product>
+  </products>
+</webstore>

data/spec/fixtures_helper.rb

@@ -0,0 +1,5 @@
+module FixturesHelper
+  def fixture_file(filename)
+    File.expand_path(File.join(File.dirname(__FILE__), 'fixtures', filename))
+  end
+end

data/spec/saxy/element_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe Saxy::Element do
+  let(:element) { Saxy::Element.new }
+
+  it "should not append empty string as value" do
+    element.append_value("")
+    element.value.should be_nil
+  end
+
+  it "should append stripped value" do
+    element.append_value(" foo ")
+    element.append_value(" bar ")
+    element.value.should == "foobar"
+  end
+
+  it "should dump as string when no attributes are set" do
+    element.stub(:value).and_return("foo")
+    element.as_object.should == "foo"
+  end
+
+  it "should dump as object when attributes are set" do
+    element.stub(:attributes).and_return("foo" => 1, "bar" => 2)
+    object = element.as_object
+
+    object.foo.should == 1
+    object.bar.should == 2
+  end
+
+  it "should add attributes under underscored names" do
+    element.set_attribute("FooBar", "baz")
+    element.as_object.foo_bar.should == "baz"
+  end
+end

data/spec/saxy/parser_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+
+describe Saxy::Parser do
+  include FixturesHelper
+
+  let(:parser) { Saxy::Parser.new(fixture_file("webstore.xml"), "product") }
+
+  it "should have empty tag stack" do
+    parser.tags.should == %w( )
+  end
+
+  it "should push/pop tag names on/from tag stack when going down/up the XML tree" do
+    parser.tags.should == %w( )
+
+    parser.start_element('webstore')
+    parser.tags.should == %w( webstore )
+
+    parser.start_element('products')
+    parser.tags.should == %w( webstore products )
+
+    parser.start_element('product')
+    parser.tags.should == %w( webstore products product )
+
+    parser.end_element('product')
+    parser.tags.should == %w( webstore products )
+
+    parser.end_element('products')
+    parser.tags.should == %w( webstore )
+
+    parser.end_element('webstore')
+    parser.tags.should == %w( )
+  end
+
+  context "when detecting object tag opening" do
+    before do
+      parser.start_element("product")
+    end
+
+    it "should add new element to stack" do
+      parser.elements.size.should == 1
+    end
+  end
+
+  context "when detecting other tag opening" do
+    before do
+      parser.start_element("other")
+    end
+
+    it "should not add new element to stack" do
+      parser.elements.should be_empty
+    end
+  end
+
+  context "with non-empty element stack" do
+    before do
+      parser.start_element("product")
+      parser.elements.should_not be_empty
+    end
+
+    context "when detecting object tag opening" do
+      before do
+        parser.start_element("product")
+      end
+
+      it "should add new element to stack" do
+        parser.elements.size.should == 2
+      end
+    end
+
+    context "when detecting other tag opening" do
+      before do
+        parser.start_element("other")
+      end
+
+      it "should not add new element to stack" do
+        parser.elements.size.should == 2
+      end
+    end
+
+    context "when detecting any tag closing" do
+      before do
+        parser.end_element("any")
+      end
+
+      it "should pop element from stack" do
+        parser.elements.should be_empty
+      end
+    end
+
+    context "with callback defined" do
+      before do
+        @callback = lambda { |object| object }
+        parser.stub(:callback).and_return(@callback)
+      end
+
+      it "should yield the object inside the callback after detecting object tag closing" do
+        @callback.should_receive(:call).with(parser.current_element.as_object)
+        parser.end_element("product")
+      end
+
+      it "should not yield the object inside the callback after detecting other tag closing" do
+        parser.start_element("other")
+        @callback.should_not_receive(:call)
+        parser.end_element("other")
+      end
+    end
+
+    it "should append cdata block's contents to top element's value when detecting cdata block" do
+      parser.current_element.should_receive(:append_value).with("foo")
+      parser.cdata_block("foo")
+    end
+
+    it "should append characters to top element's value when detecting characters block" do
+      parser.current_element.should_receive(:append_value).with("foo")
+      parser.current_element.should_receive(:append_value).with("bar")
+      parser.characters("foo")
+      parser.characters("bar")
+    end
+
+    it "should set element's attribute after processing tags" do
+      element = parser.current_element
+
+      element.should_receive(:set_attribute).with("foo", "bar")
+
+      parser.start_element("foo")
+      parser.characters("bar")
+      parser.end_element("foo")
+    end
+  end
+
+  it "should raise Saxy::ParsingError on error" do
+    lambda { parser.error("Error message.") }.should raise_error(Saxy::ParsingError, "Error message.")
+  end
+
+  it "should return Enumerator when calling #each without a block", :unless => RUBY_1_8 do
+    parser.each.should be_instance_of Enumerator
+  end
+
+  it "should return Enumerator when calling #each without a block", :if => RUBY_1_8 do
+    parser.each.should be_instance_of Enumerable::Enumerator
+  end
+end

data/spec/saxy_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe Saxy do
+  include FixturesHelper
+
+  it "should find object definitions in XML file and yield them as Ruby objects" do
+    products = Saxy.parse(fixture_file("webstore.xml"), "product").inject([]) do |arr, product|
+      arr << product
+      arr
+    end
+
+    products[0].uid.should == "FFCF177"
+    products[0].name.should == "Kindle"
+    products[0].description.should == "The world's best-selling e-reader."
+    products[0].price.should == "$109"
+    products[0].images.thumb.should == "http://amazon.com/kindle_thumb.jpg"
+    products[0].images.large.should == "http://amazon.com/kindle.jpg"
+
+    products[1].uid.should == "YD26NT"
+    products[1].name.should == "Kindle Touch"
+    products[1].description.should == "Simple-to-use touchscreen with built-in WIFI."
+    products[1].price.should == "$79"
+    products[1].images.thumb.should == "http://amazon.com/kindle_touch_thumb.jpg"
+    products[1].images.large.should == "http://amazon.com/kindle_touch.jpg"
+  end
+
+  it "should return Enumerator when calling #parse without a block", :unless => RUBY_1_8 do
+    Saxy.parse(fixture_file("webstore.xml"), "product").each.should be_instance_of Enumerator
+  end
+
+  it "should return Enumerator when calling #parse without a block", :if => RUBY_1_8 do
+    Saxy.parse(fixture_file("webstore.xml"), "product").each.should be_instance_of Enumerable::Enumerator
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'saxy'
+
+require 'fixtures_helper'
+
+RUBY_1_8 = (RUBY_VERSION =~ /^1\.8/)

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification 
+name: saxy
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.1
+platform: ruby
+authors: 
+- "Micha\xC5\x82 Szajbe"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-08-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: ZenTest
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Saxy finds object definitions in XML files and translates them into Ruby objects. It uses SAX parser under the hood, which means that it doesn't load the whole XML file into memory. It goes once though it and yields objects along the way.
+email: 
+- michal.szajbe@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/saxy.rb
+- lib/saxy/element.rb
+- lib/saxy/parser.rb
+- lib/saxy/parsing_error.rb
+- lib/saxy/version.rb
+- saxy.gemspec
+- spec/fixtures/webstore.xml
+- spec/fixtures_helper.rb
+- spec/saxy/element_spec.rb
+- spec/saxy/parser_spec.rb
+- spec/saxy_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/monterail/saxy
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Memory-efficient XML parser. Finds object definitions and translates them into Ruby objects.
+test_files: 
+- spec/fixtures/webstore.xml
+- spec/fixtures_helper.rb
+- spec/saxy/element_spec.rb
+- spec/saxy/parser_spec.rb
+- spec/saxy_spec.rb
+- spec/spec_helper.rb