uformats 1.2.1

data/CHANGES

@@ -0,0 +1,8 @@
+1.2.1 (2006-06-14)
+
+* Minor changes to work with HTMLEntities 3.0.1+
+* Added gem
+
+1.2 (2006-03-08)
+
+* First public release

data/COPYING

@@ -0,0 +1,4 @@
+Copyright Revieworld Ltd. 2006
+
+You may use, copy and redistribute this library under the same terms as Ruby
+itself (see http://www.ruby-lang.org/en/LICENSE.txt).

data/README

@@ -0,0 +1,36 @@
+uformats
+
+ABOUT
+
+A library for parsing various microformats under Ruby:
+
+* hReview (0.3)
+* hCard
+* hCalendar (vevent only; limited support)
+* rel-tag
+* rel-license
+* include-pattern
+
+PREREQUISITES
+
+htmlentities >= 3.0.1 (http://htmlentities.rubyforge.org/)
+
+If you want to try the sample code, you will also need:
+
+tidy (http://rubyforge.org/projects/tidy)
+
+You'll also need to install the tidy library for your operating system. For OS
+X, it's available via Darwin Ports (port install tidy). For Windows, get it
+from http://dev.int64.org/tidy.html and rename 'tidy.dll' to 'libtidy.dll'.
+For Linux etc. it should be available via the repositories.
+
+INSTALLATION
+
+To install (requires root/admin privileges):
+
+# ruby setup.rb
+
+To test:
+
+$ ruby setup.rb test
+

data/lib/uformats.rb

@@ -0,0 +1,158 @@
+require 'rexml/document'
+require 'uformats/pluralizer'
+require 'cgi'
+
+module Microformats
+
+  #
+  # Provides method access to an internal Hash
+  #
+  class MethodHash
+    
+    instance_methods.each { |m| undef_method m unless m =~ /^__/ }
+    
+    def initialize(hash={})
+      @hash = hash.dup
+    end
+    
+    def []=(k,v)
+      @hash[k] = v
+    end
+    
+    def [](k)
+      return @hash[k]
+    end
+  
+    def method_missing(sym, *args)
+      return Pluralizer.singularized_lookup(self, sym)
+    end
+    
+    def each(&blk)
+      case blk.arity
+      when 1
+        @hash.each do |k,v|
+          yield [k, v]
+        end
+      when 2
+        @hash.each do |k,v|
+          yield k, v
+        end
+      end
+    end
+  end # MethodHash
+  
+  #
+  # Expand all include-pattern objects in a document
+  #
+  def expand_include_patterns!(rexml_source)
+    each_element_by_class(rexml_source, :include) do |target|
+      if (target.attribute('data') && target.attribute('data').value =~ /^#/)
+        source_id = target.attribute('data').value.sub(/^#/, '')
+        source = rexml_source.elements["//*[@id='#{source_id}']"]
+        if source
+          replacement = source.deep_clone
+          replacement.attributes.delete('id')
+          target.replace_with(replacement)
+        end
+      end
+    end
+    return rexml_source
+  end
+  
+  #
+  # Yield each element matching sym at or below the given node
+  #
+  def each_element_by_class(rexml_source, sym)
+    css_class = Microformats.sym_to_css_class(sym)
+    rexml_source.each_element("descendant-or-self::*[contains(@class,'#{css_class}')]") do |element|
+      if element.attribute('class').value =~ /\b#{css_class}\b/
+        yield element
+      end
+    end
+  end
+  
+  #
+  # Returns the first element matching sym at or below the given node, or nil if none exists
+  #
+  def first_element_by_class(rexml_source, sym)
+    each_element_by_class(rexml_source, sym) do |element|
+      return element
+    end
+    return nil
+  end
+  
+  #
+  # Return a list of all rel-tag elements found at or above the given node
+  #
+  def rel_tags_above_element(rexml_element)
+    tags = []
+    rexml_element.each_element('ancestor::*/a[@rel="tag"]') do |tagged_element|
+      tag = rel_tag(tagged_element)
+      tags << tag if tag
+    end
+    tags.compact!
+    return tags.empty? ? nil : tags
+  end
+  
+  #
+  # Return a list of all rel-tag elements found at or below the given node
+  #
+  def rel_tags_below_element(rexml_element)
+    tags = []
+    rexml_element.each_element('descendant-or-self::a[@rel="tag"]') do |tagged_element|
+      tag = rel_tag(tagged_element)
+      tags << tag if tag
+    end
+    return tags.empty? ? nil : tags
+  end
+  
+  def rel_tag(rexml_element)
+    if rexml_element.attribute('href')
+      href = rexml_element.attribute('href').value
+      href.gsub!(%r!^.*/|[\?\#].*$!, '')
+      return CGI.unescape(href)
+    else
+      return nil
+    end
+  end
+  
+  #
+  # Return a list of all rel-license elements found in the given element
+  #
+  def rel_licenses(rexml_element)
+    licenses = []
+    rexml_element.each_element('descendant-or-self::a[@rel="license"]') do |license_element|
+      if license_element.attribute('href')
+        licenses << license_element.attribute('href').value
+      end
+    end
+    return licenses.empty? ? nil : licenses
+  end
+  
+  #
+  # Convert a Ruby symbol to a CSS class, e.g. :foo_bar => "foo-bar"
+  #
+  def sym_to_css_class(sym)
+    return sym.to_s.gsub('_', '-')
+  end
+  
+  #
+  # Convert a css class to a Ruby symbol
+  #
+  def css_class_to_sym(css_class)
+    return css_class.gsub('-', '_').to_sym
+  end
+  
+  #
+  # Returns a list of symbols corresponding to an element's classes
+  #
+  def classes_for_element(rexml_element)
+    if (css_class = rexml_element.attribute('class'))
+      return css_class.value.strip.split(/\s/).map{ |e| css_class_to_sym(e) }
+    else
+      return []
+    end
+  end
+  
+  extend self
+end

data/lib/uformats/basic.rb

@@ -0,0 +1,268 @@
+require 'rexml/document'
+require 'cgi'
+require 'uformats'
+require 'uformats/pluralizer'
+require 'htmlentities'
+require 'time'
+require 'uri'
+
+module Microformats     
+  class BasicNestedFormat
+    
+    alias_method :__class__, :class
+    
+    class << self
+      
+      #
+      # Define or return a hash describing the structure of the derived microformat, 
+      # using symbols, hashes, and arrays.
+      #
+      # E.g. 
+      #
+      #  structure({
+      #    :foo => :integer,   # singular integral value
+      #    :bar => [:string],  # singular or plural string value
+      #    :baz => {           # substructure below 'baz'
+      #      :created_on => :datetime # 'created-on' is interpeted as a date/time value
+      #    }
+      #  })
+      #
+      def structure(structure=nil)
+        if structure
+          @structure = structure
+          legal_keys = []
+          structure.each do |key, value|
+            legal_keys << key
+            if value.is_a?(Array)
+              legal_keys << Pluralizer.pluralize(key)
+            end
+          end
+          legal_keys.each do |key|
+            class_eval "def #{key}() return Pluralizer.singularized_lookup(@tree, :#{key}) ; end"
+          end
+        end
+        return @structure
+      end
+      
+      #
+      # By default, the name of the class is converted to lowercase and used as the 
+      # CSS class identifying this format (e.g. HReview => "hreview"). This method 
+      # can be used to override this.
+      #
+      def identifier(ident=nil)
+        @identifier_class = ident if ident
+        return @identifier_class ||= self.to_s.split('::').last.downcase.to_sym
+      end
+      
+      #
+      # Yields a new instance for each of the matching microformats within 
+      # the given document. 
+      #
+      def each(source, url=nil)
+        if source.respond_to?(:each_element)
+          xml_source = source
+        else
+          xml_source = REXML::Document.new(source.to_s)
+        end
+        Microformats.expand_include_patterns!(xml_source)
+        Microformats.each_element_by_class(xml_source, identifier) do |element|
+          yield new(element.dup, url)
+        end
+      end
+      
+      #
+      # Returns a new instance for the first matching microformat in the 
+      # given document.
+      #
+      def first(source, url=nil)
+        each(source, url) do |mf|
+          return mf
+        end
+      end
+      
+    end # class << self
+    
+    def initialize(source, url=nil)
+      if source.respond_to?(:each_element)
+        @source = source
+      else
+        @source = REXML::Document.new(source.to_s)
+      end
+      @url = url
+      @tree = parse(__class__.structure, @source, MethodHash.new)
+      post_process!
+    end
+    attr_reader :source
+    
+    def post_process!
+    end
+    
+    def parse(structure, source, default_tree=nil)
+      tree = default_tree || MethodHash.new
+      structure.each do |tag, substructure|
+        if substructure.is_a?(Array)
+          key = Pluralizer.pluralize(tag)
+        else
+          key = tag
+        end
+        Microformats.each_element_by_class(source, tag) do |element|
+          tree[key] = parse_tag(substructure, source, tag)
+        end
+      end
+      return tree
+    end
+    
+    def parse_tag(substructure, source, tag)
+      if substructure.is_a? Array
+        substructure = substructure[0]
+        elements = []
+        is_plural = true
+      else
+        is_plural = false
+      end
+      Microformats.each_element_by_class(source, tag) do |element|
+        if substructure.is_a? Hash
+          this = parse(substructure, element)
+          # Special case for values that can be encapsulated or not
+          unless this[:value]
+            ignored_classes = substructure.keys - [:value]
+            if substructure[:value] == :value
+              v = process_as_value(element, ignored_classes)
+              this[:value] ||= v if v
+            elsif substructure[:value] == :email
+              v = process_value_as_email(element)
+              this[:value] ||= v if v
+            end
+          end
+        else
+          this = self.__send__("process_as_#{substructure}".to_sym, element)
+        end
+        if is_plural
+          elements << this
+        else
+          return this
+        end
+      end
+      return elements
+    end
+    
+    def process_as_string(element, ignored_classes=[])
+      case element.fully_expanded_name
+      when 'abbr'
+        return element.attribute('title').value.strip
+      when 'img'
+        return element.attribute('alt').value.strip
+      else
+        buffer = ''
+        element.children.each do |child|
+          case child
+          when REXML::Text
+            buffer << child.to_s
+          else
+            has_classes = Microformats.classes_for_element(child)
+            if (has_classes & ignored_classes).empty?
+              buffer << process_as_string(child, ignored_classes)
+            end
+          end
+        end
+        return HTMLEntities.decode_entities(buffer.strip.gsub(/\s+/um, ' '))
+      end
+    end
+  
+    def process_as_integer(element)
+      text = process_as_string(element)
+      return nil unless text
+      return nil unless text =~ /^\d+$/
+      return text.to_i(10)
+    end
+    
+    def process_as_float(element)
+      text = process_as_string(element)
+      return nil unless text
+      return nil unless text =~ /^\d+(?:\.\d+)?$/
+      return text.to_f
+    end
+  
+    def process_as_xhtml(element)
+      return element.children.map{ |c| c.to_s }.join.strip
+    end
+    
+    def process_as_datetime(element)
+      text = process_as_string(element)
+      return nil unless text && text =~ /\d{2,}/
+      text << '-01T00:00:00Z' if text =~ /^\d{4}-\d{2}$/
+      text << '01T000000Z' if text =~ /^\d{6}$/
+      text << '-T00:00:00Z' if text =~ /^\d{4}-\d{2}-\d{2}$/
+      text << 'T000000Z' if text =~ /^\d{8}$/
+      text.gsub!(/\++/, '+')
+      text.gsub!(/\-+/, '-')
+      begin
+        return Time.parse(text)
+      rescue
+        return nil
+      end
+    end
+  
+    def process_as_url(element)
+      element.each_element('descendant-or-self::*[@href or @src]') do |subelement|
+        if (href = subelement.attribute('href'))
+          return absolute_url(href.value.strip)
+        elsif (src = subelement.attribute('src'))
+          return absolute_url(src.value.strip)
+        end
+      end
+      return nil
+    end
+    
+    def process_as_value(element, ignored_classes=[])
+      Microformats.each_element_by_class(element, :value) do |e|
+        return process_as_string(e, ignored_classes)
+      end
+      return process_as_string(element, ignored_classes)
+    end
+    
+    def process_as_email(element)
+      url = process_as_url(element)
+      if url
+        return url.sub(/^mailto:/, '')
+      else
+        return process_as_string(element)
+      end
+    end
+    
+    def process_value_as_email(element)
+      email = process_as_url(element)
+      return email.sub(/^mailto:/, '') if email
+      return process_as_value(element)
+    end
+    
+    def absolute_url(relative_url)
+      return relative_url unless @url
+      return URI.join(@url, relative_url).to_s
+    end
+    
+    #
+    # Instead of worrying about calling methods on nil, lookup provides an 
+    # easy way of accessing deeply nested data.
+    #
+    # E.g.
+    # 
+    #  object.somethings[1].other # => error if somethings[1] is nil
+    #  object.lookup(:somethings, 1, :other) # => nil if any level is nil
+    #
+    def lookup(*list)
+      tree = @tree
+      list.each do |level|
+        if level.is_a?(Symbol)
+          tree = tree.__send__(level)
+        else
+          tree = tree.__send__(:[], level)
+        end
+        return nil unless tree
+      end
+      return tree
+    end
+
+  end # BasicNestedFormat
+  
+end # Microformats