rAtom 0.3.5 released

This is just a maintenance release, nothing too exciting:

== 0.3.5 2008-05-03

* Make sure atom:entries appears last.
* Better examples in the documentation.

* Docs for Feed and Entry list attributes.
* Gave Feeds authors and contributors.
* Fixed a couple warnings.

Using rAtom in Rails

Some mysterious anonymous person asked me for a tutorial on using rAtom within Rails.  So I'll show you all how I do it.

Firstly, the big difference is that I treat it more like ActiveRecord#to_xml instead of like a *.builder view. So I'll start with an example.

Assuming you have a blog application with a Post model class, you can add a #to_atom method to your class like this:

class Post < ActiveRecord::Base  
  def to_atom
    Atom::Entry.new do |entry|
      entry.title     = self.title
      entry.updated   = self.updated_at
      entry.published = self.created_at
      entry.author    = Atom::Person.new(:name => self.author)
      entry.links    << Atom::Link.new(:rel => 'alternate', 
                                    :href => "/posts/#{self.id}")
      entry.content   = Atom::Content::Html.new(self.content)
    end
  end  
end

The advantage of returning a rAtom object here is that the atom representation is then composable, for example if you have a Blog class that has many posts you can do this:

class Blog < ActiveRecord::Base
  has_many :posts
  
  def to_atom
    Atom::Feed.new do |feed|
      feed.title = self.title
      feed.links << Atom::Link.new(:rel => 'alternate', 
                                :href => "/blogs/#{self.id}")
      
      self.posts.each do |post|
        feed.entries << post.to_atom
      end
    end
  end
end

To get this atom representation out via HTTP, you would do this in the controller:

class BlogsController << ApplicationController
  def show
    @blog = Blog.find(params[:id])
    respond_to do |format|
      format.atom { render :xml => @blog.to_atom.to_xml }
    end
  end
end

This has been really useful in an application that I am working on because we are using Atom as the main communication format between a bunch of different components, so this composability comes in really handy. For a simple blog it might be overkill, but at least you get the much better performance of libxml-ruby.

You'll probably notice a bit of ugliness in the to_atom methods, specifically this:

      entry.links    << Atom::Link.new(:rel => 'alternate', 
                                    :href => "/posts/#{self.id}")

The URL is hard-coded here because url_for is not available in a model. This is a bit of trade-off between the composability and strict MVC here, if you really wanted to you could pass the URL in as a parameter, or add a block that generates URLs or whatever, it's up to you.

For some applications, like a simple blog, the composability might not be too important, and you might prefer the syntax of atom_feed in Rails, or at least want to be able to render the atom in a view. In this case it would probably be nice to have a rAtom based template format, so you could add a view like "blogs/show.atom.ratom" which allowed you to move the to_atom method into a view and call url_for directly from the view. I'd like to add this at some stage, but it hasn't happened yet, due to time and priorities, but if anyone would like to submit a patch for it I'd gladly accept it.

rAtom 0.3.0 Released

I've just release rAtom 0.3.0. This version adds support for simple extension elements and also checks that content is in UTF-8 before serializing to XML.

As defined in the Atom Syndication Format, simple extension elements consist of XML elements from a non-Atom namespace that have no attributes or child elements, i.e. they are empty or only contain text content. These elements are treated as a name value pair where the element namespace and local name make up the key and the content of the element is the value, empty elements will be treated as an empty string.

To access extension elements use the [] method on the Feed or Entry. For example, if we are parsing the follow Atom document with extensions:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ex="http://example.org">
  <title>Feed with extensions</title>
  <ex:myelement>Something important</ex:myelement>
</feed>

We could then access the extension element on the feed using:

> feed["http://example.org", "myelement"]
  => ["Something important"]

Note that the return value is an array. This is because XML allows multiple instances of the element.

To set an extension element you append to the array:

> feed['http://example.org', 'myelement'] << 'Something less important'
=> ["Something important", "Something less important"]

You can then call to_xml and rAtom will serialize the extension elements into xml.

> puts feed.to_xml
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <myelement xmlns="http://example.org">Something important</myelement>
  <myelement xmlns="http://example.org">Something less important</myelement>
</feed>

Notice that the output repeats the xmlns attribute for each of the extensions, this is semantically the same the input XML, just a bit ugly. It seems to be a limitation of the libxml-Ruby API. But if anyone knows a work around I'd gladly accept a patch (or even advice).

You can get rAtom via gem:

> gem install ratom

or from Github.

rAtom 0.2.1 Gem released

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

rAtom was originally built to support the communication between a number of applications built by Peerworks[http://peerworks.org], 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.

Features:

• Uses libxml-ruby 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 (http://www.ietf.org/rfc/rfc5005.txt) for feed pagination.
  

You can install via gem using:
# sudo gem install ratom

Usage

To fetch and parse an Atom Feed you can simply:

feed = Atom::Feed.load_feed(URI.parse("http://example.com/feed.atom"))

And then iterate over the entries in the feed using:

feed.each_entry do |entry|
 # do cool stuff
end

To construct a Feed

feed = Atom::Feed.new do |feed|
 feed.title = "My Cool Feed"
 feed.id = "http://example.com/my_feed.atom"
 feed.updated = Time.now
end

To output a Feed as XML use to_xml

> puts feed.to_xml
<feed xmlns="http://www.w3.org/2005/Atom">
 <title>My Cool Feed</title>
 <id>http://example.com/my_feed.atom</id>
 <updated>2008-03-03T23:19:44+10:30</updated>
</feed>

Publishing

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

collection = Atom::Pub::Collection.new(:href => 'http://example.org/myblog')

Then create a new entry:

entry = Atom::Entry.new do |entry|
 entry.title = "I have discovered rAtom"
 entry.authors << name =""> 'A happy developer')
 entry.updated = Time.now
 entry.id = "http://example.org/myblog/newpost"
 entry.content = Atom::Content::Html.new("<p>rAtom lets me post to my blog using Ruby, how cool!</p>")
end

And publish it to the Collection:

published_entry = collection.publish(entry)

More Information

See http://ratom.rubyforge.org for more information.

Building Erlang with Rake

I've recently started using Erlang on a project. This is my first foray into Erlang and I'm using Joe Armstong's new book Programming Erlang as introductory material. It is a great introduction to the language, although I wish it covered more of the OTP. I suppose there is the OTP Design Principles guide but sometimes a good paper book written in conversational style is better when you are learning.

In the book Joe describes building an Erlang project using make and most of the downloadable bits of Erlang code use make too; this makes sense, make is virtually ubiquitous. However the other components of this project are Ruby on Rails applications and make heavy use of Rake, so I figure why subject myself to Make when I can use the beautiful Rake.

Here is my Rakefile for building an Erlang project.

require 'rake/clean'

INCLUDE = "include"
ERLC_FLAGS = "-I#{INCLUDE} +warn_unused_vars +warn_unused_import"

SRC = FileList['src/*.erl']
OBJ = SRC.pathmap("%{src,ebin}X.beam")
CLEAN.include("ebin/*.beam")

directory 'ebin'

rule ".beam" =>  ["%{ebin,src}X.erl"] do |t|
  sh "erlc -pa ebin -W #{ERLC_FLAGS} -o ebin #{t.source}"
end

task :compile => ['ebin'] + OBJ
task :default => :compile

This gives you rake compile which builds all the .erl files in the src subdirectory into the .beam files in the ebin directory. Files will only be built if they have changes since the last build. You also get rake clean which deletes all the .beam files from the ebin directory.

I much prefer this over the equivalent Makefile and it is much easier to extend since you have the full power of Ruby at your disposal.

Enjoy.

Update: Fixed bug when compile many files from after clean.

Testing ActiveResource

I recently started using ActiveResource on a project. ActiveResource is the client side of the REST picture, that is it can consume the REST style web services you get with Rails, think of it as ActiveRecord for HTTP.

One of the difficult parts of using ActiveResource is testing. You don't want to run it over a real HTTP connection, for one it would significantly slow down your tests and secondly you don't know what horrible side effects it might have. So you need some way to fake a HTTP connection and HTTP requests and responses. Enter the HttpMock class.

HttpMock is a fairly nice class put together by the Rails folk that allows you to register a bunch of request and response pairs for a fake HTTP connection. When you call a method on an ActiveResource in a test, it calls the HttpMock class instead of trying to create a real connection. It is fairly easy to use, although there is no documentation the blogging community has come to the rescue.

Here is a quick example:

  @matz  = { :id => 1, :name => 'Matz' }.to_xml(:root => 'person')
  ActiveResource::HttpMock.respond_to do |mock|
    mock.get "/people/1.xml", {}, @matz
  end

This creates a request response pair so that when ActiveResource tries to GET /people/1.xml it gets back the xml for the @matz hash. Pretty simple.

However there is a problem. HttpMock is misnamed - HttpMock is a stub not a mock. But the difference is more than semantic, a mock object, like those provided by the excellent Mocha library, will allow you to set expectations on a object. An expectation is like saying "for this test to pass, this method with these arguments must be called on this object". HttpMock doesn't do that, instead it is just a stub that returns a value when a method is called with a certain argument, there is no verification that the method is actually called.

To show why this is bad, lets look at the test for resource deletion from the ActiveResource unit tests themselves.

Firstly, in the setup method we use HttpMock to create response for the delete method used on the "/people/1.xml" path:

  ActiveResource::HttpMock.respond_to do |mock|
    mock.delete "/people/1.xml", {}, nil, 200
  end

And here is the test_delete method:

    1   def test_delete
    2     assert Person.delete(1)
    3     ActiveResource::HttpMock.respond_to do |mock|
    4       mock.get "/people/1.xml", {}, nil, 404
    5     end
    6     assert_raises(ActiveResource::ResourceNotFound) { Person.find(1) }
    7   end

So what is happening here? Firstly on line 2 of the test_delete method we call the Person classes delete method. The delete method is a nice one-liner:

      def delete(id, options = {})
        connection.delete(element_path(id, options))
      end

We can assume here that the the content of the delete method is sending a delete request to "/people/#{id}.xml", that makes sense. The rest of the test_delete method creates a request response pair that returns a 404 error when "/people/1.xml" is requested, all that does is test that ActiveResource::Base.find correctly handles 404.

So what ensures that the delete method does the right thing, all the test does is ensure that it returns something other than nil or false. Lets change the method and see if we can break the test. We'll just return true in the delete method:

      def delete(id, options = {})
        true
      end

After this change I re-ran the tests and they all passed. This can't be good. If you can effectively remove the body of a method you are testing and the tests still pass you don't have a very good test. So how can we fix it?

Well if HttpMock was truely a mock we could ensure that the HTTP delete method is called on the "/people/1.xml" path. Fortunately HttpMock stores every request it recieves in a class variable. So we can check that the request was received with an assertion.

Here is a new test_delete:

  def test_delete
    assert Person.delete(1)
    assert ActiveResource::HttpMock.requests.include?(ActiveResource::Request.new(:delete, "/people/1.xml", nil, {}))
  end

This one now fails when the body of the delete method is removed and passes when it is put back in, so this way we know that the tests is actually testing the functionality of the method. However it is a bit ugly isn't it? It would be nice if HttpMock allowed you to do this:

    ActiveResource::HttpMock.expects do |http|
      http.delete "/people/1.xml", {}, nil, 200
    end

But I'll leave that for another blog post.

Index Ruby Objects by an Attribute

class Array
  def hash_by(attribute)
    self.inject({}) do |hash, e|
      hash[e.send(attribute)] = e
      hash
    end
  end
end