citeproc 0.0.8 → 0.0.9

data/lib/citeproc/variable.rb

@@ -1,10 +1,12 @@
 
 module CiteProc
-  
-  #
+
   # A CiteProc Variable represents the content of a text, numeric, date, or
-  # name variable.
+  # name variable. In its basic form it is thin abstraction that behaves
+  # almost like a regular Ruby string; more complex Variables are handled
+  # by dedicated sub-classes that make the variable's type more explicit.
   #
+  # @abstract
   class Variable
 
     extend Forwardable
@@ -12,29 +14,29 @@ module CiteProc
     
     @fields = Hash.new { |h,k| h.fetch(k.to_sym, nil) }.merge({
       :date => %w{
-				accessed container event-date issued original-date submitted
-			},
+        accessed container event-date issued original-date submitted
+      },
 
       :names => %w{
-				author collection-editor composer container-author recipient editor
-				editorial-director illustrator interviewer original-author translator
-			},
+        author collection-editor composer container-author recipient editor
+        editorial-director illustrator interviewer original-author translator
+      },
+      
+      :number => %w{
+        chapter-number collection-number edition issue number number-of-pages
+        number-of-volumes volume        
+      },
       
-			:number => %w{
-				chapter-number collection-number edition issue number number-of-pages
-				number-of-volumes volume				
-			},
-			
       :text => %w{
-				abstract annote archive archive_location archive-place authority
-				call-number citation-label citation-number collection-title
-				container-title container-title-short dimensions DOI event event-place
-				first-reference-note-number genre ISBN ISSN jurisdiction keyword
-				locator medium note original-publisher original-publisher-place
-				original-title page page-first PMID PMCID publisher publisher-place
-				references section source status title title-short URL version
-				year-suffix
-			}
+        abstract annote archive archive_location archive-place authority
+        call-number citation-label citation-number collection-title
+        container-title container-title-short dimensions DOI event event-place
+        first-reference-note-number genre ISBN ISSN jurisdiction keyword
+        locator medium note original-publisher original-publisher-place
+        original-title page page-first PMID PMCID publisher publisher-place
+        references section source status title title-short URL version
+        year-suffix
+      }
     })
     
     @fields.each_value { |v| v.map!(&:to_sym) }
@@ -52,37 +54,92 @@ module CiteProc
 
     @fields.freeze
 
-		@markup = /<[^>]*>/.freeze
-		
-		
+    @markup = /<[^>]*>/.freeze
+    
+    
     class << self
-	
-      attr_reader :fields, :types, :markup, :factories
+  
+      # @!attribute [r] fields
+      # @return [{Symbol => Array<Symbol>}] mapping of variable types to
+      #   their respective field names
+      attr_reader :fields
+      
+      # @!attribute [r] types
+      # @return [{Symbol => Symbol}] mapping of field names to variable types
+      attr_reader :types
+      
+      # @!attribute [r] factories
+      # @return [{Symbol => Class}] mapping of field names to their respective
+      #   Variable classes
+      attr_reader :factories
+
+      # @!attribute markup
+      # @return [Regexp] pattern used to strip markup off values
+      attr_accessor :markup
+      
+      # Creates a new {Variable} instance using the passed-in field name
+      # to distinguish which {Variable} class to use as factory. This
+      # method returns nil if the creation fails.
+      #
+      # @see .create!
+      #
+      # @example
+      #   Variable.create('foo')
+      #   #-> #<CiteProc::Variable "foo">
+      #
+      #   Variable.create('foo', :title)
+      #   #-> #<CiteProc::Text "foo">
+      #
+      #   Variable.create(['Matz', 'Flanagan'], :author)
+      #   #-> #<CiteProc::Names "Matz & Flanagan">
+      #
+      #   Variable.create(2009, :issued)
+      #   #-> #<CiteProc::Date "2009-01-01">
+      #
+      # @param value [Object] the variable's value
+      # @param field [Symbol] the value's field name
+      #
+      # @return [Variable] a new {Variable} (or sub-class) instance
+      def create(value, field = nil)
+        create!(value, field)
+      rescue
+        nil
+      end
+      
       
-			def create(value, type = nil)
-				create!(value, type)
-			rescue
-				nil
-			end
-			
-      def create!(value, type = nil)
-				factory = factories[type]
-				value.is_a?(factory) ? value : factory.new(value)
+      # Creates a new {Variable} instance using the passed-in field name
+      # to distinguish which {Variable} class to use as factory.
+      #
+      # @see .create
+      #
+      # @raise [TypeError] if no variable can be created for the given value
+      #   and type
+      #
+      # @param value [Object] the variable's value
+      # @param field [Symbol] the variable's field name
+      #
+      # @return [Variable] a new {Variable} (or sub-class) instance
+      def create!(value, field = nil)
+        factory = factories[field]
+        value.is_a?(factory) ? value : factory.new(value)
       end
 
     end
-    
+
+    # @!attribute value
+    # @return [Object] the value wrapped by this variable
     attr_accessor :value
 
     def_delegators :@value, :to_s,
-			*::String.instance_methods(false).select {|m| m.to_s =~ /!$/ }
+      *::String.instance_methods(false).select {|m| m.to_s =~ /!$/ }
     
     def_delegators :to_s, :=~, :===,
-			*::String.instance_methods(false).reject {|m| m.to_s =~ /^\W|!$|to_s/ }
+      *::String.instance_methods(false).reject {|m| m.to_s =~ /^\W|!$|to_s/ }
 
+    
+    # Creates new Variable for the passed-in value
     def initialize(value = nil)
       replace(value)
-      yield self if block_given?
     end
     
     def initialize_copy(other)
@@ -90,72 +147,94 @@ module CiteProc
     end
     
 
-		# The replace method is typically called by the Variable's constructor. It
-		# will try to set the Variable to the passed in value and should accept
-		# a wide range of argument types; subclasses (especially Date and Names)
-		# override this method.
-		def replace(value)
-			raise TypeError, "failed to set value to #{value.inspect}" unless value.respond_to?(:to_s)
-			@value = value.to_s
-			self
-		end
+    # The replace method is typically called by the Variable's constructor. It
+    # will try to set the Variable to the passed in value and should accept
+    # a wide range of argument types; subclasses (especially Date and Names)
+    # override this method.
+    #
+    # @raise [TypeError] if the variable cannot be set to the passed-in value
+    #
+    # @param value [Object] the variable's new value
+    # @return [self]
+    def replace(value)
+      raise TypeError, "failed to set value to #{value.inspect}" unless value.respond_to?(:to_s)
+      @value = value.to_s
+      self
+    end
 
-		def type
-			@type ||= self.class.name.split(/::/)[-1].downcase.to_sym
-		end
+    # @return [Symbol] the variable's type
+    def type
+      @type ||= self.class.name.split(/::/)[-1].downcase.to_sym
+    end
 
-		# Returns true if the Variable can be (safely) cast to a numeric value.
+    # @return [Boolean] whether or not the variable can be (safely) cast to a numeric value
     def numeric?
-      match(/\d/) ? to_i : false
+      !!match(/\d/)
     end
     
-    # Returns (first) numeric data contained in the variable's value
+    # @return [Fixnum] the first (!) numeric data contained in the variable's
+    #   value; zero if no numeric data is present
     def to_i
-     to_s =~ /(-?\d+)/ && $1.to_i || 0
+     to_s =~ /([+-]?\d+)/ && $1.to_i || 0
     end
     
+    # @return [Float] the first (!) numeric or floating point data contained
+    #   in the variable's value; zero if no numeric data is present
     def to_f
-      to_s =~ /(-?\d[\d,\.]*)/ && $1.tr(',','.').to_f || 0.0
+      to_s =~ /([+-]?\d[\d,\.]*)/ && $1.tr(',','.').to_f || 0.0
     end
     
+    # @return [String] the variable's value stripped of markup
     def strip_markup
       gsub(Variable.markup, '')
     end
     
+    # Strips markup off the variable's value.
+    # @return [self]
     def strip_markup!
       gsub!(Variable.markup, '')
     end 
     
+    # Compares the variable with the passed-in value. If other responds
+    # to {#strip_markup} the stripped strings will be compared; otherwise
+    # both objects will be converted to and compared as strings.
+    #
+    # @param other [Object] the object used for comparison
+    # @return [Fixnum,nil] -1, 0, or 1 depending on the result of the
+    #   comparison; or nil if the two objects cannot be ignored.
     def <=>(other)
       case
       when other.respond_to?(:strip_markup)
         strip_markup <=> other.strip_markup
-
       when other && other.respond_to?(:to_s)
         to_s <=> other.to_s
-
       else
         nil
       end
     end
+
+    # @!method to_s
+    # @return [String] the variable's value as a string
+    alias to_citeproc to_s
     
-		alias to_citeproc to_s
-		
+    # @return [String] a JSON string representation of the variable
     def to_json
       MultiJson.encode(to_citeproc)
     end
 
-		def inspect
-			"#<#{self.class.name}: #{to_s.inspect}>"
-		end
-		
+    # @return [String] a human-readable representation of the variable
+    def inspect
+      "#<#{self.class.name} #{to_s.inspect}>"
+    end
+    
   end
 
+  # A CiteProc Variable used for string values.
+  class Text < Variable
+  end
 
-	class Text < Variable
-	end
-
-	class Number < Variable
-	end
+  # A CiteProc Variable used for numeric values.
+  class Number < Variable
+  end
 
 end

data/lib/citeproc/version.rb

@@ -1,3 +1,3 @@
 module CiteProc
-  VERSION = '0.0.8'.freeze
+  VERSION = '0.0.9'.freeze
 end

data/spec/citeproc/assets_spec.rb

@@ -1,6 +1,3 @@
-require 'spec_helper'
-require 'tempfile'
-
 module CiteProc
 
 	describe 'Assets' do
@@ -56,9 +53,18 @@ module CiteProc
 				it 'returns the given string if it looks like XML' do
 					Style.open('<b>foo bar!</b>').to_s.should == '<b>foo bar!</b>'
 				end
-
 			end
 
+      describe '.extend_name' do
+        it 'adds the default extension if the file does not already end with it' do
+          Style.extend_name(name.sub(/#{extension}$/,'')).should == name
+        end
+        
+        it 'does not add the default extension if the file already ends with it' do
+          Style.extend_name(name).should == name
+        end
+      end
+      
 		end
 	end
 end

data/spec/citeproc/date_spec.rb

@@ -3,6 +3,101 @@ require 'spec_helper'
 module CiteProc
   describe Date do
     
+    class Date
+      describe DateParts do
+        it { should_not be_nil }
+        it { should be_empty }
+      
+        describe 'sorting' do
+          it 'treats [2003] as less than [2003,1]' do
+            DateParts.new(2003).should be < DateParts.new(2003,1)
+          end
+
+          it 'treats [1992,9,23] as less than [1993,8,22]' do
+            DateParts.new(1992,9,23).should be < DateParts.new(1993,8,22)
+          end
+
+          it 'treats [1992,9,23] as less than [1992,10,22]' do
+            DateParts.new(1992,9,23).should be < DateParts.new(1992,10,22)
+          end
+
+          it 'treats [1992,9,23] as less than [1992,9,24]' do
+            DateParts.new(1992,9,23).should be < DateParts.new(1992,9,24)
+          end
+
+          it 'treats [-50] as less than [-25]' do
+            DateParts.new(-50).should be < DateParts.new(-25)
+          end
+
+          it 'treats [-50] as less than [-50,12]' do
+            DateParts.new(-50).should be < DateParts.new(-50,12)
+          end
+          
+          it 'treats [1994,1,23] as less than today' do
+            DateParts.new(1994,1,23).should be < ::Date.today
+          end          
+        end
+        
+        describe '#dup' do
+          let(:date) { DateParts.new(1991,8,22) }
+          
+          it 'creates a copy that contains the same parts' do
+            date.dup.to_a.should == [1991,8,22]
+          end
+          
+          it 'does not return self' do
+            date.dup.should_not equal(date)
+            date.dup.should == date
+          end
+        end
+        
+        describe '#update' do
+          it 'accepts a hash' do
+            DateParts.new.update(:month => 2, :year => 80).to_a.should == [80,2,nil]
+          end
+          
+          it 'accepts an array' do
+            DateParts.new.update([80,2]).to_a.should == [80,2,nil]
+          end
+        end
+        
+        describe '#strftime' do
+          it 'formats the date parts according to the format string' do
+            DateParts.new(1998,2,4).strftime('FOO %0m%0d%y').should == 'FOO 020498'
+          end
+        end
+        
+        describe 'to_citeproc' do
+          it 'returns an empty list by default' do
+            DateParts.new.to_citeproc.should == []
+          end
+          
+          it 'returns a list with the year if only the year is set' do
+            DateParts.new(2001).to_citeproc.should == [2001]
+          end
+
+          it 'supports zero parts' do
+            DateParts.new(0,0).to_citeproc.should == [0,0]
+          end
+        end
+        
+        describe '#open?' do
+          it 'returns false by default' do
+            DateParts.new.should_not be_open
+          end
+          
+          it 'returns false for [1999,8,24]' do
+            DateParts.new(1999, 8, 24).should_not be_open
+          end
+          
+          it 'returns true for [0]' do
+            DateParts.new(0).should be_open
+          end
+        end
+      end
+    end
+    
+    
     let(:ad2k) { Date.create('date-parts' => [[2000]])}
     let(:may) { Date.create('date-parts' => [[2000, 5]])}
     let(:first_of_may) { Date.create('date-parts' => [[2000, 5, 1]])}
@@ -17,11 +112,68 @@ module CiteProc
     it { should_not be_numeric }
     
     describe '.new' do
+      it 'accepts a hash as input' do
+        Date.new(:literal => 'Summer').to_s.should == 'Summer'
+      end
+
+      it 'accepts a hash as input and converts date parts' do
+        Date.new(:'date-parts' => [[2003,2]]).parts[0].should be_a(Date::DateParts)
+      end
+      
+      it 'accepts a fixnum and treats it as the year' do
+        Date.new(1666).year.should == 1666
+      end
+      
+      it 'accepts a date' do
+        Date.new(::Date.new(1980,4)).month.should == 4
+      end
+      
+      it 'accepts a date and creates date parts' do
+        Date.new(::Date.new(1980,4)).parts[0].to_citeproc.should == [1980,4,1]
+      end
+      
+      it 'is empty by default' do
+        Date.new.should be_empty
+      end
+
+      it 'accepts date strings' do
+        Date.new('2009-03-19').day.should == 19
+      end
+
+      it 'accepts JSON strings' do
+        Date.new('{ "date-parts": [[2001,1,19]]}').day.should == 19
+      end
+
+      it 'accepts date parts in an array' do
+        Date.new([2009,3]).month.should == 3
+      end
+
+      it 'accepts ranges as an array' do
+        Date.new([[2009],[2012]]).should be_range
+      end
+
+      it 'accepts year ranges' do
+        Date.new(2009..2012).should be_range
+      end
+
+      it 'accepts exclusive date ranges' do
+        Date.new(::Date.new(2009) ... ::Date.new(2011)).end_date.year.should == 2010
+      end
+
+      it 'accepts inclusive date ranges' do
+        Date.new(::Date.new(2009) .. ::Date.new(2011)).end_date.year.should == 2011
+      end
       
+      it 'accepts EDTF date strings' do
+        Date.new('2009?-03-19').should be_uncertain
+      end
+
+      it 'accepts EDTF intervals' do
+        Date.new('2009-03-19/2010-11-21').parts.map(&:to_citeproc).should == [[2009,3,19],[2010,11,21]]
+      end
     end
     
 		describe '.parse' do
-			
 			it 'returns nil by default' do
 				Date.parse('').should be nil
 				Date.parse(nil).should be nil
@@ -38,6 +190,32 @@ module CiteProc
       end
     end
     
+    describe '#dup' do
+      let(:date) { Date.new([1991,8]) }
+      
+      it 'creates a copy that contains the same parts' do
+        date.dup.parts.map(&:to_citeproc).should == [[1991,8]]
+      end
+
+      it 'copies uncertainty' do
+        date.dup.should_not be_uncertain
+        date.uncertain!.dup.should be_uncertain
+      end
+      
+      it 'makes a deep copy of attributes' do
+        expect { date.dup.uncertain! }.not_to change { date.uncertain? }
+      end
+      
+      it 'makes a deep copy of date parts' do
+        expect { date.dup.parts[0].update(:year => 2012) }.not_to change { date.year }
+      end
+      
+      it 'does not return self' do
+        date.dup.should_not equal(date)
+        date.dup.should == date
+      end
+    end
+    
     describe 'literal dates' do      
       it 'is not literal by default' do
         Date.new.should_not be_literal
@@ -51,16 +229,36 @@ module CiteProc
         Date.create('date-parts' => [[2000]], :literal => 'foo').should be_literal
       end
     end
+
+    describe 'seasons' do
+      it 'is no season by default' do
+        Date.new.should_not be_season
+      end
+      
+      it 'is a season if contains only a season field' do
+        Date.new(:season => 'Winter').should be_season
+      end
+
+      it 'is a season if contains a season field' do
+        Date.new(:'date-parts' => [[2001]], :season => 'Winter').should be_season
+      end      
+    end
     
     describe 'uncertain dates' do
       it 'are uncertain' do
         Date.new({ 'date-parts' => [[-225]], 'circa' => '1' }).should be_uncertain
-        Date.new { |d| d.parts = [[-225]]; d.uncertain! }.should be_uncertain
+        Date.new { |d| d.parts = [[-225]]; d.uncertain! }.should_not be_certain
+      end
+      
+      describe '#(un)certain!' do
+        it 'returns self' do
+          ad2k.uncertain!.should equal(ad2k)
+          ad2k.certain!.should equal(ad2k)
+        end
       end
     end
     
     describe 'sorting' do
-      
       it 'dates with more date-parts will come after those with fewer parts' do
         (ad2k < may  && may < first_of_may).should be true
       end
@@ -68,8 +266,42 @@ module CiteProc
       it 'negative years are sorted inversely' do
         [ad50, bc100, bc50, ad100].sort.map(&:year).should == [-100, -50, 50, 100]
       end
+      
+      it 'can be compared to dates' do
+        ad50.should be < ::Date.new(50,2)
+        ad50.should be > ::Date.new(49)
+      end
+    end
+
+    describe '#start_date' do
+      it 'returns nil by default' do
+        Date.new.start_date.should be_nil
+      end
+      
+      it 'returns a ruby date when date-parts are set' do
+        Date.new(1999).start_date.year.should == 1999
+      end
     end
 
+    describe '#end_date' do
+      it 'returns nil by default' do
+        Date.new.end_date.should be_nil
+      end
+      
+      it 'returns nil when there is a single date-parts set' do
+        Date.new(1312).end_date.should be_nil
+      end
+      
+      it 'returns a ruby date when date-parts are a closed range' do
+        Date.new(1999..2000).end_date.year.should == 2000
+      end
+    end
+    
+    describe '#-@' do
+      it 'inverts the year' do
+        (-ad50).should == bc50
+      end
+    end
 
     describe '#display' do
       it 'returns an empty string by default' do
@@ -114,21 +346,49 @@ module CiteProc
 			it 'today is not b.c.' do
 				Date.today.should_not be_bc
 			end
-			
+
 			it 'the year 2000 is not a.d.' do
 				ad2k.should_not be_ad
 			end
 			
 		end
 		
+		describe '#empty?' do
+		  it 'returns true by default' do
+		    Date.new.should be_empty
+		  end
+		  
+		  it 'returns true when it contains no date parts' do
+		    Date.new({}).should be_empty
+		  end
+		  
+		  it 'returns false for today' do
+		    Date.today.should_not be_empty
+		  end
+		  
+		  it 'returns false for literal dates' do
+		    Date.new(:literal => 'foo').should_not be_empty
+		  end
+
+		  it 'returns false for seasons' do
+		    Date.new(:season => 'Summer').should_not be_empty
+		  end
+		end
+				
     describe '#to_json' do    
       it 'supports simple parts' do
         Date.new(%w{2000 1 15}).to_json.should == '{"date-parts":[[2000,1,15]]}'
       end
 
-      it 'supports integers and strings parts' do
+      it 'supports string parts' do
         Date.new(['2000', '1', '15']).to_json.should == '{"date-parts":[[2000,1,15]]}'
+      end
+
+      it 'supports integer parts' do
         Date.new([2000, 1, 15]).to_json.should == '{"date-parts":[[2000,1,15]]}'
+      end
+        
+      it 'supports mixed parts' do
         Date.new(['2000', 1, '15']).to_json.should == '{"date-parts":[[2000,1,15]]}'
       end
 
@@ -136,9 +396,12 @@ module CiteProc
         Date.new(-200).to_json.should == '{"date-parts":[[-200]]}'
       end
 
+      it 'treats seasons as a strings' do
+        Date.create({:season => '1', 'date-parts' => [[1950]]}).to_json.should =~ /"season":"1"/
+      end
+      
       it 'supports seasons' do
-        Date.create({:season => '1', 'date-parts' => [[1950]]}).to_json.should == '{"date-parts":[[1950]],"season":"1"}'
-        Date.create({:season => 'Trinity', 'date-parts' => [[1975]]}).to_json.should == '{"date-parts":[[1975]],"season":"Trinity"}'
+        Date.create({:season => 'Trinity', 'date-parts' => [[1975]]}).to_json.should =~ /"season":"Trinity"/
       end
 
       it 'supports string literals' do
@@ -149,8 +412,11 @@ module CiteProc
         Date.new(:raw => '23 May 1955').to_json.should == '{"date-parts":[[1955,5,23]]}'
       end
 
-      it 'supports open and closed ranges' do
+      it 'supports closed ranges' do
         Date.new([[2000,11],[2000,12]]).to_json.should == '{"date-parts":[[2000,11],[2000,12]]}'
+      end
+      
+      it 'supports open ranges' do
         Date.new([[2000,11],[0,0]]).to_json.should == '{"date-parts":[[2000,11],[0,0]]}'
       end
     end