Skip to content
A fast, libxml based, Ruby Atom library supporting the Syndication Format and the Publishing Protocol. <br> Gem is available now!!<br>
Ruby JavaScript
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= rAtom

rAtom is a library for working with the Atom Syndication Format and
the Atom Publishing Protocol (APP).

* Built using libxml so it is _much_ faster than a REXML based library.
* Uses the libxml pull parser so it has much lighter memory usage.
* Supports {RFC 5005}[] for feed pagination.

rAtom was originally built to support the communication between a number of applications
built by Peerworks[], via the Atom Publishing protocol.  However, it 
supports, or aims to support, all the Atom Syndication Format and Publication Protocol
and can be used to access Atom feeds or to script publishing entries to a blog supporting APP.

== Prerequisites

* libxml-ruby, =
* rspec (Only required for tests)

libxml-ruby in turn requires the libxml2 library to be installed. libxml2 can be downloaded
from or installed using whatever tools are provided by your
platform.  At least version 2.6.31 is required.

=== Mac OSX

Mac OSX by default comes with an old version of libxml2 that will not work with rAtom. You
will need to install a more recent version.  If you are using Macports:

  port install libxml2

== Installation

You can install via gem using:

  gem install ratom
== Usage

To fetch a parse an Atom Feed you can simply:

  feed = Atom::Feed.load_feed(URI.parse(""))
And then iterate over the entries in the feed using:

  feed.each_entry do |entry|
    # do cool stuff
To construct a Feed

  feed = do |feed|
    feed.title = "My Cool Feed" = ""
    feed.updated =
To output a Feed as XML use to_xml

  > puts feed.to_xml
  <?xml version="1.0"?>
  <feed xmlns="">
    <title>My Cool Feed</title>

See Feed and Entry for details on the methods and attributes of those classes.

=== Publishing

To publish to a remote feed using the Atom Publishing Protocol, first you need to create a collection to publish to:

  require 'atom/pub'
  collection = => '')
Then create a new entry

  entry = do |entry|
    entry.title = "I have discovered rAtom"
    entry.authors << => 'A happy developer')
    entry.updated = = ""
    entry.content ="<p>rAtom lets me post to my blog using Ruby, how cool!</p>")
And publish it to the Collection:

  published_entry = collection.publish(entry)

Publish returns an updated entry filled out with any attributes to server may have set, including information
required to let us update to the entry.  For example, lets change the content and republished:

  published_entry.content ="<p>rAtom lets me post to and edit my blog using Ruby, how cool!</p>")
  published_entry.updated =!
You can also delete an entry using the <tt>destroy!</tt> method, but we won't do that will we?.


* Support partial content responses from the server.
* Support batching of protocol operations.
* Examples of editing existing entries.
* All my tests have been against internal systems, I'd really like feedback from those who have tried rAtom using existing blog software that supports APP.
* Handle all base uri tests.
* What to do with extension elements?
* Add slug support.

== Source Code

The source repository is accessible via GitHub:

  git clone git://

== Contact Information

The project page is at Please file any bugs or feedback
using the trackers and forums there.

== Authors and Contributors

rAtom was developed by Peerworks[] and written by Sean Geoghegan.

Something went wrong with that request. Please try again.