ratom 0.2.1

data/History.txt

@@ -0,0 +1,7 @@
+== 0.2.1 2008-03-03
+
+* Initial release to the public.
+
+== < 0.2.1
+
+* Internal releases.

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Peerworks
+
+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,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+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.

data/Manifest.txt

@@ -0,0 +1,52 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/atom.rb
+lib/atom/pub.rb
+lib/atom/version.rb
+lib/atom/xml/parser.rb
+setup.rb
+spec/app/member_entry.atom
+spec/app/service.xml
+spec/atom/pub_spec.rb
+spec/atom_spec.rb
+spec/conformance/baseuri.atom
+spec/conformance/divtest.atom
+spec/conformance/linktests.xml
+spec/conformance/nondefaultnamespace-baseline.atom
+spec/conformance/nondefaultnamespace-xhtml.atom
+spec/conformance/nondefaultnamespace.atom
+spec/conformance/ordertest.xml
+spec/conformance/title/html-cdata.atom
+spec/conformance/title/html-entity.atom
+spec/conformance/title/html-ncr.atom
+spec/conformance/title/text-cdata.atom
+spec/conformance/title/text-entity.atom
+spec/conformance/title/text-ncr.atom
+spec/conformance/title/xhtml-entity.atom
+spec/conformance/title/xhtml-ncr.atom
+spec/conformance/unknown-namespace.atom
+spec/conformance/xmlbase.atom
+spec/fixtures/complex_single_entry.atom
+spec/fixtures/created_entry.atom
+spec/fixtures/entry.atom
+spec/fixtures/multiple_entry.atom
+spec/fixtures/simple_single_entry.atom
+spec/paging/first_paged_feed.atom
+spec/paging/last_paged_feed.atom
+spec/paging/middle_paged_feed.atom
+spec/spec.opts
+spec/spec_helper.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,123 @@
+= 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}[http://www.ietf.org/rfc/rfc5005.txt] for feed pagination.
+
+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.
+
+== Prerequisites
+
+* ActiveSupport, >= 2.0.1
+* libxml-ruby, = 0.5.2.0
+* rspec (Only required for tests)
+
+libxml-ruby in turn requires the libxml2 library to be installed. libxml2 can be downloaded
+from http://xmlsoft.org/downloads.html 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("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
+  <?xml version="1.0"?>
+  <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>
+
+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 = 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 << Atom::Person.new(: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)
+
+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 =  Atom::Content::Html.new("<p>rAtom lets me post to and edit my blog using Ruby, how cool!</p>")
+  published_entry.updated = Time.now
+  published_entry.save!
+  
+You can also delete an entry using the <tt>destroy!</tt> method, but we won't do that will we?.
+    
+
+== TODO
+
+* 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.
+
+== Source Code
+
+The source repository is accessible via GitHub:
+
+  git clone git://github.com/seangeo/ratom.git
+
+== Contact Information
+
+The project page is at http://rubyforge.org/projects/ratom. Please file any bugs or feedback
+using the trackers and forums there.
+
+== Authors and Contributors
+
+rAtom was developed by Peerworks[http://peerworks.org] and written by Sean Geoghegan.
+

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,72 @@
+require 'atom/version'
+
+AUTHOR = 'Peerworks'  # can also be an array of Authors
+EMAIL = "info@peerworks.org"
+DESCRIPTION = "Atom Syndication and Publication API"
+GEM_NAME = 'ratom' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'ratom' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "sgeo"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Atom::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'atom documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  p.extra_deps = [['activesupport', '>= 2.0.1'], ['libxml-ruby', '= 0.5.2.0']]     
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = RUBYFORGE_PROJECT
+hoe.remote_rdoc_dir = PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,'')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'atom'

data/lib/atom.rb

@@ -0,0 +1,566 @@
+# Copyright (c) 2008 The Kaphan Foundation
+#
+# For licensing information see LICENSE.txt.
+#
+
+require 'forwardable'
+require 'rubygems'
+require 'xml/libxml'
+require 'activesupport'
+require 'atom/xml/parser.rb'
+
+module Atom # :nodoc:
+  NAMESPACE = 'http://www.w3.org/2005/Atom' unless defined?(NAMESPACE)
+  
+  # Raised when a Parsing Error occurs.
+  class ParseError < StandardError; end
+      
+  # Represents a Generator as defined by the Atom Syndication Format specification.
+  #
+  # The generator identifies an agent or engine used to a produce a feed.
+  #
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.generator
+  class Generator
+    include Xml::Parseable
+    
+    attr_reader :name
+    attribute :uri, :version
+    
+    # Initialize a new Generator.
+    #
+    # +xml+:: An XML::Reader object.
+    #
+    def initialize(xml)
+      @name = xml.read_string.strip
+      parse(xml, :once => true)
+    end
+  end
+    
+  # Represents a Person as defined by the Atom Syndication Format specification.
+  #
+  # A Person is used for all author and contributor attributes.
+  #
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#atomPersonConstruct
+  #
+  class Person
+    include Xml::Parseable
+    element :name, :uri, :email
+   
+    # Initialize a new person.
+    #
+    # +o+:: An XML::Reader object or a hash. Valid hash keys are +:name+, +:uri+ and +:email+.
+    def initialize(o = {})
+      case o
+      when XML::Reader
+        o.read
+        parse(o)
+      when Hash
+        o.each do |k, v|
+          self.send("#{k.to_s}=", v)
+        end
+      end
+    end
+    
+    def inspect
+      "<Atom::Person name:'#{name}' uri:'#{uri}' email:'#{email}"
+    end
+  end
+    
+  class Content  # :nodoc:
+    def self.parse(xml)
+      case xml['type']
+      when "xhtml"
+        Xhtml.new(xml)
+      when "html"
+        Html.new(xml)
+      else
+        Text.new(xml)
+      end
+    end
+  
+    # This is the base class for all content within an atom document.
+    #
+    # Content can be Text, Html or Xhtml.
+    #
+    # A Content object can be treated as a String with type and xml_lang
+    # attributes.
+    #
+    # For a thorough discussion of atom content see 
+    # http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.content
+    class Base < DelegateClass(String)
+      include Xml::Parseable
+      attribute :type, :'xml:lang'
+            
+      def initialize(c)
+        __setobj__(c)
+      end
+      
+      def ==(o)
+        if o.is_a?(self.class)
+          self.type == o.type &&
+           self.xml_lang == o.xml_lang &&
+           self.to_s == o.to_s
+        elsif o.is_a?(String)
+          self.to_s == o
+        end
+      end
+            
+      protected
+      def set_content(c) # :nodoc:
+        __setobj__(c)
+      end
+    end
+    
+    # Text content within an Atom document.
+    class Text < Base
+      def initialize(xml)
+        super(xml.read_string)
+        parse(xml, :once => true)
+      end
+    end
+    
+    # Html content within an Atom document.
+    class Html < Base
+      
+      # Creates a new Content::Html.
+      #
+      # +o+:: An XML::Reader or a HTML string.
+      #
+      def initialize(o)
+        case o
+        when XML::Reader
+          super(o.read_string.gsub(/\s+/, ' ').strip)
+          parse(o, :once => true)
+        when String
+          super(o)
+          @type = 'html'
+        end        
+      end
+      
+      def to_xml(nodeonly = true, name = 'content') # :nodoc:
+        node = XML::Node.new(name)
+        node << self.to_s
+        node['type'] = 'html'
+        node['xml:lang'] = self.xml_lang        
+        node
+      end
+    end
+    
+    # XHTML content within an Atom document.
+    class Xhtml < Base
+      XHTML = 'http://www.w3.org/1999/xhtml'
+      
+      def initialize(xml)        
+        parse(xml, :once => true)
+        starting_depth = xml.depth
+        
+        # Get the next element - should be a div according to the atom spec
+        while xml.read == 1 && xml.node_type != XML::Reader::TYPE_ELEMENT; end
+        
+        if xml.local_name == 'div' && xml.namespace_uri == XHTML
+          super(xml.read_inner_xml.strip.gsub(/\s+/, ' '))
+        else
+          super(xml.read_outer_xml)
+        end
+        
+        # get back to the end of the element we were created with
+        while xml.read == 1 && xml.depth > starting_depth; end
+      end
+      
+      def to_xml(nodeonly = true, name = 'content')
+        node = XML::Node.new(name)
+        node['type'] = 'xhtml'
+        node['xml:lang'] = self.xml_lang
+        
+        div = XML::Node.new('div')        
+        div['xmlns'] = XHTML
+        div
+        
+        p = XML::Parser.string(to_s)
+        content = p.parse.root.copy(true)
+        div << content
+        
+        node << div
+        node
+      end
+    end
+  end
+   
+  # Represents a Source as defined by the Atom Syndication Format specification.
+  #
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.source
+  class Source
+    extend Forwardable
+    def_delegators :@links, :alternate, :self, :alternates, :enclosures
+    include Xml::Parseable
+    
+    element :id
+    element :updated, :class => Time, :content_only => true
+    element :title, :subtitle, :class => Content
+    elements :authors, :contributors, :class => Person
+    elements :links
+    
+    def initialize(xml)
+      unless current_node_is?(xml, 'source', NAMESPACE)
+        raise ArgumentError, "Invalid node for atom:source - #{xml.name}(#{xml.namespace})"
+      end
+      
+      @authors, @contributors, @links = [], [], Links.new
+      
+      xml.read
+      parse(xml)
+    end
+  end
+  
+  # Represents a Feed as defined by the Atom Syndication Format specification.
+  #
+  # A feed is the top level element in an atom document.  It is a container for feed level
+  # metadata and for each entry in the feed.
+  #
+  # This supports pagination as defined in RFC 5005, see http://www.ietf.org/rfc/rfc5005.txt
+  # 
+  # == Parsing
+  #
+  # A feed can be parsed using the Feed.load_feed method. This method accepts a String containing
+  # a valid atom document, an IO object, or an URI to a valid atom document. For example:
+  #
+  #   # Using a File
+  #   feed = Feed.load_feed(File.open("/path/to/myfeed.atom"))
+  #
+  #   # Using a URL
+  #   feed = Feed.load_feed(URI.parse("http://example.org/afeed.atom"))
+  # 
+  # == Encoding
+  #
+  # A feed can be converted to XML using, the to_xml method that returns a valid atom document in a String.
+  #
+  # == References
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.feed
+  class Feed
+    include Xml::Parseable
+    extend Forwardable
+    def_delegators :@links, :alternate, :self, :via, :first_page, :last_page, :next_page, :prev_page
+        
+    loadable! 
+    
+    element :id, :rights
+    element :generator, :class => Generator
+    element :title, :subtitle, :class => Content
+    element :updated, :published, :class => Time, :content_only => true
+    elements :links, :entries
+    
+    # Initialize a Feed.
+    #
+    # This will also yield itself, so a feed can be constructed like this:
+    #
+    #   feed = Feed.new do |feed|
+    #     feed.title = "My Cool feed"
+    #   end
+    # 
+    # +o+:: An XML Reader or a Hash of attributes.
+    #
+    def initialize(o = {})
+      @links, @entries = Links.new, []
+      
+      case o
+      when XML::Reader
+        if next_node_is?(o, 'feed', Atom::NAMESPACE)
+          o.read
+          parse(o)
+        else
+          raise ArgumentError, "XML document was missing atom:feed: #{o.read_outer_xml}"
+        end
+      when Hash
+        o.each do |k, v|
+          self.send("#{k.to_s}=", v)
+        end
+      end
+      
+      yield(self) if block_given?
+    end
+    
+    # Return true if this is the first feed in a paginated set.
+    def first?
+      links.self == links.first_page
+    end 
+    
+    # Returns true if this is the last feed in a paginated set.
+    def last?
+      links.self == links.last_page
+    end
+    
+    # Reloads the feed by fetching the self uri.
+    def reload!
+      if links.self
+        Feed.load_feed(URI.parse(links.self.href))
+      end
+    end
+    
+    # Iterates over each entry in the feed.
+    #
+    # ==== Options
+    #
+    # +paginate+::  If true and the feed supports pagination this will fetch each page of the feed.
+    # +since+::     If a Time object is provided each_entry will iterate over all entries that were updated since that time.
+    #
+    def each_entry(options = {}, &block)
+      if options[:paginate]
+        since_reached = false
+        feed = self
+        loop do          
+          feed.entries.each do |entry|
+            if options[:since] && entry.updated && options[:since] > entry.updated
+              since_reached = true
+              break
+            else
+              block.call(entry)
+            end
+          end
+          
+          if since_reached || feed.next_page.nil?
+            break
+          else feed.next_page
+            feed = feed.next_page.fetch 
+          end
+        end
+      else
+        self.entries.each(&block)
+      end
+    end
+  end
+  
+  # Represents an Entry as defined by the Atom Syndication Format specification.
+  #
+  # An Entry represents an individual entry within a Feed.
+  #
+  # == Parsing
+  #
+  # An Entry can be parsed using the Entry.load_entry method. This method accepts a String containing
+  # a valid atom entry document, an IO object, or an URI to a valid atom entry document. For example:
+  #
+  #   # Using a File
+  #   entry = Entry.load_entry(File.open("/path/to/myfeedentry.atom"))
+  #
+  #   # Using a URL
+  #   Entry = Entry.load_entry(URI.parse("http://example.org/afeedentry.atom"))
+  # 
+  # The document must contain a stand alone entry element as described in the Atom Syndication Format.
+  # 
+  # == Encoding
+  #
+  # A Entry can be converted to XML using, the to_xml method that returns a valid atom entry document in a String.
+  #
+  # == References
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry
+  class Entry
+    include Xml::Parseable
+    extend Forwardable
+    def_delegators :@links, :alternate, :self, :alternates, :enclosures, :edit_link, :via
+    
+    loadable!
+    element :title, :id, :summary
+    element :updated, :published, :class => Time, :content_only => true
+    element :content, :class => Content
+    element :source, :class => Source
+    elements :links
+    elements :authors, :contributors, :class => Person
+        
+    # Initialize an Entry.
+    #
+    # This will also yield itself, so an Entry can be constructed like this:
+    #
+    #   entry = Entry.new do |entry|
+    #     entry.title = "My Cool entry"
+    #   end
+    # 
+    # +o+:: An XML Reader or a Hash of attributes.
+    #
+    def initialize(o = {})
+      @links = Links.new
+      @authors = []
+      @contributors = []
+      
+      case o
+      when XML::Reader
+        if current_node_is?(o, 'entry', Atom::NAMESPACE) || next_node_is?(o, 'entry', Atom::NAMESPACE)
+          o.read
+          parse(o)
+        else
+          raise ArgumentError, "Entry created with node other than atom:entry: #{o.name}"
+        end
+      when Hash
+        o.each do |k,v|
+          send("#{k.to_s}=", v)
+        end
+      end
+
+      yield(self) if block_given?
+    end   
+    
+    # Reload the Entry by fetching the self link.
+    def reload!
+      if links.self
+        Entry.load_entry(URI.parse(links.self.href))
+      end
+    end
+  end
+
+  # Links provides an Array of Link objects belonging to either a Feed or an Entry.
+  #
+  # Some additional methods to get specific types of links are provided.
+  #
+  # == References
+  # 
+  # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link
+  # for details on link selection and link attributes.
+  #
+  class Links < DelegateClass(Array)
+    include Enumerable
+    
+    # Initialize an empty Links array.
+    def initialize
+      super([])
+    end
+    
+    # Get the alternate.
+    #
+    # Returns the first link with rel == 'alternate' that matches the given type.
+    def alternate(type = nil)
+      detect { |link| (link.rel.nil? || link.rel == Link::Rel::ALTERNATE) && (type.nil? || type == link.type) }
+    end
+    
+    # Get all alternates.
+    def alternates
+      select { |link| link.rel.nil? || link.rel == Link::Rel::ALTERNATE }
+    end
+    
+    # Gets the self link.
+    def self
+      detect { |link| link.rel == Link::Rel::SELF }
+    end
+    
+    # Gets the via link.
+    def via
+      detect { |link| link.rel == Link::Rel::VIA }
+    end
+    
+    # Gets all links with rel == 'enclosure'
+    def enclosures
+      select { |link| link.rel == Link::Rel::ENCLOSURE }
+    end
+    
+    # Gets the link with rel == 'first'.
+    #
+    # This is defined as the first page in a pagination set.
+    def first_page
+      detect { |link| link.rel == Link::Rel::FIRST }
+    end
+    
+    # Gets the link with rel == 'last'.
+    #
+    # This is defined as the last page in a pagination set.
+    def last_page
+      detect { |link| link.rel == Link::Rel::LAST }
+    end
+    
+    # Gets the link with rel == 'next'.
+    #
+    # This is defined as the next page in a pagination set.
+    def next_page
+      detect { |link| link.rel == Link::Rel::NEXT }
+    end
+    
+    # Gets the link with rel == 'prev'.
+    #
+    # This is defined as the previous page in a pagination set.
+    def prev_page
+      detect { |link| link.rel == Link::Rel::PREVIOUS }
+    end
+    
+    # Gets the edit link.
+    #
+    # This is the link which can be used for posting updates to an item using the Atom Publishing Protocol.
+    #
+    def edit_link
+      detect { |link| link.rel == 'edit' }
+    end
+  end
+  
+  # Represents a link in an Atom document.
+  #
+  # A link defines a reference from an Atom document to a web resource.
+  #
+  # == References
+  # See http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.link for
+  # a description of the different types of links.
+  #
+  class Link
+    module Rel # :nodoc:
+      ALTERNATE = 'alternate'
+      SELF = 'self'
+      VIA = 'via'
+      ENCLOSURE = 'enclosure'
+      FIRST = 'first'
+      LAST = 'last'
+      PREVIOUS = 'prev'
+      NEXT = 'next'
+    end    
+    
+    include Xml::Parseable
+    attribute :href, :rel, :type, :length
+        
+    # Create a link.
+    #
+    # +o+:: An XML::Reader containing a link element or a Hash of attributes.
+    #
+    def initialize(o)
+      case o
+      when XML::Reader
+        if current_node_is?(o, 'link')
+          parse(o, :once => true)
+        else
+          raise ArgumentError, "Link created with node other than atom:link: #{o.name}"
+        end
+      when Hash
+        [:href, :rel, :type, :length].each do |attr|
+          self.send("#{attr}=", o[attr])
+        end
+      else
+        raise ArgumentError, "Don't know how to handle #{o}"
+      end        
+    end
+    
+    def length=(v)
+      @length = v.to_i
+    end
+    
+    def to_s
+      self.href
+    end
+    
+    def ==(o)
+      o.respond_to?(:href) && o.href == self.href
+    end
+    
+    # This will fetch the URL referenced by the link.
+    #
+    # If the URL contains a valid feed, a Feed will be returned, otherwise,
+    # the body of the response will be returned.
+    #
+    # TODO: Handle redirects.
+    #
+    def fetch
+      content = Net::HTTP.get_response(URI.parse(self.href)).body
+      
+      begin
+        Atom::Feed.load_feed(content)
+      rescue ArgumentError, ParseError => ae
+        content
+      end
+    end
+    
+    def inspect
+      "<Atom::Link href:'#{href}' type:'#{type}'>"
+    end
+  end
+end