saxy 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9486f25851c6f1fc75f37b2196b02cc27831386
-  data.tar.gz: d914fa68442184ac2066e8f860f1f82d029222a3
+  metadata.gz: d90158e708f84a77ddd18b19c881fa528a839f28
+  data.tar.gz: 14e88af956179b23fff98fc80a2dac03cd36efa2
 SHA512:
-  metadata.gz: 116cf7b365cecb245cec43dc7e45ec62f5e36f05461d47ce270b8aab2113a546de053d4772ac97878518d5a0534241ee44ffcd37cd9db172016872edd7192d04
-  data.tar.gz: de32e8c5e86c0a29300a5f0dc64b29c3282c40d3aa8fb5d4a2ad0f70d6352d860cb95c040a985eca2782c7e1a0e70fa507fc677272e0c8e25b0a277d71e98e88
+  metadata.gz: d1380012654abe0e6c51095220d0be5349666de298294addbd81ae1954842249cea8e055514c3583eaa285834eb5ee9ac181b632647bc30d1fa8ebcfd6d049d9
+  data.tar.gz: 4bb6c121dd6543cb736d02278ee752eba2bf9a2e6105cdaf3bdff7fa617facda2738ba697de4626135a09984f77a100a4d3ccd7082c25a1ea880cf87aee1a127

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Saxy Changelog
+
+## 0.6.0
+
+* [BREAKING] `Saxy::ParsingError` now inherits from `StandardError`, not `Exception`.
+* [BREAKING] Forced encoding is now an option instead of third argument of `Saxy.parse` method.
+* Added `recovery` and `replace_entities` options that are internally passed to `Nokogiri::XML::SAX::ParserContext`
+* Added `context` method to `Saxy::ParsingError` that holds parser context at the time of error.
+
+## 0.5.2
+
+* Added optional `encoding` argument to `Saxy.parse`
+
+## 0.5.1
+
+* Removed `activesupport` dependency
+
+## 0.5.0
+
+* [BREAKING] Dropped support for ruby 1.9.2 and lower
+* [BREAKING] Yields hashes instead of `OpenStruct`s
+* Added support for `IO`-like objects

data/README.md

@@ -5,7 +5,7 @@
 
 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 through it and yields objects along the way.
+It uses SAX parser (provided by Nokogiri gem) under the hood, which means that it doesn't load the whole XML file into memory. It goes once through it and yields objects along the way.
 
 In result the memory footprint of the parser remains small and more or less constant irrespective of the size of the XML file, be it few KB or hundreds of GB.
 
@@ -23,24 +23,51 @@ Or install it yourself as:
 
     $ gem install saxy
 
+## Requirements
+
 As of `0.5.0` version `saxy` requires ruby 1.9.3 or higher. Previous versions of the gem work with ruby 1.8 and 1.9.2 (see below), but they are not maintained anymore.
 
-## Ruby 1.8 support
+### Ruby 1.8 support
 
 See `ruby-1.8` branch. Install with:
 
     gem 'saxy', '~> 0.3.0'
 
-## Ruby 1.9.2 support
+### Ruby 1.9.2 support
 
 See `ruby-1.9.2` branch. Install with:
 
     gem 'saxy', '~> 0.4.0'
 
+## Changelog
+
+See `CHANGELOG.md` file.
 
 ## Usage
 
-Assume the XML file:
+You instantiate the parser by passing path to XML file or an IO-like object, object-identifying tag name and options hash (optionally) as its arguments.
+
+```ruby
+parser = Saxy.parse(path_or_io, object_tag, options = {})
+```
+
+Then iterate over it using `each` (or any of convenient methods provided by `Enumerable` mix-in).
+
+```ruby
+parser.each do |object|
+  ...
+end
+```
+
+### Options
+
+* `encoding` - Forces the parser to work in given encoding
+* `recovery` - Should this parser recover from structural errors? It will not stop processing file on structural errors if set to `true`.
+* `replace_entities` - Should this parser replace entities? `&` will get converted to `&` if set to `true`.
+
+## Example
+
+Assume the XML file (an imaginary product feed):
 
 ````xml
 <?xml version='1.0' encoding='UTF-8'?>
@@ -63,8 +90,6 @@ Assume the XML file:
 </webstore>
 ````
 
-You instantiate the parser by passing path to XML file or an IO-like object and object-identyfing tag name as its arguments.
-
 The following will parse the XML, find product definitions (inside `<product>` and `</product>` tags), build `Hash`es and yield them inside the block.
 
 Usage with a file path:
@@ -119,6 +144,18 @@ webstore = Saxy.parse("filename.xml", "webstore").first
 webstore[:products][:product].size # => 2
 ````
 
+## Debugging
+
+Invalid XML files happen a lot and error messages are not always extremely helpful. In case of a parsing error, some additional information can be retrieved from parser's context.
+
+```ruby
+  begin
+    Saxy.parse(...) { ... }
+  rescue e => Saxy::ParsingError
+    puts "#{e.message} at #{e.context.line} line and #{e.context.column}"
+  end
+```
+
 ## Contributing
 
 1. Fork it
@@ -126,3 +163,11 @@ webstore[:products][:product].size # => 2
 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
+
+## License
+
+See `LICENSE.txt` file.
+
+## Author
+
+Michał Szajbe, [@szajbus](https://twitter.com/szajbus), [szajbe.pl](http://szajbe.pl)

data/lib/saxy/parser.rb

@@ -16,10 +16,15 @@ module Saxy
     # Will yield objects inside the callback after they're built
     attr_reader :callback
 
-    def initialize(object, object_tag, encoding=nil)
-      @object, @object_tag = object, object_tag
+    # Parser context
+    attr_reader :context
+
+    # Parser options
+    attr_reader :options
+
+    def initialize(object, object_tag, options={})
+      @object, @object_tag, @options = object, object_tag, options
       @tags, @elements = [], []
-      @encoding = encoding
     end
 
     def start_element(tag, attributes=[])
@@ -56,7 +61,7 @@ module Saxy
     end
 
     def error(message)
-      raise ParsingError.new(message)
+      raise ParsingError.new(message, context)
     end
 
     def current_element
@@ -68,15 +73,25 @@ module Saxy
 
       @callback = blk
 
-      args = [self, @encoding].compact
+      args = [self, options[:encoding]].compact
 
       parser = Nokogiri::XML::SAX::Parser.new(*args)
 
       if @object.respond_to?(:read) && @object.respond_to?(:close)
-        parser.parse_io(@object)
+        parser.parse_io(@object, &context_blk)
       else
-        parser.parse_file(@object)
+        parser.parse_file(@object, &context_blk)
       end
     end
+
+    def context_blk
+      proc { |context|
+        [:recovery, :replace_entities].each do |key|
+          context.send("#{key}=", options[key]) if options.has_key?(key)
+        end
+
+        @context = context
+      }
+    end
   end
 end

data/lib/saxy/parsing_error.rb

@@ -1,4 +1,10 @@
 module Saxy
-  class ParsingError < ::Exception
+  class ParsingError < ::StandardError
+    attr_reader :context
+
+    def initialize(message, context)
+      @context = context
+      super(message)
+    end
   end
-end
+end

data/lib/saxy/version.rb

@@ -1,3 +1,3 @@
 module Saxy
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

data/spec/fixtures/invalid.xml

@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<webstore>
+  <products>
+    <product>
+      <uid>FFCF177</uid>
+      <name>No closing tag...
+    </product>
+  </products>
+</webstore>

data/spec/saxy/parser_spec.rb

@@ -3,7 +3,8 @@ require 'spec_helper'
 describe Saxy::Parser do
   include FixturesHelper
 
-  let(:parser) { Saxy::Parser.new(fixture_file("webstore.xml"), "product", "UTF-8") }
+  let(:parser) { Saxy::Parser.new(fixture_file("webstore.xml"), "product") }
+  let(:invalid_parser) { Saxy::Parser.new(fixture_file("invalid.xml"), "product") }
   let(:file_io) { File.new(fixture_file("webstore.xml")) }
   let(:io_like) { IOLike.new(file_io) }
 
@@ -19,11 +20,18 @@ describe Saxy::Parser do
   end
 
   it "should accept optional force-encoding" do
-    parser = Saxy::Parser.new(file_io, "product", 'UTF-8')
+    parser = Saxy::Parser.new(file_io, "product", encoding: "UTF-8")
     expect(Nokogiri::XML::SAX::Parser).to receive(:new).with(parser, "UTF-8").and_call_original
     expect(parser.each.to_a.size).to eq(2)
   end
 
+  it "should pass options to parser context" do
+    parser = Saxy::Parser.new(file_io, "product", recovery: true, replace_entities: true)
+    parser.each.to_a
+    expect(parser.context.recovery).to be_truthy
+    expect(parser.context.replace_entities).to be_truthy
+  end
+
   it "should accept an IO-like for parsing" do
     parser = Saxy::Parser.new(io_like, "product")
     expect(parser.each.to_a.size).to eq(2)
@@ -158,7 +166,11 @@ describe Saxy::Parser do
   end
 
   it "should raise Saxy::ParsingError on error" do
-    expect { parser.error("Error message.") }.to raise_error(Saxy::ParsingError, "Error message.")
+    expect { invalid_parser.each.to_a }.to raise_error { |error|
+      expect(error).to be_a(Saxy::ParsingError)
+      expect(error.message).to match(/Opening and ending tag mismatch/)
+      expect(error.context).to be_a(Nokogiri::XML::SAX::ParserContext)
+    }
   end
 
   it "should return Enumerator when calling #each without a block" do

data/spec/spec_helper.rb

@@ -3,4 +3,4 @@ require 'bundler/setup'
 require 'saxy'
 
 require 'fixtures_helper'
-require File.join(File.dirname(__FILE__), 'fixtures', 'io_like')
+require 'support/io_like'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saxy
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Michał Szajbe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-20 00:00:00.000000000 Z
+date: 2017-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -66,6 +66,7 @@ files:
 - ".rspec"
 - ".travis.yml"
 - Appraisals
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -78,13 +79,14 @@ files:
 - lib/saxy/parsing_error.rb
 - lib/saxy/version.rb
 - saxy.gemspec
-- spec/fixtures/io_like.rb
+- spec/fixtures/invalid.xml
 - 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
+- spec/support/io_like.rb
 homepage: http://github.com/humante/saxy
 licenses: []
 metadata: {}
@@ -110,10 +112,11 @@ specification_version: 4
 summary: Memory-efficient XML parser. Finds object definitions and translates them
   into Ruby objects.
 test_files:
-- spec/fixtures/io_like.rb
+- spec/fixtures/invalid.xml
 - 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
+- spec/support/io_like.rb