ratom 0.2.2 → 0.3.0

data/History.txt

@@ -1,3 +1,9 @@
+== 0.3.0 2008-04-02
+
+* Raise Atom::Serialization error when you try and serialize non-utf8 content.
+* Support reading simple extension elements, see README.txt.
+* Support writing simple extension elements, see README.txt.
+
 == 0.2.2 2008-02-10
 
 * Removed dependency on ActiveSupport.

data/README.txt

@@ -97,6 +97,45 @@ required to let us update to the entry.  For example, lets change the content an
   
 You can also delete an entry using the <tt>destroy!</tt> method, but we won't do that will we?.
     
+=== Extension elements
+
+As of version 0.3.0, rAtom support simple extension elements on feeds and entries.  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).
 
 == TODO
 
@@ -105,8 +144,8 @@ You can also delete an entry using the <tt>destroy!</tt> method, but we won't do
 * 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.
+* Handle HTTP basic authentication.
 
 == Source Code
 

data/lib/atom.rb

@@ -11,10 +11,40 @@ require 'atom/xml/parser.rb'
 
 module Atom # :nodoc:
   NAMESPACE = 'http://www.w3.org/2005/Atom' unless defined?(NAMESPACE)
-  
+  module Pub
+    NAMESPACE = 'http://www.w3.org/2007/app'
+  end
   # Raised when a Parsing Error occurs.
   class ParseError < StandardError; end
+  # Raised when a Serialization Error occurs.
+  class SerializationError < StandardError; end
+  
+  # Provides support for reading and writing simple extensions as defined by the Atom Syndication Format.
+  #
+  # A Simple extension is an element from a non-atom namespace that has no attributes and only contains
+  # text content. It is interpreted as a key-value pair when the namespace and the localname of the
+  # extension make up the key. Since in XML you can have many instances of an element, the values are
+  # represented as an array of strings, so to manipulate the values manipulate the array returned by
+  # +[ns, localname]+.
+  #
+  module SimpleExtensions
+    attr_reader :simple_extensions
+    
+    # Gets a simple extension value for a given namespace and local name.
+    #
+    # +ns+:: The namespace.
+    # +localname+:: The local name of the extension element.
+    #
+    def [](ns, localname)
+      if @simple_extensions.nil?
+        @simple_extensions = {}
+      end
       
+      key = "{#{ns},#{localname}}"
+      (@simple_extensions[key] or @simple_extensions[key] = [])
+    end
+  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.
@@ -138,11 +168,23 @@ module Atom # :nodoc:
       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
+        require 'iconv'
+        # Convert from utf-8 to utf-8 as a way of making sure the content is UTF-8.
+        #
+        # This is a pretty crappy way to do it but if we don't check libxml just
+        # fails silently and outputs the content element without any content. At
+        # least checking here and raising an exception gives the caller a chance
+        # to try and recitfy the situation.
+        #
+        begin
+          node = XML::Node.new(name)
+          node << Iconv.iconv('utf-8', 'utf-8', self.to_s)
+          node['type'] = 'html'
+          node['xml:lang'] = self.xml_lang        
+          node
+        rescue Iconv::IllegalSequence => e
+          raise SerializationError, "Content must be converted to UTF-8 before attempting to serialize to XML: #{e.message}."
+        end
       end
     end
     
@@ -239,9 +281,10 @@ module Atom # :nodoc:
   # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.feed
   class Feed
     include Xml::Parseable
+    include SimpleExtensions
     extend Forwardable
     def_delegators :@links, :alternate, :self, :via, :first_page, :last_page, :next_page, :prev_page
-        
+
     loadable! 
     
     element :id, :rights
@@ -327,7 +370,7 @@ module Atom # :nodoc:
       else
         self.entries.each(&block)
       end
-    end
+    end   
   end
   
   # Represents an Entry as defined by the Atom Syndication Format specification.
@@ -355,6 +398,7 @@ module Atom # :nodoc:
   # See also http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.entry
   class Entry
     include Xml::Parseable
+    include SimpleExtensions
     extend Forwardable
     def_delegators :@links, :alternate, :self, :alternates, :enclosures, :edit_link, :via
     

data/lib/atom/pub.rb

@@ -21,7 +21,6 @@ module Atom
         @response = response
       end
     end
-    NAMESPACE = 'http://www.w3.org/2007/app'
     
     class Service
       include Atom::Xml::Parseable

data/lib/atom/version.rb

@@ -1,8 +1,8 @@
 module Atom #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 2
-    TINY  = 2
+    MINOR = 3
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/atom/xml/parser.rb

@@ -6,6 +6,7 @@
 #
 
 require 'net/http'
+require 'time'
 
 # Just a couple methods form transforming strings
 unless defined?(ActiveSupport)
@@ -36,7 +37,7 @@ module Atom
         loop do
           case xml.node_type
           when XML::Reader::TYPE_ELEMENT
-            if element_specs.include?(xml.local_name)
+            if element_specs.include?(xml.local_name) && [Atom::NAMESPACE, Atom::Pub::NAMESPACE].include?(xml.namespace_uri)
               element_specs[xml.local_name].parse(self, xml)
             elsif attributes.any?
               while (xml.move_to_next_attribute == 1)
@@ -45,6 +46,8 @@ module Atom
                   self.send("#{xml.name.sub(/:/, '_')}=", xml.value)
                 end
               end
+            elsif self.respond_to?(:simple_extensions)
+              self[xml.namespace_uri, xml.local_name] << xml.read_string
             end
           end
           break unless !options[:once] && xml.next == 1 && xml.depth >= starting_depth
@@ -114,6 +117,21 @@ module Atom
           end
         end
         
+        if self.respond_to?(:simple_extensions) && self.simple_extensions
+          self.simple_extensions.each do |name, value_array|
+            if name =~ /\{(.*),(.*)\}/
+              value_array.each do |value|
+                ext = XML::Node.new($2)
+                ext['xmlns'] = $1
+                ext << value
+                node << ext
+              end
+            else
+              STDERR.print "Couldn't split #{name}"
+            end
+          end
+        end
+        
         unless nodeonly
           doc = XML::Document.new
           doc.root = node

data/spec/atom_spec.rb

@@ -7,6 +7,77 @@
 
 require File.dirname(__FILE__) + '/spec_helper.rb'
 require 'net/http'
+require 'time'
+
+shared_examples_for 'simple_single_entry.atom attributes' do
+  it "should parse title" do
+    @feed.title.should == 'Example Feed'
+  end
+
+  it "should parse updated" do
+    @feed.updated.should == Time.parse('2003-12-13T18:30:02Z')
+  end
+
+  it "should parse id" do
+    @feed.id.should == 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6'
+  end
+
+  it "should have an entries array" do
+    @feed.entries.should be_an_instance_of(Array)
+  end
+
+  it "should have one element in the entries array" do
+    @feed.entries.size.should == 1
+  end
+
+  it "should have an alternate" do
+    @feed.alternate.should_not be_nil
+  end
+
+  it "should have an Atom::Link as the alternate" do
+    @feed.alternate.should be_an_instance_of(Atom::Link)
+  end
+
+  it "should have the correct href in the alternate" do
+    @feed.alternate.href.should == 'http://example.org/'
+  end
+  
+  it "should parse title" do
+    @entry.title.should == 'Atom-Powered Robots Run Amok'
+  end
+  
+  it "should have an alternate" do
+    @entry.alternate.should_not be_nil
+  end
+  
+  it "should have an Atom::Link as the alternate" do
+    @entry.alternate.should be_an_instance_of(Atom::Link)
+  end
+  
+  it "should have the correct href on the alternate" do
+    @entry.alternate.href.should == 'http://example.org/2003/12/13/atom03'
+  end
+  
+  it "should parse id" do
+    @entry.id.should == 'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
+  end
+  
+  it "should parse updated" do
+    @entry.updated.should == Time.parse('2003-12-13T18:30:02Z')
+  end
+  
+  it "should parse summary" do
+    @entry.summary.should == 'Some text.'
+  end
+  
+  it "should parse content" do
+    @entry.content.should == 'This <em>is</em> html.'
+  end
+  
+  it "should parse content type" do
+    @entry.content.type.should == 'html'
+  end
+end
 
 describe Atom do  
   describe "Atom::Feed.load_feed" do
@@ -70,83 +141,10 @@ describe Atom do
   describe 'SimpleSingleFeed' do
     before(:all) do 
       @feed = Atom::Feed.load_feed(File.open('spec/fixtures/simple_single_entry.atom'))
+      @entry = @feed.entries.first
     end
        
-    describe Atom::Feed do      
-      it "should parse title" do
-        @feed.title.should == 'Example Feed'
-      end
-
-      it "should parse updated" do
-        @feed.updated.should == Time.parse('2003-12-13T18:30:02Z')
-      end
-
-      it "should parse id" do
-        @feed.id.should == 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6'
-      end
-
-      it "should have an entries array" do
-        @feed.entries.should be_an_instance_of(Array)
-      end
-
-      it "should have one element in the entries array" do
-        @feed.entries.size.should == 1
-      end
-
-      it "should have an alternate" do
-        @feed.alternate.should_not be_nil
-      end
-
-      it "should have an Atom::Link as the alternate" do
-        @feed.alternate.should be_an_instance_of(Atom::Link)
-      end
-
-      it "should have the correct href in the alternate" do
-        @feed.alternate.href.should == 'http://example.org/'
-      end
-    end
-
-    describe Atom::Entry do
-      before(:each) do
-        @entry = @feed.entries.first
-      end
-      
-      it "should parse title" do
-        @entry.title.should == 'Atom-Powered Robots Run Amok'
-      end
-      
-      it "should have an alternate" do
-        @entry.alternate.should_not be_nil
-      end
-      
-      it "should have an Atom::Link as the alternate" do
-        @entry.alternate.should be_an_instance_of(Atom::Link)
-      end
-      
-      it "should have the correct href on the alternate" do
-        @entry.alternate.href.should == 'http://example.org/2003/12/13/atom03'
-      end
-      
-      it "should parse id" do
-        @entry.id.should == 'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'
-      end
-      
-      it "should parse updated" do
-        @entry.updated.should == Time.parse('2003-12-13T18:30:02Z')
-      end
-      
-      it "should parse summary" do
-        @entry.summary.should == 'Some text.'
-      end
-      
-      it "should parse content" do
-        @entry.content.should == 'This <em>is</em> html.'
-      end
-      
-      it "should parse content type" do
-        @entry.content.type.should == 'html'
-      end
-    end
+    it_should_behave_like "simple_single_entry.atom attributes"
   end
   
   describe 'ComplexFeed' do
@@ -905,6 +903,53 @@ describe Atom do
         entry_count.should == 1
       end
     end
+    
+    describe "entry_with_simple_extensions.atom" do
+      before(:each) do
+        @feed = Atom::Feed.load_feed(File.open('spec/fixtures/entry_with_simple_extensions.atom'))
+        @entry = @feed.entries.first
+      end
+      
+      it "should load simple extension for feed" do
+        @feed["http://example.org/example", 'simple1'].should == ['Simple1 Value']
+      end
+      
+      it "should load empty simple extension for feed" do
+        @feed["http://example.org/example", 'simple-empty'].should == ['']
+      end
+      
+      it "should load simple extension 1 for entry" do
+        @entry["http://example.org/example", 'simple1'].should == ['Simple1 Entry Value']
+      end
+      
+      it "should load simple extension 2 for entry" do 
+        @entry["http://example.org/example", 'simple2'].should == ['Simple2', 'Simple2a']
+      end
+      
+      it "should find a simple extension in another namespace" do
+        @entry["http://example2.org/example2", 'simple1'].should == ['Simple Entry Value (NS2)']
+      end
+      
+      it "should read an extension with the same local name as an Atom element" do
+        @feed['http://example.org/example', 'title'].should == ['Extension Title']
+      end
+      
+      it_should_behave_like 'simple_single_entry.atom attributes'
+    end
+    
+    describe 'writing simple extensions' do
+      it "should recode and re-read a simple extension element" do
+        entry = Atom::Entry.new do |entry|
+          entry.id = 'urn:test'
+          entry.title = 'Simple Ext. Test'
+          entry.updated = Time.now
+          entry['http://example.org', 'title'] << 'Example title'
+        end
+        
+        entry2 = Atom::Entry.load_entry(entry.to_xml)
+        entry2['http://example.org', 'title'].should == ['Example title']
+      end
+    end
   end
   
   describe Atom::Link do
@@ -972,6 +1017,16 @@ describe Atom do
       other = Atom::Entry.load_entry(@entry.to_xml)
       @entry.should == other
     end
+    
+    it "should raise error when to_xml'ing non-utf8 content" do
+      lambda {
+        puts(Atom::Entry.new do |entry|
+          entry.title = "My entry"
+          entry.id = "urn:entry:1"
+          entry.content = Atom::Content::Html.new("this is not \227 utf8")
+        end.to_xml)  
+      }.should raise_error(Atom::SerializationError)      
+    end
   end
   
   describe 'Atom::Feed initializer' do

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: ratom
 version: !ruby/object:Gem::Version 
-  version: 0.2.2
-platform: ""
+  version: 0.3.0
+platform: ruby
 authors: 
 - Peerworks
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2008-03-10 00:00:00 +10:30
+date: 2008-04-02 00:00:00 +10:30
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: ratom
-rubygems_version: 0.9.5
+rubygems_version: 1.1.0
 signing_key: 
 specification_version: 2
 summary: Atom Syndication and Publication API