saxerator 0.2.0 → 0.3.0

data/README.md

@@ -8,15 +8,31 @@ independently.
 
 Each xml chunk is parsed into a JSON-like Ruby Hash structure for consumption.
 
-Examples
---------
 You can parse any valid xml in 3 simple steps.
 
 1. Initialize the parser
-1. Tell it which tag you care about
-1. Perform your work in an 'each' block, or using any [Enumerable](http://apidock.com/ruby/Enumerable)
+1. Specify which tag you care about using a simple DSL
+1. Perform your work in an `each` block, or using any [Enumerable](http://apidock.com/ruby/Enumerable)
 method
 
+The DSL
+-------
+The DSL consists of predicates that may be combined to describe which elements the parser should enumerate over.
+Saxerator will only enumerate over chunks of xml that match all of the combined predicates (see Examples section
+for added clarity).
+
+| Predicate       | Explanation |
+|:----------------|:------------|
+| `all`           | Returns the entire document parsed into a hash. Cannot combine with other predicates
+| `for_tag(name)` | Elements whose name matches the given `name`
+| `at_depth(n)`   | Elements `n` levels deep inside the root of an xml document. The root element itself is `n = 0`
+| `within(name)`  | Elements nested anywhere within an element with the given `name`
+| `child_of(name)`| Elements that are direct children of an element with the given `name`
+| `with_attribute(name, value)` | Elements with a given `name` and `value`. If no `value` is given, matches any element with the specified attribute name present
+
+
+Examples
+--------
 ```ruby
 parser = Saxerator.parser(File.new("rss.xml"))
 

data/lib/saxerator.rb

@@ -7,11 +7,12 @@ require 'saxerator/hash_with_attributes'
 require 'saxerator/xml_node'
 
 require 'saxerator/parser/accumulator'
-require 'saxerator/parser/element_name_latch'
-require 'saxerator/parser/depth_latch'
-require 'saxerator/parser/within_element_latch'
+require 'saxerator/parser/for_tag_latch'
+require 'saxerator/parser/at_depth_latch'
+require 'saxerator/parser/within_latch'
 require 'saxerator/parser/latched_accumulator'
 require 'saxerator/parser/child_of_latch'
+require 'saxerator/parser/with_attribute_latch'
 
 module Saxerator
   extend self

data/lib/saxerator/dsl.rb

@@ -1,19 +1,23 @@
 module Saxerator
   module DSL
     def for_tag(tag)
-      specify(Parser::ElementNameLatch.new(tag.to_s))
+      specify Parser::ForTagLatch.new(tag.to_s)
     end
 
     def at_depth(depth)
-      specify(Parser::DepthLatch.new(depth.to_i))
+      specify Parser::AtDepthLatch.new(depth.to_i)
     end
 
     def within(tag)
-      specify(Parser::WithinElementLatch.new(tag.to_s))
+      specify Parser::WithinLatch.new(tag.to_s)
     end
 
     def child_of(tag)
-      specify(Parser::ChildOfLatch.new(tag.to_s))
+      specify Parser::ChildOfLatch.new(tag.to_s)
+    end
+
+    def with_attribute(name, value = nil)
+      specify Parser::WithAttributeLatch.new(name.to_s, !!value ? value.to_s : nil)
     end
 
     private

data/lib/saxerator/parser/{depth_latch.rb → at_depth_latch.rb}

@@ -2,10 +2,10 @@ require 'saxerator/parser/document_latch'
 
 module Saxerator
   module Parser
-    class DepthLatch < DocumentLatch
+    class AtDepthLatch < DocumentLatch
       def initialize(depth)
         @target_depth = depth
-        @current_depth = 0
+        @current_depth = -1
       end
 
       def start_element(_, __)

data/lib/saxerator/parser/{element_name_latch.rb → for_tag_latch.rb}

@@ -2,7 +2,7 @@ require 'saxerator/parser/document_latch'
 
 module Saxerator
   module Parser
-    class ElementNameLatch < DocumentLatch
+    class ForTagLatch < DocumentLatch
       def initialize(name)
         @name = name
       end

data/lib/saxerator/parser/with_attribute_latch.rb

@@ -0,0 +1,25 @@
+require 'saxerator/parser/document_latch'
+
+module Saxerator
+  module Parser
+    class WithAttributeLatch < DocumentLatch
+      def initialize(name, value)
+        @attr_name = name
+        @attr_value = value
+      end
+
+      def start_element _, attributes
+        attributes = Hash[attributes]
+        if attributes[@attr_name] && (@attr_value.nil? || attributes[@attr_name] == @attr_value)
+          open
+        else
+          close
+        end
+      end
+
+      def end_element _
+        close
+      end
+    end
+  end
+end

data/lib/saxerator/parser/{within_element_latch.rb → within_latch.rb}

@@ -2,7 +2,7 @@ require 'saxerator/parser/document_latch'
 
 module Saxerator
   module Parser
-    class WithinElementLatch < DocumentLatch
+    class WithinLatch < DocumentLatch
       def initialize(name)
         @name = name
         @depth_within_element = 0

data/lib/saxerator/version.rb

@@ -1,3 +1,3 @@
 module Saxerator
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/spec/lib/saxerator_spec.rb

@@ -43,8 +43,8 @@ describe Saxerator do
             <book>
               <name>How to eat an airplane</name>
               <author>
-                <name>Leviticus Alabaster</name>
-                <name>Eunice Diesel</name>
+                <name type="primary">Leviticus Alabaster</name>
+                <name type="foreword">Eunice Diesel</name>
               </author>
             </book>
             <book>
@@ -64,7 +64,7 @@ describe Saxerator do
       end
 
       it "should only parse the requested tag depth" do
-        subject.at_depth(3).inject([], :<<).should == [
+        subject.at_depth(2).inject([], :<<).should == [
           'How to eat an airplane', { 'name' => ['Leviticus Alabaster', 'Eunice Diesel'] },
           'To wallop a horse in the face', { 'name' => 'Jeanne Clarewood' },
           'Is our children learning?', { 'name' => 'Hazel Nutt' }
@@ -72,7 +72,7 @@ describe Saxerator do
       end
 
       it "should only parse the requested tag depth and tag" do
-        subject.at_depth(3).for_tag(:name).inject([], :<<).should == [
+        subject.at_depth(2).for_tag(:name).inject([], :<<).should == [
             'How to eat an airplane',
             'To wallop a horse in the face',
             'Is our children learning?'
@@ -92,6 +92,17 @@ describe Saxerator do
             'Hazel Nutt'
         ]
       end
+
+      it "should match tags with the specified attributes" do
+        subject.with_attribute(:type).inject([], :<<).should == [
+            'Leviticus Alabaster',
+            'Eunice Diesel'
+        ]
+      end
+
+      it "should match tags with the specified attributes" do
+        subject.with_attribute(:type, :primary).inject([], :<<).should == ['Leviticus Alabaster']
+      end
     end
 
     context "with a grand child" do
@@ -142,17 +153,18 @@ describe Saxerator do
       end
     end
 
+    # Verifying the basic parsing behaviors (strings, hashes, arrays, attributes, character entity decoding)
     context "with a file with nested elements" do
       let(:xml) { fixture_file('nested_elements.xml') }
       subject { parser.for_tag(:entry).first }
 
       specify { subject['title'].should == 'How to eat an airplane' }
       specify { subject['author'].should == {'name' => 'Soulcutter'} }
+
       specify { subject['contributor'].should == [{'name' => 'Jane Doe'}, {'name' => 'Leviticus Alabaster'}] }
-      specify { subject['content'].should == "<p>Airplanes are very large — this can present difficulty in digestion.</p>"}
-      specify { subject['content'].attributes['type'].should == 'html' }
       specify { subject['contributor'][0].attributes['type'].should == 'primary' }
-      specify { subject['contributor'][0]['name'].should == 'Jane Doe' }
+
+      specify { subject['content'].should == "<p>Airplanes are very large — this can present difficulty in digestion.</p>"}
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saxerator
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-24 00:00:00.000000000 Z
+date: 2012-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -82,12 +82,13 @@ files:
 - lib/saxerator/full_document.rb
 - lib/saxerator/hash_with_attributes.rb
 - lib/saxerator/parser/accumulator.rb
+- lib/saxerator/parser/at_depth_latch.rb
 - lib/saxerator/parser/child_of_latch.rb
-- lib/saxerator/parser/depth_latch.rb
 - lib/saxerator/parser/document_latch.rb
-- lib/saxerator/parser/element_name_latch.rb
+- lib/saxerator/parser/for_tag_latch.rb
 - lib/saxerator/parser/latched_accumulator.rb
-- lib/saxerator/parser/within_element_latch.rb
+- lib/saxerator/parser/with_attribute_latch.rb
+- lib/saxerator/parser/within_latch.rb
 - lib/saxerator/string_with_attributes.rb
 - lib/saxerator/version.rb
 - lib/saxerator/xml_node.rb