badgerhash 0.0.1

data/README.md

@@ -0,0 +1,48 @@
+# Badgerhash
+[![Build Status](https://travis-ci.org/gfmurphy/badgerhash.svg?branch=master)](https://travis-ci.org/gfmurphy/badgerhash)
+[![Code Climate](https://codeclimate.com/github/gfmurphy/badgerhash.png)](https://codeclimate.com/github/gfmurphy/badgerhash)
+
+Convert XML to a Ruby Hash using the BadgerFish convention: http://badgerfish.ning.com/
+
+The resulting Hash can be easily converted to JSON using a JSON library.
+
+The reference implementation of the generators use REXML for parsing the given
+XML. REXML is included in the Ruby Standard Library so no depencies are
+introduced. Nevertheless, this library provides interfaces that allow using
+alternate parsers if performance is a concern.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'badgerhash'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install badgerhash
+
+## Usage
+
+### Generating a BadgerFish Hash Using a Stream Parser
+
+```ruby
+require "badgerhash"
+require "stringio"
+
+xml = StringIO.new("<alice>bob</alice>")
+xml_stream =  Badgerhash::XmlStream.create(xml)
+
+puts xml_stream.to_badgerfish.inspect
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/gfmurphy/badgerhash/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "yard"
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end

data/badgerhash.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'badgerhash/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "badgerhash"
+  spec.version       = Badgerhash::VERSION
+  spec.authors       = ["George F. Murphy"]
+  spec.email         = ["gmurphy@epublishing.com"]
+  spec.summary       = "Parse XML as IO into hash using badgerfish convention."
+  spec.homepage      = "http://github.com/gfmurphy/badgerhash"
+  spec.license       = "GNU LGPL"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 1.9.3"
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.1.1"
+end

data/lib/badgerhash.rb

@@ -0,0 +1,31 @@
+require "badgerhash/handlers/sax_handler"
+require "badgerhash/parsers/rexml"
+require "badgerhash/version"
+require "badgerhash/xml_stream"
+
+# Convert XML to Ruby Hash using Badgerfish convention: http://badgerfish.ning.com/
+# @api public
+module Badgerhash
+  # Class of the default sax parser implementation
+  DEFAULT_SAX_PARSER = Parsers::REXML::SaxDocument
+
+  # Set the sax parser for the module
+  #
+  # @param parser [Class] a parser that supports the required interface
+  # @see Parsers::REXML::SaxDocument for the reference implementation
+  # @example
+  #   Badgerhash.sax_parser = MyFastParser => MyFastParser
+  # @return [Class] the new parser class
+  def self.sax_parser=(parser)
+    @sax_parser = parser
+  end
+
+  # The current sax parser implementation
+  #
+  # @example
+  #   Badgerhash.sax_parser => Parsers::REXML::SaxDocument
+  # @return [Class] the current sax parser implementation
+  def self.sax_parser
+    @sax_parser || DEFAULT_SAX_PARSER
+  end
+end

data/lib/badgerhash/handlers/sax_handler.rb

@@ -0,0 +1,95 @@
+module Badgerhash
+  module Handlers
+    # SaxHandler that is passed to a sax parser implementation
+    # @api public
+    class SaxHandler
+      attr_reader :node
+
+      # Initialize the SaxHandler
+      #
+      # @param node [Hash] Used to preinitialzie the internal node.
+      # @api private
+      def initialize(node={})
+        @parents = []
+        @node = node
+      end
+
+      # Sends message to handler that a new element was encountered in
+      # stream
+      #
+      # @param name [String] the name of the new element
+      #
+      # @example
+      #  handler.start_element "foo" => handler
+      # @return [SaxHandler]
+      def start_element(name)
+        name = name.to_s
+        element = node_namespaces
+
+        @node[name] = case @node[name]
+                      when nil
+                        element
+                      when Hash
+                        [@node[name], element]
+                      else
+                        @node[name] << element
+                      end
+
+        @parents << @node
+        @node = element
+        self
+      end
+
+      # Sends message to handler that an attribute was encountered in
+      # the stream
+      #
+      # @param name [String] the name of the attribute
+      # @param value [String] the attribute's value
+      # @example
+      #   handler.attr "foo", "bar"  => handler
+      # @return [SaxHandler]
+      def attr(name, value)
+        if name =~ /^xmlns(:?(.*))/i
+          key = $2.to_s.length > 0 ? $2 : "$"
+          (@node["@xmlns"] ||= {})[key] = value
+        else
+          @node["@#{name}"] = value
+        end
+        self
+      end
+
+      # Sends a message to handler that a text node or cdata section
+      # was found in the stream
+      #
+      # @param value [String] the text encountered
+      # @example
+      #   handler.text "this is my text node" => handler
+      # @return [SaxHandler]
+      def text(value)
+        value = value.to_s.strip
+        @node["$"] = value unless value.empty?
+        self
+      end
+
+      alias :cdata :text
+
+      # Sends a message to the handler that the end of an element has
+      # been found in the stream
+      #
+      # @param name [String] the name of the element
+      # @example
+      #   handler.end_element "foo" => handler
+      # @return [SaxHandler]
+      def end_element(name)
+        @node = @parents.pop || {}
+        self
+      end
+
+      private
+      def node_namespaces
+        ns = @node.fetch("@xmlns", {})
+        ns.size > 0 ? { "@xmlns" => ns } : {}
+      end
+    end
+  end
+end

data/lib/badgerhash/parsers/rexml.rb

@@ -0,0 +1,49 @@
+require "forwardable"
+require "rexml/document"
+require "rexml/streamlistener"
+
+module Badgerhash
+  module Parsers
+    module REXML
+      # SaxDocument provides an implmentation of the required
+      # public interface for a parser that is to be used when parsing
+      # an XmlStream. An implementation is required to provide a parse method
+      # that accepts a Badgerhash::Handler::SaxHandler and an IO object.
+      # When parsing the given IO stream, it must send messages to the handler
+      # in order to build the correct Hash. This also serves as a reference
+      # implementation for other sax parsers.
+      #
+      # @api private
+      class SaxDocument
+        include ::REXML::StreamListener
+        extend Forwardable
+
+        def_delegators :@handler, :text, :cdata
+        def_delegator  :@handler, :end_element, :tag_end
+
+        # Parse the given stream and update the handler.
+        #
+        # @param handler [Badgerhash::Handler::SaxHandler] parsing handler
+        # @param io [IO] the XML to be parsed.
+        # @return void
+        def self.parse(handler, io)
+          ::REXML::Document.parse_stream(io, new(handler))
+        end
+
+        # Initialize the parser.
+        #
+        # @param handler [Badgerhash::Handlers::SaxHandler]
+        def initialize(handler)
+          @handler = handler
+        end
+
+        def tag_start(name, attributes=[])
+          @handler.start_element name
+          Array(attributes).each do |attr|
+            @handler.attr(*attr)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badgerhash/version.rb

@@ -0,0 +1,5 @@
+module Badgerhash
+  # The String containing the current version of the library.
+  # @api public
+  VERSION = "0.0.1"
+end

data/lib/badgerhash/xml_stream.rb

@@ -0,0 +1,40 @@
+module Badgerhash
+  # Converts XML as IO to a Badgerfish Hash using a stream parser
+  class XmlStream
+    # Create a properly initialized Badgerhash::XmlStream object
+    #
+    # @param io [IO] an object containing the XML to be parsed
+    # @example
+    #   io = StringIO.new("<alice>bob</alice>")
+    #   Badgerhash::XmlStream.create(io)
+    # @return [Badgerhash::XmlStream] the XmlStream
+    # @api public
+    def self.create(io)
+      new(Handlers::SaxHandler.new, Badgerhash.sax_parser, io)
+    end
+
+    # The Badgerfish representation of the XML
+    #
+    # @example
+    #  io = StringIO.new("<alice>bob</alice>")
+    #  Badgerhash::XmlStream.create(io).to_badgerfish => {"alice" => {"$" => "bob" }}
+    # @return [Hash] the Badgerfish hash
+    # @api public
+    def to_badgerfish
+      @parser.parse(@handler, @io)
+      @handler.node.dup
+    end
+
+    # Initialize an XmlStream object.
+    #
+    # @param handler [Badgerhash::Handlers::SaxHandler] the handler
+    # @param parser  [Class] a parser conforming to the required interface.
+    # @param io [IO] object containing the XML to be parsed.
+    # @api private
+    def initialize(handler, parser, io)
+      @handler = handler
+      @parser  = parser
+      @io      = io
+    end
+  end
+end

data/spec/badgerhash/handlers/sax_handler_spec.rb

@@ -0,0 +1,134 @@
+require File.expand_path "../../../spec_helper.rb", __FILE__
+
+module Badgerhash
+  module Handlers
+    describe SaxHandler do
+      subject(:handler) { SaxHandler.new }
+
+      describe "#start_element" do
+        it "sets the current node to new hash" do
+          handler.start_element "foo"
+          expect(handler.node).to eq({})
+        end
+
+        context "when no element present with name" do
+          subject(:handler) { SaxHandler.new }
+          it "adds the node name and empty hash" do
+            handler.start_element("foo").end_element("foo")
+            expect(handler.node).to eq({"foo" => {}})
+          end
+        end
+
+        context "when one element present with name" do
+          subject(:handler) { SaxHandler.new({"foo" => { "$" => "bar" }}) }
+          it "add the new node and old node to an Array" do
+            handler.start_element("foo").end_element("foo")
+            expect(handler.node)
+              .to eq({"foo" => [{"\$" => "bar"}, {}]})
+          end
+        end
+
+        context "when more than one element present with name" do
+          subject(:handler) { SaxHandler.new({ "foo" => [{ "\$" => "bar" },
+                  { "\$" => "baz" }] }) }
+          it "adds the new node to the Array" do
+            handler.start_element("foo").end_element("foo")
+            expect(handler.node)
+              .to eq({"foo" => [{"\$" => "bar"}, {"\$" => "baz"}, {}]})
+          end
+        end
+      end
+
+      describe "#attr" do
+        it "adds attribute as property that begins with '@'" do
+          handler.start_element("foo")
+            .attr("george", "bar")
+            .end_element("foo")
+          expect(handler.node).to eq("foo" => {"@george"=>  "bar"})
+        end
+
+        context "with parent namespaces" do
+          before do
+            handler.start_element("foo")
+              .text("test")
+              .attr("xmlns", "http://foo.com/namespace")
+              .attr("xmlns:charlie", "http://foo.com/charlie")
+              .start_element("charlie:bar")
+              .text("test2")
+              .end_element("charlie:bar")
+          end
+
+          it "adds parents namespaces" do
+            expect(handler.node["charlie:bar"]["@xmlns"]["$"])
+              .to eq("http://foo.com/namespace")
+            expect(handler.node["charlie:bar"]["@xmlns"]["charlie"])
+              .to eq("http://foo.com/charlie")
+          end
+        end
+
+        context "when namespace" do
+          it "stores main namespace in @xmlns $ property" do
+            handler.start_element("foo")
+              .attr("xmlns", "http://foo.com/namespace")
+              .end_element("foo")
+            expect(handler.node)
+              .to eq("foo" => {"@xmlns" => {"$" => "http://foo.com/namespace"}})
+          end
+
+          it "stores additional namespaces in named property" do
+            handler.start_element("foo")
+              .attr("xmlns:george", "http://foo.com/george")
+              .end_element("foo")
+            expect(handler.node)
+              .to eq("foo" => {"@xmlns" => {"george" => "http://foo.com/george"}})
+          end
+        end
+      end
+
+      describe "#text" do
+        it "sets the $ key in the hash with the text value" do
+          handler.text "foo"
+          expect(handler.node).to eq({"\$" => "foo"})
+        end
+
+        it "compresses leading whitespace" do
+          handler.text "\nfoo"
+          expect(handler.node).to eq({"\$" => "foo"})
+        end
+
+        it "compresses trailing whitespace" do
+          handler.text "foo\n"
+          expect(handler.node).to eq({"\$" => "foo"})
+        end
+      end
+
+      describe "#cdata" do
+        it "sets the $ key in the hash with the cdata section" do
+          handler.cdata "foo"
+          expect(handler.node).to eq({"\$" => "foo"})
+        end
+      end
+
+      describe "#end_element" do
+        context "with parent tag on stack" do
+          before do
+            handler.start_element "foo"
+          end
+
+          it "closes the current node" do
+            handler.end_element "foo"
+            expect(handler.node).to eq({"foo" => {}})
+          end
+        end
+
+        context "when no parent tag on stack" do
+          it "sets node to empty hash" do
+            handler.end_element "foo"
+            expect(handler.node).to eq({})
+          end
+        end
+      end
+    end
+  end
+end
+

data/spec/badgerhash/parsers/rexml_spec.rb

@@ -0,0 +1,60 @@
+require File.expand_path "../../../spec_helper.rb", __FILE__
+
+module Badgerhash
+  module Parsers
+    module REXML
+      describe SaxDocument do
+        let(:handler) { double(:handler) }
+        subject(:document) { SaxDocument.new(handler) }
+
+        describe ".parse" do
+          let(:parser) { double(:parser) }
+          let(:io)     { double(:io) }
+
+          it "delegates to the REXML sax parser" do
+            expect(::REXML::Document).to receive(:parse_stream)
+            SaxDocument.parse(handler, io)
+          end
+        end
+
+        describe "#tag_end" do
+          it "delegates to handler" do
+            expect(handler).to receive(:end_element).with("foo")
+            document.tag_end("foo")
+          end
+        end
+
+        describe "#cdata" do
+          it "delegates to handler's text method" do
+            expect(handler).to receive(:cdata).with "foo"
+            document.cdata "foo"
+          end
+        end
+
+        describe "#text" do
+          it "delegates to the handler's text method" do
+            expect(handler).to receive(:text).with "foo"
+            document.text "foo"
+          end
+        end
+
+        describe "#tag_start" do
+          let(:attributes) { [["one", '1'], ["two", '2']] }
+
+          before do
+            expect(handler).to receive(:start_element).with "foo"
+          end
+
+          it "delegates to handler's start_element_method" do
+            document.tag_start "foo"
+          end
+
+          it "delegates attributes to handler's attr method" do
+            expect(handler).to receive(:attr).exactly(attributes.size).times
+            document.tag_start "foo", attributes
+          end
+        end
+      end
+    end
+  end
+end