lib/atom/text.rb in atom-tools-0.9.2 vs lib/atom/text.rb in atom-tools-0.9.3

@@ -2,35 +2,48 @@
 
 module XHTML
   NS = "http://www.w3.org/1999/xhtml"
 end
 
-module Atom 
+module Atom
   # An Atom::Element representing a text construct.
-  # It has a single attribute, "type", which accepts values
-  # "text", "html" and "xhtml"
-
+  # It has a single attribute, "type", which specifies how to interpret
+  # the element's content. Different types are:
+  #
+  # text:: a plain string, without any markup (default)
+  # html:: a chunk of HTML
+  # xhtml:: a chunk of *well-formed* XHTML
+  #
+  # You should set this attribute appropriately after you set a Text
+  # element (entry.content, entry.title or entry.summary).
+  #
+  # This content of this element can be retrieved in different formats, see #html and #xml
   class Text < Atom::Element
     attrb :type
 
     def initialize value, name # :nodoc:
       @content = value
       @content ||= "" # in case of nil
       self["type"] = "text"
-      
+
       super name
     end
 
+    # convenient, but not overly useful. see #html instead.
     def to_s
-      if self["type"] == "xhtml" 
+      if self["type"] == "xhtml"
         @content.children.to_s
       else
         @content.to_s
       end
     end
 
-    # returns a string suitable for dumping into an HTML document
+    # returns a string suitable for dumping into an HTML document.
+    #   (or nil if that's impossible)
+    #
+    # if you're storing the content of a Text construct, you probably
+    # want this representation.
     def html
       if self["type"] == "xhtml" or self["type"] == "html"
         to_s
       elsif self["type"] == "text"
         REXML::Text.new(to_s).to_s
@@ -38,11 +51,11 @@
     end
 
     # attempts to parse the content of this element as XML and return it
     # as an array of REXML::Elements.
     #
-    # If this self["type"] is "html" and Hpricot is installed, it will
+    # If self["type"] is "html" and Hpricot is installed, it will
     # be converted to XHTML first.
     def xml
       if self["type"] == "xhtml"
         @content.children
       elsif self["type"] == "text"
@@ -81,11 +94,11 @@
         end
       end
 
       super(key, value)
     end
-    
+
     def to_element # :nodoc:
       e = super
 
       if self["type"] == "text"
         e.attributes.delete "type"
@@ -104,22 +117,23 @@
         end
       end
 
       e
     end
-    
+
     private
+    # converts @content based on the value of self["type"]
     def convert_contents e
       if self["type"] == "xhtml"
         @content
       elsif self["type"] == "text" or self["type"].nil?
         REXML::Text.normalize(@content.to_s)
       elsif self["type"] == "html"
-        @content.to_s
+        @content.to_s.gsub(/&/, "&amp;")
       end
     end
-    
+
     def valid_type? type
       ["text", "xhtml", "html"].member? type
     end
 
     def parse_xhtml_content xhtml = nil
@@ -151,9 +165,17 @@
   #
   # * the "type" attribute can be an arbitrary media type
   # * there is a "src" attribute which is an IRI that points to the content of the entry (in which case the content element will be empty)
   class Content < Atom::Text
     attrb :src
+
+    def html
+      if self["src"]
+        ""
+      else
+        super
+      end
+    end
 
     private
     def valid_type? type
       super or type.match(/\//)
     end