csl 1.0.0.pre3 → 1.0.0.pre4

data/lib/csl/info.rb

@@ -1,73 +1,169 @@
 module CSL
-  
+  #
+  # {Info} nodes contain a {Style} (or {Locale}) metadata. Their XML structure
+  # is based on the Atom Syndication Format. For independent styles an {Info}
+  # node typically has the following child elements:
+  #
+  # * {Author} and {Contributor}: used to respectively acknowledge
+  #   style authors and contributors, may each be used multiple times.
+  # * {Category}: styles may be assigned one or more categories. One
+  #   {Category} node may be used once to describe how in-text citations
+  #   are rendered, using its citation-format attribute.
+  # * {Id}: Must appear once. The element should contain a URI to establish
+  #   the identity of the style. A stable, unique and dereferenceable URI
+  #   is desired for publicly available styles.
+  # * {Link}: Multiple links can be added to an {Info} node: self,
+  #   documentation, and template links all have dedicated accessors.
+  # * {Title}: Must appear once. The contents of this node should be the
+  #   name of the style as shown to users.
+  # * {TitleShort}: May appear once. The contents of this node should be a
+  #   shortened style name (e.g. "APA").
+  # * {Summary}: This node gives a description of the style.
+  # * {Rights}: This node specifies the license under which the style file
+  #   is released. The element may carry a license attribute to specify the
+  #   URI of the license.
+  # * {Updated}: Must appear once. This node must contain a timestamp that
+  #   shows when the style was last updated.
+  #
+  # In dependent styles, the {Info} node must contain a {Link} with rel set
+  # to "independent-parent", with the URI of the independent parent style
+  # set on href. This link is also accessible as a string using the
+  # {#independent_parent} accessors. In addition, dependent styles should
+  # not contain template links.
+  #
+  # In a {Locale} node the {Info} node typically carries only {Translator},
+  # {Rights} and {Updated} nodes.
   class Info < Node
 
     attr_children :title, :'title-short', :id, :issn, :eissn, :issnl,
       :link, :author, :contributor, :category, :published, :summary,
       :updated, :rights, :'link-dependent-style'
-    
+
     alias_child :contributors, :contributor
-    alias_child :authors, :contributor
+    alias_child :authors, :author
     alias_child :links, :link
-    
+    alias_child :categories, :category
+
     def initialize(attributes = {})
       super(attributes, &nil)
-      children[:link] = []
+      children[:link], children[:category] = [], []
 
       yield self if block_given?
     end
-    
+
     # @!attribute self_link
     # @return [String,nil] the style's URI
 
     # @!attribute template_link
     # @return [String,nil] URI of the style from which the current style is derived
-    
+
     # @!attribute documentation_link
     # @return [String,nil] URI of style documentation
-    [:self, :template, :documentation].each do |type|
-      method_id = "#{type}_link"
-      
+
+    # @!attribute independent_parent_link
+    # @return [String,nil] URI of independent-parent
+    %w{ self template documentation independent-parent }.each do |type|
+      method_id = "#{type.tr('-', '_')}_link"
+
       define_method method_id do
-        link = links.detect { |l| l.match? :rel => type.to_s }
+        link = links.detect { |l| l.match? :rel => type }
         link.nil? ? nil : link[:href]
       end
-      
+
       alias_method "has_#{method_id}?", method_id
-      
+
       define_method "#{method_id}=" do |value|
-        link = links.detect { |l| l.match? :rel => type.to_s }
-        
+        link = links.detect { |l| l.match? :rel => type }
+
         if link.nil?
-          set_child_link :href => value.to_s, :rel => type.to_s
+          set_child_link :href => value.to_s, :rel => type
         else
           link[:href] = value.to_s
           link
         end
       end
     end
-    
+
+    # Ruby 1.8 still has Object#id methods so the attr_children generator
+    # has not created those; since #id is deprecated in 1.8.7 we're
+    # forcing the override anyway. Live dangerously!
+
+    # @return [Id] the id text node
     def id
       children[:id]
     end
-    
+
     alias id= set_child_id
 
+    # @return [Time,nil] when the info node's parent was last updated
+    def updated_at
+      return unless has_updated?
+      updated.to_time
+    end
+
+    # Sets the updated_at timestamp.
+    # @return [self]
+    def update!(timestamp = Time.now)
+      ts = timestamp.respond_to?(:xmlschema) ? timestamp.xmlschema : timestamp.to_s
+      
+      if has_updated?
+        updated = Updated.new { |u| u.text = ts }
+      else
+        updated.text = ts
+      end
+      
+      self
+    end
+    
+    # @return [Time,nil] when the info node's parent was published
+    def published_at
+      return unless has_published?
+      published.to_time
+    end
+
+    # Sets the updated_at timestamp.
+    # @return [self]
+    def publish!(timestamp = Time.now)
+      ts = timestamp.respond_to?(:xmlschema) ? timestamp.xmlschema : timestamp.to_s
+      
+      if has_published?
+        published = Published.new { |u| u.text = ts }
+      else
+        published.text = ts
+      end
+      
+      self
+    end
+    
+    # @return [Symbol] the parent style's citation format
+    def citation_format
+      return unless has_categories?
+      
+    end
+    
+    def ciation_format=(new_format)
+    end
+
+    #
+    # Info Child Nodes
+    #
 
     class Contributor < Node
       attr_children :name, :email, :uri
     end
-    
+
     class Author < Node
       attr_children :name, :email, :uri
     end
-    
+
     class Translator < Node
       attr_children :name, :email, :uri
     end
-    
+
     class Link < Node
       attr_struct :href, :rel
+
+      # TODO xml:lang
     end
 
     class DependentStyle < TextNode
@@ -77,36 +173,55 @@ module CSL
 
     class Category < Node
       attr_struct :field, :'citation-format'
-    end    
+    end
 
     class Id < TextNode
     end
-    
+
     class Name < TextNode
     end
-    
+
     class Email < TextNode
     end
 
+    class URI < TextNode
+    end
+
     class Title < TextNode
+      # TODO xml:lang
     end
 
-    class ShortTitle < TextNode
+    class TitleShort < TextNode
+      # TODO xml:lang
     end
 
     class Summary < TextNode
+      # TODO xml:lang
     end
-    
+
     class Rights < TextNode
+      attr_struct :license
+      # TODO xml:lang
     end
 
-    class Uri < TextNode
+    class Updated < TextNode
+
+      def to_time
+        return if empty?
+        Time.parse(to_s)
+      end
+      alias to_date to_time
     end
 
-    class Updated < TextNode
+    class Published < TextNode
+      def to_time
+        return if empty?
+        Time.parse(to_s)
+      end
+      alias to_date to_time
     end
 
   end
-    
-  
+
+
 end

data/lib/csl/node.rb

@@ -1,16 +1,16 @@
 module CSL
-  
+
   class Node
-    
+
     extend Forwardable
-    
+
     include Enumerable
     include Comparable
-    
+
     include Treelike
     include PrettyPrinter
-    
-    
+
+
     class << self
 
       def inherited(subclass)
@@ -19,19 +19,19 @@ module CSL
           klass.types << subclass if klass < Node
         end
       end
-      
+
       def types
         @types ||= Set.new
       end
-      
+
       def default_attributes
         @default_attributes ||= {}
       end
-      
+
       def constantize(name)
-        pattern = /#{name.to_s.tr('-', '')}$/i
+        pattern = /:#{name.to_s.tr('-', '')}$/i
         klass = types.detect { |t| t.matches?(pattern) }
-        
+
         case
         when !klass.nil?
           klass
@@ -48,16 +48,16 @@ module CSL
         name_pattern === name
       end
       alias matches? match?
-      
+
       # Returns a new node with the passed in name and attributes.
       def create(name, attributes = {}, &block)
         klass = constantize(name)
 
-        node = (klass || Node).new(attributes, &block)        
+        node = (klass || Node).new(attributes, &block)
         node.nodename = name
         node
       end
-      
+
       def create_attributes(attributes)
         if const?(:Attributes)
           const_get(:Attributes).new(default_attributes.merge(attributes))
@@ -101,27 +101,27 @@ module CSL
           def values
             super.compact
           end
-          
+
           # def to_a
           #   keys.zip(values_at(*keys)).reject { |k,v| v.nil? }
           # end
-          
+
           # @return [Boolean] true if all the attribute values are nil;
           #   false otherwise.
           def empty?
             values.compact.empty?
           end
-          
+
           def fetch(key, default = nil)
             value = keys.include?(key.to_sym) && send(:'[]', key)
-            
-            if block_given? 
+
+            if block_given?
               value || yield(key)
             else
               value || default
             end
           end
-          
+
           # Merges the current with the passed-in attributes.
           #
           # @param other [#each_pair] the other attributes
@@ -162,14 +162,14 @@ module CSL
     attr_reader :attributes
 
     def_delegators :attributes, :[], :[]=, :values, :values_at, :length, :size
-    
+
     def initialize(attributes = {})
       @attributes = self.class.create_attributes(attributes)
       @children = self.class.create_children
-      
+
       yield self if block_given?
     end
-    
+
     # Iterates through the Node's attributes
     def each
       if block_given?
@@ -186,7 +186,7 @@ module CSL
     def attribute?(name)
       attributes.fetch(name, false)
     end
-    
+
     # Returns true if the node contains any attributes (ignores nil values);
     # false otherwise.
     def has_attributes?
@@ -202,7 +202,7 @@ module CSL
       File.open(path, 'w:UTF-8') do |f|
         f << (options[:compact] ? to_xml : pretty_print)
       end
-      
+
       self
     end
 
@@ -231,7 +231,7 @@ module CSL
     # @return [Boolean] whether or not the query matches the node
     def match?(name = nodename, conditions = {})
       name, conditions = match_conditions_for(name, conditions)
-      
+
       return false unless name === nodename
       return true  if conditions.empty?
 
@@ -265,10 +265,10 @@ module CSL
     # @return [Boolean] whether or not the query matches the node exactly
     def exact_match?(name = nodename, conditions = {})
       name, conditions = match_conditions_for(name, conditions)
-      
+
       return false unless name === nodename
       return true  if conditions.empty?
-      
+
       conditions.values_at(*attributes.keys).zip(
         attributes.values_at(*attributes.keys)).all? do |condition, value|
           condition === value
@@ -281,40 +281,40 @@ module CSL
     rescue
       nil
     end
-    
+
     # Returns the node' XML tags (including attribute assignments) as an
     # array of strings.
     def tags
       if has_children?
         tags = []
         tags << "<#{[nodename, *attribute_assignments].join(' ')}>"
-        
+
         tags << children.map { |node|
           node.respond_to?(:tags) ? node.tags : [node.to_s]
         }.flatten(1)
-        
+
         tags << "</#{nodename}>"
         tags
       else
         ["<#{[nodename, *attribute_assignments].join(' ')}/>"]
       end
     end
-    
+
     def inspect
       "#<#{[self.class.name, *attribute_assignments].join(' ')} children=[#{children.count}]>"
     end
-    
+
     alias to_s pretty_print
 
-    
+
     private
-        
+
     def attribute_assignments
       each_pair.map { |name, value|
         value.nil? ? nil: [name, value.to_s.inspect].join('=')
       }.compact
     end
-    
+
     def match_conditions_for(name, conditions)
       case name
       when Hash
@@ -327,15 +327,15 @@ module CSL
     end
 
   end
-  
-  
+
+
   class TextNode < Node
-    
+
     has_no_children
 
     class << self
       undef_method :attr_children
-      
+
       # @override
       def create(name, attributes = {}, &block)
         klass = constantize(name)
@@ -347,19 +347,22 @@ module CSL
     end
 
     attr_accessor :text
-    alias to_s text
+
+    def to_s
+      text.to_s.strip
+    end
 
     # TextNodes quack like a string.
     # def_delegators :to_s, *String.instance_methods(false).reject do |m|
     #   m.to_s =~ /^\W|!$|(?:^(?:hash|eql?|to_s|length|size|inspect)$)/
     # end
-    # 
+    #
     # String.instance_methods(false).select { |m| m.to_s =~ /!$/ }.each do |m|
     #   define_method(m) do
     #     content.send(m) if content.respond_to?(m)
     #   end
     # end
-    
+
     def initialize(argument = '')
       case
       when argument.is_a?(Hash)
@@ -372,19 +375,23 @@ module CSL
         raise ArgumentError, "failed to create text node from #{argument.inspect}"
       end
     end
-    
+
     def textnode?
       true
     end
-    
+
+    def empty?
+      text.nil? || text.empty?
+    end
+
     def tags
       ["<#{attribute_assignments.unshift(nodename).join(' ')}>#{text}</#{nodename}>"]
     end
-    
+
     def inspect
       "#<#{[self.class.name, text.inspect, *attribute_assignments].join(' ')}>"
     end
-    
+
   end
-  
+
 end