xmlparsable 1.1

data/README.md

@@ -0,0 +1,80 @@
+# XmlParsable
+
+XmlParsable is a simple means to declare how an XML grammar maps to Ruby objects. It does not
+perform validation of the input, and it is only able to describe fairly simple structures. It
+relies on LibXML::XML::SaxParser.
+
+1. Declare XML grammar
+
+        require "xmlparsable"
+
+        # Needed only for using the "collection" declaration or
+        # implement your own String#pluralize, String#singularize
+        require "active_support/core_ext"
+
+        class AddressBook
+          include XmlParsable
+
+          class Contact
+            include XmlParsable
+            element :givenname
+            element :familyname
+            element :phone
+            element :email
+            element :spouse,      Contact
+            collection :children, Contact
+            element :birthdate,   DateElement
+            element :updated,     TimeElement
+          end
+
+          collection :contact, Contact
+        end
+
+2. Parse input XML from string, IO, or File
+
+        book = AddressBook.parse(<<-XML)
+          <contacts>
+            <contact>
+              <familyname>Kim</familyname>
+              <givenname>Jong-il</givenname>
+              <birthdate>1942-02-16</birthdate>
+              <updated>2010-01-01T12:45:30</updated>
+              <children>
+                <child><givenname>Sul-song</givenname></child>
+                <child><givenname>Jong-chul</givenname></child>
+                <child><givenname>Jong-un</givenname></child>
+                <child>
+                  <givenname>Jong-nam</givenname>
+                  <spouse>
+                    <givenname>Jong-hui</givenname>
+                    <familyname>Shin</familyname>
+                  </spouse>
+                </child>
+              </children>
+            </contact>
+    
+            <contact>
+              <givenname>Vladimir</givenname>
+              <familyname>Putin</familyname>
+              <email>vlad@gmail.com</email>
+              <spouse>
+                <givenname>Lyudmila</givenname>
+                <familyname>Putina</familyname>
+              </spouse>
+            </contact>
+          </contacts>
+        XML
+
+3. Iterate parsed data
+
+        kim, vlad = book.contacts
+        kim.givenname #=> "Kim"
+        kim.birthdate #=> #<Date: 4860813/2,0,2299161>
+        kim.updated   #=> Fri Jan 01 12:45:30 2010
+    
+        sulsong, jongchul, jongun, jongnam = kim.children
+        jongnam.spouse.givenname  #=> "Jong-hui"
+        jongnam.spouse.familyname #=> "Shin"
+    
+        vlad.email    #=> "vlad@gmail.com"
+        vlad.spouse   #=> #<AddressBook::Contact @givenname="Lyudmila" @familyname="Putina">

data/Rakefile

@@ -0,0 +1,19 @@
+begin
+  require "rspec/core/rake_task"
+
+  RSpec::Core::RakeTask.new do |t|
+    t.verbose = false
+    t.pattern = "spec/examples/**/*.example"
+    t.rspec_opts = ["--color", "--format=p"]
+  end
+rescue LoadError
+  require "spec/rake/spectask"
+
+  Spec::Rake::SpecTask.new do |t|
+    t.pattern = "spec/examples/**/*.example"
+    t.spec_opts << "--color"
+    t.spec_opts << "--format=p"
+  end
+end
+
+task :default => :spec

data/lib/xmlparsable/elements/abstract.rb

@@ -0,0 +1,21 @@
+module XmlParsable
+  module Elements
+    class AbstractElement
+      def self.parsable
+        self
+      end
+
+      def open(name, attributes)
+      end
+
+      def read(text)
+      end
+
+      def comment(text)
+      end
+
+      def finalize
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements/date.rb

@@ -0,0 +1,25 @@
+require "date"
+
+module XmlParsable
+  module Elements
+    #
+    # Parses content into a ruby Date value
+    #
+    class DateElement < AbstractElement
+      attr_reader :name
+
+      def initialize(name, attributes, parent, *arguments)
+        @name, @parent, @string = name, parent, ""
+      end
+
+      def read(text)
+        @string << text
+      end
+
+      def finalize
+        stripped = @string.strip
+        @parent.closed(self, Date.parse(stripped)) if stripped != ""
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements/list.rb

@@ -0,0 +1,31 @@
+module XmlParsable
+  module Elements
+
+    class ListElement < AbstractElement
+      attr_reader :name
+
+      def initialize(name, attributes, parent, *arguments)
+        @name, @parent, @elements = name, parent, []
+
+        @cname   = arguments.shift.to_s
+        @cparser = arguments.shift
+        @cargs   = arguments
+      end
+
+      def open(name, attributes)
+        if name == @cname
+          @cparser.parsable.new(name, attributes, self, *@cargs)
+        end
+      end
+
+      def closed(element, value)
+        @elements << value
+      end
+
+      def finalize
+        @parent.closed(self, @elements)
+      end
+    end
+
+  end
+end

data/lib/xmlparsable/elements/record.rb

@@ -0,0 +1,48 @@
+module XmlParsable
+  module Elements
+    class RecordElement < AbstractElement
+      attr_reader :name, :attributes, :parent, :target
+
+      def initialize(name, attributes, parent, target, parsers, *arguments)
+        @name       = name
+        @attributes = attributes
+        @parent     = parent
+        @target     = target
+        @parsers    = parsers
+        @elements   = Hash.new
+      end
+
+      def open(name, attributes)
+        parser, *arguments = @parsers[name]
+        if parser
+          parser.new(name, attributes, self, *arguments)
+        end
+      end
+
+      def closed(element, value)
+        parser, *arguments = @parsers[element.name]
+        if arguments.include?(:repeated)
+          (@elements[element.name] ||= []) << value
+        else
+          @elements[element.name] = value
+        end
+      end
+
+      def finalize
+        @elements.each{|name, value| @target.instance_variable_set("@#{name}", value) }
+        @parent.closed(self, @target) if @parent
+      end
+
+      class Proxy
+        def initialize(base, parsers)
+          @base, @parsers = base, parsers
+        end
+
+        def new(name, attributes, parent, *arguments)
+          RecordElement.new(name, attributes, parent, @base.new, @parsers)
+        end
+      end
+    end
+
+  end
+end

data/lib/xmlparsable/elements/string.rb

@@ -0,0 +1,23 @@
+module XmlParsable
+  module Elements
+    #
+    # Parses content into a ruby String value. This discards comments and children
+    # elements so "abc <!-- foo --> def <b>whatever</b>" is read as "abc def"
+    #
+    class StringElement < AbstractElement
+      attr_reader :name
+
+      def initialize(name, attributes, parent, *arguments)
+        @name, @parent, @string = name, parent, ""
+      end
+
+      def read(text)
+        @string << text
+      end
+
+      def finalize
+        @parent.closed(self, @string)
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements/text.rb

@@ -0,0 +1,34 @@
+module XmlParsable
+  module Elements
+    #
+    # Parses content into a ruby String value. Discards comments and flattens children
+    # elements so "abc def <b>what<!-- foo -->ever</b>" is read as "abc def whatever"
+    #
+    class TextElement < XmlElement::Node
+      attr_reader :name, :attributes, :parent
+
+      def initialize(name, attributes, parent, *arguments)
+        @name, @attributes, @parent, @text = name, attributes, parent, ""
+      end
+
+      def open(name, attributes)
+        TextElement.new(name, attributes, self)
+      end
+
+      def read(text)
+        @text << text
+      end
+
+      def comment(text)
+      end
+      
+      def closed(element, value)
+        @text << value
+      end
+
+      def finalize
+        @parent.closed(self, @text)
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements/time.rb

@@ -0,0 +1,25 @@
+require "time"
+
+module XmlParsable
+  module Elements
+    #
+    # Parses content into a ruby Time value
+    #
+    class TimeElement < AbstractElement
+      attr_reader :name
+
+      def initialize(name, attributes, parent, *arguments)
+        @name, @parent, @string = name, parent, ""
+      end
+
+      def read(text)
+        @string << text
+      end
+
+      def finalize
+        stripped = @string.strip
+        @parent.closed(self, Time.parse(stripped)) if stripped != ""
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements/xml.rb

@@ -0,0 +1,79 @@
+module XmlParsable
+  module Elements
+    #
+    # Parses content into a generic tree structure, consisting of three
+    # classes -- Node, Text, and Comment.
+    #
+    class XmlElement
+
+      def self.parsable
+        Node
+      end
+
+      class Node < AbstractElement
+        attr_reader :name, :attributes, :parent, :children
+
+        def initialize(name, attributes, parent, *arguments)
+          @parent, @name, @attributes, @children = parent, name, attributes, Array.new
+        end
+
+        def open(name, attributes)
+          Node.new(name, attributes, self)
+        end
+
+        def read(text)
+          @children << Text.new(text, self)
+        end
+
+        def comment(text)
+          @children << Comment.new(text, self)
+        end
+        
+        def closed(element, value)
+          @children << value
+        end
+
+        def finalize
+          @parent.closed(self, self)
+        end
+
+        def to_s(buffer = "")
+          buffer << "<#{@name}"
+          @attributes.each{|name, value| buffer << %[ #{name}='#{value}'] }
+
+          if @children.empty?
+            buffer << "/>"
+          else
+            buffer << ">"
+            @children.each{|child| child.to_s(buffer) }
+            buffer << "</#{@name}>" 
+          end
+        end
+      end
+
+      class Text
+        attr_reader :text, :parent
+
+        def initialize(text, parent)
+          @text, @parent = text, parent
+        end
+
+        def to_s(buffer = "")
+          buffer << @text
+        end
+      end
+
+      class Comment
+        attr_reader :text, :parent
+
+        def initialize(text, parent)
+          @text, @parent = text, parent
+        end
+
+        def to_s(buffer = "")
+          buffer << "<!--" << @text << "-->"
+        end
+      end
+    end
+  end
+end

data/lib/xmlparsable/elements.rb

@@ -0,0 +1,12 @@
+module XmlParsable
+  module Elements
+    autoload :AbstractElement,  "xmlparsable/elements/abstract"
+    autoload :DateElement,      "xmlparsable/elements/date"
+    autoload :ListElement,      "xmlparsable/elements/list"
+    autoload :RecordElement,    "xmlparsable/elements/record"
+    autoload :StringElement,    "xmlparsable/elements/string"
+    autoload :TextElement,      "xmlparsable/elements/text"
+    autoload :TimeElement,      "xmlparsable/elements/time"
+    autoload :XmlElement,       "xmlparsable/elements/xml"
+  end
+end

data/lib/xmlparsable/parser.rb

@@ -0,0 +1,42 @@
+module XmlParsable
+  class Parser
+    attr_reader :documents
+
+    def initialize(constructed = nil, &constructor)
+      @documents   = Array.new
+      @constructor = constructor || lambda { constructed }
+    end
+
+    def on_start_document
+      @stack = [@constructor.call]
+    end
+
+    def on_end_document
+      @documents << @stack.shift.finalize
+    end
+
+    def on_characters(text)
+      @stack.first.read(text)
+    end
+
+    def on_comment(comment)
+      @stack.first.comment(comment)
+    end
+
+    def on_start_element_ns(name, attributes, prefix, uri, namespaces)
+      @stack.unshift(@stack.first.open(name, attributes) || StubElement)
+    end
+
+    def on_end_element_ns(name, prefix, uri)
+      @stack.shift.finalize
+    end
+
+    module StubElement
+      def self.open(name, attributes) self end
+      def self.close(element, value) end
+      def self.comment(text) end
+      def self.read(text) end
+      def self.finalize; end
+    end
+  end
+end

data/lib/xmlparsable.rb

@@ -0,0 +1,74 @@
+require "libxml"
+
+module XmlParsable
+
+  autoload :Parser,   "xmlparsable/parser"
+  autoload :Elements, "xmlparsable/elements"
+
+  def self.parser(input)
+    case input
+    when String then LibXML::XML::SaxParser.string(input)
+    when File   then LibXML::XML::SaxParser.file(input)
+    when IO     then LibXML::XML::SaxParser.io(input)
+    else raise ArgumentError, "argument must be a String, File, or IO"
+    end
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.__send__(:include, Elements)
+  end
+
+  module ClassMethods
+    def element(name, *arguments)
+      element ||= arguments.pop.delete(:class) if arguments.last.is_a?(Hash)
+      element ||= arguments.shift if arguments.first.is_a?(Class)
+      element ||= Elements::StringElement
+
+      (@parsers ||= {})[name.to_s] = [element.parsable, *arguments]
+
+      define_method(name) { instance_variable_get("@#{name}") }
+    end
+
+    def repeated(name, *arguments)
+      element ||= arguments.pop.delete(:class) if arguments.last.is_a?(Hash)
+      element ||= arguments.shift if arguments.first.is_a?(Class)
+      element ||= Elements::StringElement
+
+      (@parsers ||= {})[name.to_s.singularize] = [element.parsable, *arguments.push(:repeated)]
+
+      define_method(name) { instance_variable_get("@#{name.to_s.singularize}") }
+    end
+
+    def collection(name, *arguments)
+      item ||= arguments.pop.delete(:class) if arguments.last.is_a?(Hash)
+      item ||= arguments.shift if arguments.first.is_a?(Class)
+      item ||= Elements::StringElement
+
+      if arguments.empty?
+        single = name.to_s.singularize
+        plural = name.to_s.pluralize
+      else
+        plural = name
+        single = arguments.shift
+      end
+
+      element(plural, Elements::ListElement, single, item)
+    end
+
+    def parse(input)
+      root   = XmlParsable::Elements::RecordElement.new(nil, nil, nil, new, @parsers)
+      stack  = XmlParsable::Parser.new(root)
+      parser = XmlParsable.parser(input)
+
+      parser.callbacks = stack
+      parser.parse
+      root.target
+    end
+
+    def parsable
+      Elements::RecordElement::Proxy.new(self, @parsers)
+    end
+  end
+
+end

data/spec/examples/record.example

@@ -0,0 +1,229 @@
+require "spec_helper"
+
+describe XmlParsable::Elements::RecordElement do
+
+  class Record
+    include XmlParsable
+
+    element :date,    DateElement
+    element :record,  self
+    element :string,  StringElement
+    element :text,    TextElement
+    element :time,    TimeElement
+    element :xml,     XmlElement
+
+    collection :kids, self
+    collection :list, :item
+  end
+
+  describe "date" do
+    it "parses date into a ruby Date" do
+      Record.parse("<date>#{Date.today}</date>").date.should == Date.today
+    end
+
+    it "parses missing date as nil" do
+      Record.parse("<date><!-- nope --></date>").date.should == nil
+    end
+
+    it "ignores children" do
+      Record.parse("<date><x>2010-01-01</x></date>").date.should == nil
+    end
+
+    it "ignores comments" do
+      Record.parse("<date>#{Date.today} <!-- that's today --></date>").date.should == Date.today
+    end
+
+    it "ignores whitespace" do
+      Record.parse("<date>\n  #{Date.today}\n  </date>").date.should == Date.today
+    end
+  end
+
+  describe "list of strings" do
+    it "parses empty list into an empty Array" do
+      Record.parse("<list/>").list.should == []
+    end
+
+    it "parses non-empty list into an Array" do
+      Record.parse("<list><item>a</item><item>b</item></list>").list.should == ["a", "b"]
+    end
+
+    it "ignores non-matching children" do
+      Record.parse("<list><fail/><item/><boat/><item/><item/></list>").list.should == ["", "", ""]
+    end
+
+    it "ignores comments" do
+      Record.parse("<list><!-- <item>x</item> --><item><!-- y --></item></list>").list.should == [""]
+    end
+
+    it "ignores whitespace between children" do
+      Record.parse(<<-XML).list.should == ["a", "b", "c"]
+        <list>
+          <item>a</item>
+          <item>b</item>
+          <item>c</item>
+        </list>
+      XML
+    end
+  end
+
+  describe "list of records" do
+    it "parses empty list into an empty Array" do
+      Record.parse("<kids/>").kids.should == []
+    end
+
+    it "parses non-empty list into an array" do
+      x = Record.parse(<<-XML)
+        <kids>
+          <kid><text>first</text></kid>
+          <kid><text>second</text></kid>
+          <kid><text>third</text></kid>
+        </kids>
+      XML
+
+      x.kids.should have(3).items
+      x.kids[0].text.should == "first"
+      x.kids[1].text.should == "second"
+      x.kids[2].text.should == "third"
+    end
+  end
+
+  describe "string" do
+    it "parses empty string" do
+      Record.parse("<string></string>").string.should == ""
+    end
+
+    it "parses non-empty string" do
+      Record.parse("<string>lo and behold</string>").string.should == "lo and behold"
+    end
+
+    it "ignores comments" do
+      Record.parse("<string>hi<!-- secret message --></string>").string.should == "hi"
+    end
+
+    it "ignores children" do
+      Record.parse("<string><b>bold</b>, <i>italic</i>, plain</string>").string.should == ", , plain"
+    end
+
+    it "does not ignore whitespace" do
+      Record.parse("<string>   foob  ar</string>").string.should == "   foob  ar"
+    end
+  end
+
+  describe "text" do
+    it "parses text" do
+      Record.parse("<text>lo and behold</text>").text.should == "lo and behold"
+    end
+
+    it "ignores comments" do
+      Record.parse("<text>lo <!--and--> behold</text>").text.should == "lo  behold"
+    end
+
+    it "strips away markup" do
+      Record.parse("<text>lo <span class='x'><i>and</i> behold</span></text>").text.should == "lo and behold"
+    end
+
+    it "does not ignore whitespace" do
+      Record.parse("<text>   foob  ar</text>").text.should == "   foob  ar"
+    end
+  end
+
+  describe "time" do
+    it "parses time" do
+      time = Time.now
+      Record.parse("<time>#{time}</time>").time.to_i.should == time.to_i
+    end
+
+    it "ignores comments" do
+      Record.parse("<time><!-- #{Time.now} --></time>").time.should be_nil
+    end
+
+    it "ignores children" do
+      Record.parse("<time><b>#{Time.now}</b></time>").time.should be_nil
+    end
+
+    it "ignores whitespace" do
+      time = Time.now
+      Record.parse("<time>   #{time}    </time>").time.to_i.should == time.to_i
+    end
+  end
+
+  describe "record" do
+    it "parses date" do
+      x = Record.parse("<record><date>#{Date.today}</date></record>")
+      x.date.should be_nil
+      x.record.date.should == Date.today
+    end
+
+    it "parses list" do
+      x = Record.parse("<record><list/></record>")
+      x.list.should be_nil
+      x.record.list.should == []
+    end
+
+    it "parses string" do
+      x = Record.parse("<record><string>abc</string></record>")
+      x.string.should be_nil
+      x.record.string.should == "abc"
+    end
+
+    it "parses text" do
+      x = Record.parse("<record><text><b>big</b><i>little</i></text></record>")
+      x.text.should be_nil
+      x.record.text.should == "biglittle"
+    end
+
+    it "parses time" do
+      time = Time.now
+      Record.parse("<record><time>#{time}</time></record>").record.time.to_i.should == time.to_i
+    end
+
+    it "parses multiple elements" do
+      time = Time.now
+      x = Record.parse <<-XML
+        <record>
+          <date>#{Date.today}</date>
+          <list>
+            <item>a</item>
+            <item>b</item>
+            <item>c</item>
+          </list>
+          <string>xyz</string>
+          <text>
+            <ul>
+              <li>vim</li>
+              <li>emacs</li>
+              <li>ctags</li>
+              <li>lint</li>
+              <li>gdb</li>
+            </ul>
+          </text>
+          <time>#{time}</time>
+        </record>
+      XML
+
+      x.record.date.should == Date.today
+      x.record.list.should == ["a","b","c"]
+      x.record.string.should == "xyz"
+      x.record.text.strip.should == <<-DOC.strip
+              vim
+              emacs
+              ctags
+              lint
+              gdb
+      DOC
+
+      x.record.time.to_i.should == time.to_i
+    end
+
+    it "parses recursive records" do
+      x = Record.parse("<record><record><record><record></record></record></record></record>")
+      x.should be_a(Record)
+      x.record.should be_a(Record)
+      x.record.record.should be_a(Record)
+      x.record.record.record.should be_a(Record)
+      x.record.record.record.record.should be_a(Record)
+      x.record.record.record.record.record.should be_nil
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+begin
+  require "rspec"
+rescue LoadError
+  require "spec"
+end
+
+spec = File.dirname(__FILE__)
+
+$:.unshift(spec)
+$:.unshift(File.dirname(spec) + "/lib")
+
+require "xmlparsable"
+require "active_support/core_ext"

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: xmlparsable
+version: !ruby/object:Gem::Version
+  version: '1.1'
+  prerelease: 
+platform: ruby
+authors:
+- Kyle Putnam
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-14 00:00:00.000000000 Z
+dependencies: []
+description: Simple declarative XML parsing
+email: putnam.kyle@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/xmlparsable/elements/abstract.rb
+- lib/xmlparsable/elements/date.rb
+- lib/xmlparsable/elements/list.rb
+- lib/xmlparsable/elements/record.rb
+- lib/xmlparsable/elements/string.rb
+- lib/xmlparsable/elements/text.rb
+- lib/xmlparsable/elements/time.rb
+- lib/xmlparsable/elements/xml.rb
+- lib/xmlparsable/elements.rb
+- lib/xmlparsable/parser.rb
+- lib/xmlparsable.rb
+- spec/examples/record.example
+- spec/spec_helper.rb
+homepage: https://github.com/kputnam/xmlparsable
+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: Simple declarative XML parsing
+test_files:
+- spec/examples/record.example