Project

saxy

No commit activity in last 3 years
No release in over 3 years
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 through it and yields objects along the way.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

 Project Readme

Saxy

Gem Version Build Status

Memory-efficient XML parser. Finds object definitions in XML and translates them into Ruby hashes.

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 hashes 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.

Installation

Add this line to your application's Gemfile:

gem 'saxy'

And then execute:

$ bundle

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

See ruby-1.8 branch. Install with:

gem 'saxy', '~> 0.3.0'

Ruby 1.9.2 support

See ruby-1.9.2 branch. Install with:

gem 'saxy', '~> 0.4.0'

Changelog

See CHANGELOG.md file.

Usage

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.

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).

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.
  • error_handler - If set to a callable, parser will call it with any error it encounters instead of raising exceptions.

Combination of error_handler and recovery options allows for continued processing when encountering recoverable errors (e.g. unescaped predefined entities).

error_handler = proc { |e| $stderr.puts "#{e.message} at line #{e.context.line}, column #{e.context.column}." }
Saxy.parse(path_or_io, object_tag, error_handler: error_handler, recovery: true) { ... }

Example

Assume the XML file (an imaginary product feed):

<?xml version='1.0' encoding='UTF-8'?>
<webstore>
  <name>Amazon</name>
  <products>
    <product>
      <name>Kindle - The world's best-selling e-reader.</name>
      <images>
        <thumbSize width="80" height="60">http://amazon.com/kindle_thumb.jpg</thumbSize>
      </images>
    </product>
    <product>
      <name>Kindle Touch - Simple-to-use touchscreen with built-in WIFI.</name>
      <images>
        <thumbSize width="120" height="90">http://amazon.com/kindle_touch_thumb.jpg</thumbSize>
      </images>
    </product>
  </products>
</webstore>

The following will parse the XML, find product definitions (inside <product> and </product> tags), build Hashes and yield them inside the block.

Usage with a file path:

Saxy.parse("filename.xml", "product").each do |product|
  puts product["name"]
  puts product["images"]["thumb_size"]["contents"]
  puts "#{product["images"]["thumb_size"]["width"]}x#{product["images"]["thumb_size"]["height"]}"
end

# =>
"Kindle - The world's best-selling e-reader."
"http://amazon.com/kindle_thumb.jpg"
"80x60"
"Kindle Touch - Simple-to-use touchscreen with built-in WIFI."
"http://amazon.com/kindle_touch_thumb.jpg"
"120x90"

Usage with an IO-like object ARGF or $stdin:

# > cat filename.xml | ruby this_script.rb
Saxy.parse(ARGF, "product").each do |product|
  puts product["name"]
end

# =>
"Kindle - The world's best-selling e-reader."

Saxy supports Enumerable, so you can use its goodies to your comfort without building intermediate arrays:

Saxy.parse("filename.xml", "product").map do |object|
  # map yielded Hash 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
lazy       = Saxy.parse("filename.xml", "product").lazy # Ruby 2.0

Multiple definitions of child objects are grouped in arrays:

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.

  begin
    Saxy.parse(...) { ... }
  rescue e => Saxy::ParsingError
    puts "#{e.message} at #{e.context.line} line and #{e.context.column}"
  end

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

License

See LICENSE.txt file.

Author

MichaƂ Szajbe, @szajbus, szajbe.pl