atom-tools 0.9.0

data/lib/atom/element.rb

@@ -0,0 +1,277 @@
+require "time"
+require "rexml/element"
+
+module Atom # :nodoc:
+  class Time < ::Time # :nodoc:
+    def self.new date
+      return if date.nil?
+
+      date = if date.respond_to?(:iso8601)
+        date
+      else
+        Time.parse date.to_s
+      end
+        
+      def date.to_s
+        iso8601
+      end
+
+      date
+    end
+  end
+       
+  # ignore the man behind the curtain.
+  def self.Multiple klass
+    Class.new(Array) do
+      @class = klass
+
+      def new
+        item = self.class.holds.new
+        self << item
+      
+        item
+      end
+
+      def to_element
+        collect do |item| item.to_element end
+      end
+
+      def self.holds; @class end
+      def self.single?; true end
+      def taguri; end
+    end
+  end
+
+  class Element < Hash 
+    # a REXML::Element that shares this element's extension attributes
+    # and child elements
+    attr_reader :extensions
+
+    # this element's xml:base
+    attr_accessor :base
+ 
+    # The following is a DSL for describing an atom element.
+
+    # this element's attributes
+    def self.attrs # :nodoc:
+      @attrs || []
+    end
+
+    # this element's child elements
+    def self.elements # :nodoc:
+      @elements || []
+    end
+
+    # required child elements
+    def self.required # :nodoc:
+      @elements.find { |name,kind,req| req }
+    end
+
+    # copy defined elements and attributes so inheritance works
+    def self.inherited klass # :nodoc:
+      elements.each do |name, kind, req|
+        klass.element name, kind, req
+      end
+      attrs.each do |name, req|
+        klass.attrb name, req
+      end
+    end
+
+    # define a child element
+    def self.element(name, kind, req = false) # :nodoc:
+      attr_reader name
+
+      @elements ||= []
+      @elements << [name, kind, req]
+
+      unless kind.respond_to? :single?
+        self.define_accessor(name,kind)
+      end
+    end
+
+    # define an attribute 
+    def self.attrb(name, req = false) # :nodoc:
+      @attrs ||= []
+
+      @attrs << [name, req]
+    end
+ 
+    # a little bit of magic
+    def self.define_accessor(name,kind) # :nodoc:
+      define_method "#{name}=".to_sym do |value|
+        return unless value
+        
+        i = if kind.ancestors.member? Atom::Element
+          kind.new(value, name.to_s)
+        else
+          kind.new(value)
+        end
+       
+        set(name, i)
+      end
+    end
+
+    # get the value of an attribute
+    def [] key
+      test_key key
+   
+      super
+    end
+    
+    # set the value of an attribute
+    def []= key, value
+      test_key key
+
+      super
+    end
+
+    # internal junk you probably don't care about
+    def initialize name = nil # :nodoc:
+      @extensions = REXML::Element.new("extensions")
+      @local_name = name
+
+      self.class.elements.each do |name,kind,req|
+        if kind.respond_to? :single?
+          a = kind.new
+          set(name, kind.new)
+        end
+      end
+    end
+
+    # eg. "feed" or "entry" or "updated" or "title" or ...
+    def local_name # :nodoc:
+      @local_name || self.class.name.split("::").last.downcase
+    end
+   
+    # convert to a REXML::Element (with no namespace)
+    def to_element 
+      elem = REXML::Element.new(local_name)
+
+      self.class.elements.each do |name,kind,req|
+        v = get(name)
+        next if v.nil?
+
+        if v.respond_to? :to_element
+          e = v.to_element
+          e = [ e ] unless e.is_a? Array
+
+          e.each do |bit|
+            elem << bit
+          end
+        else
+          e = REXML::Element.new(name.to_s, elem).text = get(name)
+        end
+      end
+
+      self.class.attrs.each do |name,req|
+        value = self[name.to_s]
+        elem.attributes[name.to_s] = value if value
+      end
+
+      self.extensions.children.each do |element|
+        elem << element.dup # otherwise they get removed from @extensions
+      end
+
+      if self.base and not self.base.empty?
+        elem.attributes["xml:base"] = self.base
+      end
+
+      elem
+    end
+    
+    # convert to a REXML::Document (properly namespaced)
+    def to_xml
+      doc = REXML::Document.new
+      root = to_element
+      root.add_namespace Atom::NS
+      doc << root
+      doc
+    end
+   
+    # convert to an XML string
+    def to_s
+      to_xml.to_s
+    end
+    
+    private
+
+    # like +valid_key?+ but raises on failure
+    def test_key key
+      unless valid_key? key
+        raise RuntimeError, "this element (#{local_name}) doesn't have that attribute '#{key}'"
+      end
+    end
+
+    # tests that an attribute 'key' has been defined
+    def valid_key? key
+      self.class.attrs.find { |name,req| name.to_s == key }
+    end
+
+    def get name
+      instance_variable_get "@#{name}"
+    end
+
+    def set name, value
+      instance_variable_set "@#{name}", value
+    end
+  end
+  
+  # this facilitates YAML output
+  class AttrEl < Atom::Element # :nodoc:
+  end
+
+  # A link has the following attributes:
+  #
+  # href (required):: the link's IRI
+  # rel:: the relationship of the linked item to the current item
+  # type:: a hint about the media type of the linked item
+  # hreflang:: the language of the linked item (RFC3066)
+  # title:: human-readable information about the link
+  # length:: a hint about the length (in octets) of the linked item
+  class Link < Atom::AttrEl
+    attrb :href, true
+    attrb :rel
+    attrb :type
+    attrb :hreflang
+    attrb :title
+    attrb :length
+
+    def initialize name = nil # :nodoc:
+      super name
+
+      # just setting a default
+      self["rel"] = "alternate"
+    end
+  end
+ 
+  # A category has the following attributes:
+  #
+  # term (required):: a string that identifies the category
+  # scheme:: an IRI that identifies a categorization scheme
+  # label:: a human-readable label
+  class Category < Atom::AttrEl
+    attrb :term, true
+    attrb :scheme
+    attrb :label
+  end
+
+  # A person construct has the following child elements:
+  #
+  # name (required):: a human-readable name
+  # uri:: an IRI associated with the person
+  # email:: an email address associated with the person
+  class Author < Atom::Element
+    element :name, String, true
+    element :uri, String
+    element :email, String
+  end
+ 
+  # same as Atom::Author
+  class Contributor < Atom::Element 
+    # Author and Contributor should probably inherit from Person, but
+    # oh well.
+    element :name, String, true
+    element :uri, String
+    element :email, String
+  end
+end

data/lib/atom/entry.rb

@@ -0,0 +1,135 @@
+require "rexml/document"
+
+require "atom/element"
+require "atom/text"
+
+module Atom
+  NS = "http://www.w3.org/2005/Atom"
+
+  # An individual entry in a feed. As an Atom::Element, it can be
+  # manipulated using accessors for each of its child elements. You
+  # should be able to set them using an instance of any class that
+  # makes sense
+  #
+  # Entries have the following children:
+  #
+  # id:: a universally unique IRI which permanently identifies the entry
+  # title:: a human-readable title (Atom::Text)
+  # content:: contains or links to the content of an entry (Atom::Content)
+  # rights:: information about rights held in and over an entry (Atom::Text)
+  # source:: the source feed's metadata (unimplemented)
+  # published:: a Time "early in the life cycle of an entry"
+  # updated:: the most recent Time an entry was modified in a way the publisher considers significant
+  # summary:: a summary, abstract or excerpt of an entry (Atom::Text)
+  #
+  # There are also +categories+, +links+, +authors+ and +contributors+,
+  # each of which is an Array of its respective type and can be used
+  # thusly:
+  #
+  #   author = entry.authors.new
+  #   author.name = "Captain Kangaroo"
+  class Entry < Atom::Element
+    # the master list of standard children and the types they map to
+    element :id, String, true
+    element :title, Atom::Text, true
+    element :content, Atom::Content, true
+    
+    element :rights, Atom::Text
+    # element :source, Atom::Feed  # complicated, eg. serialization
+    
+    element :authors, Atom::Multiple(Atom::Author)
+    element :contributors, Atom::Multiple(Atom::Contributor)
+    
+    element :categories, Atom::Multiple(Atom::Category)
+    element :links, Atom::Multiple(Atom::Link)
+    
+    element :published, Atom::Time
+    element :updated, Atom::Time, true
+    
+    element :summary, Atom::Text
+
+    def initialize # :nodoc:
+      super "entry"
+     
+      # XXX I don't think I've ever actually used this
+      yield self if block_given?
+    end
+
+    # parses XML fetched from +base+ into an Atom::Entry
+    def self.parse xml, base = ""
+      if xml.respond_to? :to_atom_entry
+        xml.to_atom_entry(base)
+      else
+        REXML::Document.new(xml.to_s).to_atom_entry(base)
+      end
+    end
+
+    def inspect # :nodoc:
+      "#<Atom::Entry id:'#{self.id}'>"
+    end
+
+    # declare that this entry has updated
+    def updated!
+      self.updated = Time.now
+    end
+
+    # categorize the entry based on a space-separated string
+    def tag_with string
+      return if string.nil?
+
+      string.split.each do |tag|
+        categories.new["term"] = tag
+      end
+    end
+
+# XXX this needs a test suite before it can be trusted.
+=begin
+    # tests the entry's validity
+    def valid?
+      self.class.required.each do |element|
+        unless instance_variable_get "@#{element}"
+          return [ false, "required element atom:#{element} missing" ]
+        end
+      end
+
+      if @authors.length == 0
+        return [ false, "required element atom:author missing" ]
+      end
+
+      alternates = @links.find_all do |link|
+        link["rel"] == "alternate"
+      end
+
+      unless @content or alternates
+          return [ false, "no atom:content or atom:link[rel='alternate']" ]
+      end
+
+      alternates.each do |link|
+        if alternates.find do |x|
+          not x == link and 
+            x["type"] == link["type"] and 
+            x["hreflang"] == link["hreflang"]
+          end
+         
+          return [ false, 'more than one atom:link with a rel attribute value of "alternate" that has the same combination of type and hreflang attribute values.' ]
+        end
+      end
+
+      type = @content["type"]
+
+      base64ed = (not ["", "text", "html", "xhtml"].member? type) and 
+        type.match(/^text\/.*/).nil? and  # not text
+        type.match(/.*[\+\/]xml$/).nil?   # not XML
+
+      if (@content["src"] or base64ed) and not summary
+        return [ false, "out-of-line or base64ed atom:content and no atom:summary" ]
+      end
+
+      true
+    end
+=end
+  end
+end
+
+# this is here solely so that you don't have to require it
+require "atom/xml"

data/lib/atom/feed.rb

@@ -0,0 +1,229 @@
+require "atom/element"
+require "atom/text"
+require "atom/entry"
+
+require "atom/http"
+
+module Atom
+  class HTTPException < RuntimeError # :nodoc:
+  end
+  class FeedGone < RuntimeError # :nodoc:
+  end
+
+  # A feed of entries. As an Atom::Element, it can be manipulated using
+  # accessors for each of its child elements. You can set them with any
+  # object that makes sense; they will be returned in the types listed.
+  #
+  # Feeds have the following children:
+  #
+  # id:: a universally unique IRI which permanently identifies the feed
+  # title:: a human-readable title (Atom::Text)
+  # subtitle:: a human-readable description or subtitle (Atom::Text)
+  # updated:: the most recent Time the feed was modified in a way the publisher considers significant
+  # generator:: the agent used to generate a feed
+  # icon:: an IRI identifying an icon which visually identifies a feed (1:1 aspect ratio, looks OK small)
+  # logo:: an IRI identifying an image which visually identifies a feed (2:1 aspect ratio)
+  # rights:: rights held in and over a feed (Atom::Text)  
+  #
+  # There are also +links+, +categories+, +authors+, +contributors+ 
+  # and +entries+, each of which is an Array of its respective type and
+  # can be used thusly:
+  #
+  #   entry = feed.entries.new
+  #   entry.title = "blah blah blah"
+  class Feed < Atom::Element
+    attr_reader :uri
+
+    # the Atom::Feed pointed to by link[@rel='previous']
+    attr_reader :prev
+    # the Atom::Feed pointed to by link[@rel='next']
+    attr_reader :next
+   
+    # conditional get information from the last fetch
+    attr_reader :etag, :last_modified
+
+    element :id, String, true
+    element :title, Atom::Text, true
+    element :subtitle, Atom::Text
+   
+    element :updated, Atom::Time, true
+
+    element :links, Atom::Multiple(Atom::Link)
+    element :categories, Atom::Multiple(Atom::Category)
+
+    element :authors, Atom::Multiple(Atom::Author)
+    element :contributors, Atom::Multiple(Atom::Contributor)
+
+    element :generator, String # XXX with uri and version attributes!
+    element :icon, String
+    element :logo, String
+
+    element :rights, Atom::Text
+    
+    element :entries, Atom::Multiple(Atom::Entry)
+
+    include Enumerable
+
+    def inspect # :nodoc:
+      "<#{@uri} entries: #{entries.length} title='#{title}'>"
+    end
+
+    # parses XML fetched from +base+ into an Atom::Feed
+    def self.parse xml, base = ""
+      if xml.respond_to? :to_atom_entry
+        xml.to_atom_feed(base)
+      else
+        REXML::Document.new(xml.to_s).to_atom_feed(base)
+      end
+    end
+
+    # Create a new Feed that can be found at feed_uri and retrieved
+    # using an Atom::HTTP object http
+    def initialize feed_uri = nil, http = Atom::HTTP.new
+      @entries = []
+      @http = http
+
+      if feed_uri
+        @uri = feed_uri.to_uri
+        self.base = feed_uri
+      end
+
+      super "feed"
+    end
+
+    # iterates over a feed's entries
+    def each &block
+      @entries.each &block
+    end
+
+    # gets everything in the logical feed (could be a lot of stuff)
+    # (see <http://www.ietf.org/internet-drafts/draft-nottingham-atompub-feed-history-05.txt>)
+    def get_everything!
+      self.update!
+  
+      prev = @prev
+      while prev
+        prev.update!
+
+        self.merge_entries! prev
+        prev = prev.prev
+      end
+
+      nxt = @next
+      while nxt
+        nxt.update!
+
+        self.merge_entries! nxt
+        nxt = nxt.next
+      end
+
+      self
+    end
+
+    # merges the entries from another feed into this one
+    def merge_entries! other_feed
+      other_feed.each do |entry|
+        # TODO: add atom:source elements
+        self << entry
+      end
+    end
+
+    # like #merge, but in place 
+    def merge! other_feed
+      [:id, :title, :subtitle, :updated, :rights].each { |p|
+        self.send("#{p}=", other_feed.send("#{p}"))
+      }
+
+      [:links, :categories, :authors, :contributors].each do |p|
+        other_feed.send("#{p}").each do |e|
+          self.send("#{p}") << e
+        end
+      end
+
+      merge_entries! other_feed
+    end
+
+    # merges "important" properties of this feed with another one,
+    # returning a new feed
+    def merge other_feed
+      feed = self.clone
+
+      feed.merge! other_feed
+      
+      feed
+    end
+
+    # fetches this feed's URL, parses the result and #merge!s
+    # changes, new entries, &c.
+    def update!
+      raise(RuntimeError, "can't fetch without a uri.") unless @uri
+     
+      headers = {}
+      headers["If-None-Match"] = @etag if @etag
+      headers["If-Modified-Since"] = @last_modified if @last_modified
+
+      res = @http.get(@uri, headers)
+
+      if res.code == "304"
+        # we're already all up to date
+        return self
+      elsif res.code == "410"
+        raise Atom::FeedGone, "410 Gone (#{@uri})"
+      elsif res.code != "200"
+        raise Atom::HTTPException, "Unexpected HTTP response code: #{res.code}"
+      end
+        
+      unless res.content_type.match(/^application\/atom\+xml/)
+        raise Atom::HTTPException, "Unexpected HTTP response Content-Type: #{res.content_type} (wanted application/atom+xml)"
+      end
+
+      @etag = res["Etag"] if res["Etag"]
+      @last_modified = res["Last-Modified"] if res["Last-Modified"]
+
+      xml = res.body
+
+      coll = REXML::Document.new(xml)
+
+      update_time = Time.parse(REXML::XPath.first(coll, "/atom:feed/atom:updated", { "atom" => Atom::NS } ).text)
+
+      # the feed hasn't been updated, don't bother
+      if self.updated and self.updated >= update_time
+        return self
+      end
+
+      coll = Atom::Feed.parse(coll, self.base.to_s)
+      merge! coll
+     
+      link = coll.links.find { |l| l["rel"] = "next" and l["type"] == "application/atom+xml" }
+      if link
+        abs_uri = @uri + link["href"]
+        @next = Feed.new(abs_uri.to_s, @http)
+      end
+
+      link = coll.links.find { |l| l["rel"] = "previous" and l["type"] == "application/atom+xml" } 
+      if link
+        abs_uri = @uri + link["href"]
+        @prev = Feed.new(abs_uri.to_s, @http)
+      end
+
+      self
+    end
+
+    # adds an entry to this feed. if this feed already contains an 
+    # entry with the same id, the newest one is used.
+    def << entry
+      existing = entries.find do |e|
+        e.id == entry.id
+      end
+
+      if not existing
+        @entries << entry
+      elsif not existing.updated or (existing.updated and entry.updated and entry.updated >= existing.updated)
+        @entries[@entries.index(existing)] = entry
+      end
+    end
+  end
+end
+
+# this is here solely so you don't have to require it
+require "atom/xml"