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 [](http://travis-ci.org/pauldix/sax-machine)
+# SAX Machine
-[Wiki](https://github.com/pauldix/sax-machine/wiki)
+## Status
+[](http://badge.fury.io/rb/sax-machine)
+[](http://travis-ci.org/pauldix/sax-machine?branch=master)
+[](https://coveralls.io/r/pauldix/sax-machine?branch=master)
+[](https://codeclimate.com/github/pauldix/sax-machine)
+[](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.