README.md in sax-machine-0.2.1 vs README.md in sax-machine-0.3.0

- old
+ new

@@ -1,93 +1,164 @@ -# SAX Machine [![Build Status](https://secure.travis-ci.org/pauldix/sax-machine.png?branch=master)](http://travis-ci.org/pauldix/sax-machine) +# SAX Machine -[Wiki](https://github.com/pauldix/sax-machine/wiki) +## Status +[![Gem Version](https://badge.fury.io/rb/sax-machine.svg)](http://badge.fury.io/rb/sax-machine) +[![Build Status](https://secure.travis-ci.org/pauldix/sax-machine.svg?branch=master)](http://travis-ci.org/pauldix/sax-machine?branch=master) +[![Coverage Status](https://img.shields.io/coveralls/pauldix/sax-machine.svg)](https://coveralls.io/r/pauldix/sax-machine?branch=master) +[![Code Climate](https://img.shields.io/codeclimate/github/pauldix/sax-machine.svg)](https://codeclimate.com/github/pauldix/sax-machine) +[![Dependencies](https://gemnasium.com/pauldix/sax-machine.svg)](https://gemnasium.com/pauldix/sax-machine) + ## Description -A declarative SAX parsing library backed by Nokogiri +A declarative SAX parsing library backed by Nokogiri or Ox. +## Installation + +Add this line to your application's Gemfile: + +```ruby +gem 'sax-machine' +``` + +And then execute: + +```bash +$ bundle +``` + ## Usage + +To use **Nokogiri** as a SAX handler: + ```ruby require 'sax-machine' +``` -# Class for information associated with content parts in a feed. -# Ex: <content type="text">sample</content> -# instance.type will be "text", instance.text will be "sample" +To use **Ox** as a SAX handler: + +Add this line to your application's Gemfile: + +```ruby +gem 'ox', '>= 2.1.2' +``` + +Tell SAXMachine to use Ox: + +```ruby +require 'sax-machine' +SAXMachine.handler = :ox +``` + +Please note that this operation is not thread-safe, so it's better to define +handler at initialization stage and do not change it during runtime. + +## Examples + +Include `SAXMachine` in any class and define properties to parse: + +```ruby class AtomContent include SAXMachine attribute :type value :text end -# Class for parsing an atom entry out of a feedburner atom feed class AtomEntry include SAXMachine element :title - # the :as argument makes this available through atom_entry.author instead of .name - element :name, :as => :author - element "feedburner:origLink", :as => :url + # The :as argument makes this available through entry.author instead of .name + element :name, as: :author + element "feedburner:origLink", as: :url element :summary - element :content, :class => AtomContent + element :content, class: AtomContent element :published ancestor :ancestor end -# Class for parsing Atom feeds class Atom include SAXMachine element :title - # the :with argument means that you only match a link tag that has an attribute of :type => "text/html" - # the :value argument means that instead of setting the value to the text between the tag, - # it sets it to the attribute value of :href - element :link, :value => :href, :as => :url, :with => {:type => "text/html"} - element :link, :value => :href, :as => :feed_url, :with => {:type => "application/atom+xml"} - elements :entry, :as => :entries, :class => AtomEntry + # The :with argument means that you only match a link tag + # that has an attribute of type: "text/html" + element :link, value: :href, as: :url, with: { + type: "text/html" + } + # The :value argument means that instead of setting the value + # to the text between the tag, it sets it to the attribute value of :href + element :link, value: :href, as: :feed_url, with: { + type: "application/atom+xml" + } + elements :entry, as: :entries, class: AtomEntry end +``` -# you can then parse like this +Then parse any XML with your class: + +```ruby feed = Atom.parse(xml_text) -# then you're ready to rock -feed.title # => whatever the title of the blog is -feed.url # => the main url of the blog -feed.feed_url # => goes to the feedburner feed -feed.entries.first.title # => title of the first entry -feed.entries.first.author # => the author of the first entry -feed.entries.first.url # => the permalink on the blog for this entry -feed.entries.first.ancestor # => the Atom ancestor -# etc ... +feed.title # Whatever the title of the blog is +feed.url # The main URL of the blog +feed.feed_url # The URL of the blog feed -# you can also use the elements method without specifying a class like so -class SomeServiceResponse +feed.entries.first.title # Title of the first entry +feed.entries.first.author # The author of the first entry +feed.entries.first.url # Permalink on the blog for this entry +feed.entries.first.ancestor # The Atom ancestor +feed.entries.first.content # Instance of AtomContent +feed.entries.first.content.text # Entry content text +``` + +You can also use the elements method without specifying a class: + +```ruby +class ServiceResponse include SAXMachine - elements :message, :as => :messages + elements :message, as: :messages end -response = SomeServiceResponse.parse("<response><message>hi</message><message>world</message></response>") -response.messages.first # => "hi" -response.messages.last # => "world" +response = ServiceResponse.parse(" + <response> + <message>hi</message> + <message>world</message> + </response> +") +response.messages.first # hi +response.messages.last # world +``` -# To limit conflicts in the class used for mappping, you can use the alternate SAXMachine.configure syntax +To limit conflicts in the class used for mappping, you can use the alternate +`SAXMachine.configure` syntax: +```ruby class X < ActiveRecord::Base - # this way no element, elements or ancestor method will be added to X + # This way no element, elements or ancestor method will be added to X SAXMachine.configure(X) do |c| c.element :title end end ``` +## Contributing + +1. Fork it +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 + ## LICENSE The MIT License -Copyright (c) 2009-2012: +Copyright (c) 2009-2014: * [Paul Dix](http://www.pauldix.net) * [Julien Kirch](http://www.archiloque.net) * [Ezekiel Templin](http://zeke.templ.in) +* [Dmitry Krasnoukhov](http://krasnoukhov.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, @@ -102,6 +173,6 @@ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.