citeproc 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db40316ba1ffbee282afc7c803b98fc2205c4687f2ccfad319661ce8bccacbaa
-  data.tar.gz: 0c95ef58ae66fb9101dce5e91d70b760ed93dc6aa15a1ce18356af1b38c9a2af
+  metadata.gz: 8708658d44ed66deb17744c846697187edbcd1f6dc308c4bf3bc69933ede3e7e
+  data.tar.gz: 1d1af4037b6dae14f20adffdbb7e51b35ecd02728586f95932348416788347c1
 SHA512:
-  metadata.gz: 2db1938d6f1f5b8248f5e9f97d1c242055a695cd2dea7b26f96cfe8b7bdca30eed1e21fe9630adc96b2f22920c117cacf8255dfb18de10e034e80745c084f157
-  data.tar.gz: 339dea1c644ca79ca5379d2094b4f08f1fa41058053f511fd0e52b072349a880a3b8721e2ed82498b50ded6f74b57eff42eebc6a77e2cb70dbd9f2643870a601
+  metadata.gz: 4dc2d276583d4071cf17459265a3c706f8eb4091c59527a80506241e8f5187de4eba9f6cb140e560327fde38f8e8225348818dfeda0e1b2b98ef53acb67c5064
+  data.tar.gz: 33de631e29bd0e3484a0509e4f61bfb4e2b59fe87aeb8e7cbd25c1d9065ce20588637725f00d9f88ab2e19bcee765d3a19bc71d25adced9135d6a74627018279

data/README.md

@@ -1,9 +1,10 @@
 CiteProc
 ========
-CiteProc is a cite processor interface and citation data API based on the
-Citation Style Language (CSL) specifications. To actually process citations
-a dedicated processor engine is required; a pure Ruby engine is available
-in the [citeproc-ruby](https://rubygems.org/gems/citeproc-ruby) gem.
+CiteProc is a cite processor interface and citation data API
+based on the Citation Style Language (CSL) specifications.
+To actually process citations a dedicated processor engine is required;
+a pure Ruby engine is available in the
+[citeproc-ruby](https://rubygems.org/gems/citeproc-ruby) gem.
 
 Quickstart
 ----------
@@ -12,117 +13,117 @@ Install CiteProc-Ruby and all official CSL styles (optional).
     $ [sudo] gem install citeproc-ruby
     $ [sudo] gem install csl-styles
 
-Start rendering you references with any CSL style!
+Start rendering your references with any CSL style!
 
     require 'citeproc'
     require 'csl/styles'
+    require 'bibtex'
 
-    # Create a new processor with the desired style,
-    # format, and locale.
+    # Create a new processor
+    # with the desired style, format, and locale.
     cp = CiteProc::Processor.new style: 'apa', format: 'text'
 
-    # To see what styles are available in your current
-    # environment, run `CSL::Style.ls'; this also works for
-    # locales as `CSL::Locale.ls'.
+    # To see what styles are available in your current environment,
+    # run `CSL::Style.ls';
+    # this also works for locales as `CSL::Locale.ls'.
 
-    # Tell the processor where to find your references. In this
-    # example we load them from a BibTeX bibliography using the
-    # bibtex-ruby gem.
+    # Tell the processor where to find your references.
+    # In this example we load them from a BibTeX bibliography
+    # using the bibtex-ruby gem (`gem install bibtex-ruby').
     cp.import BibTeX.open('./references.bib').to_citeproc
 
-    # Now you are ready for rendering; the processor API
-    # provides three main rendering methods: `process',
-    # `append', or `bibliography'.
+    # Now you are ready for rendering;
+    # the processor API provides two main rendering methods:
+    # `process' and `bibliography'.
 
-    # For simple one-off renditions, you can also call
-    # `render' in bibliography or citation mode:
+    # For simple one-off renditions,
+    # you can also call `render' in bibliography or citation mode:
     cp.render :bibliography, id: 'knuth'
 
     # This will return a rendered reference, like:
-    #-> Knuth, D. (1968). The art of computer programming. Boston: Addison-Wesley.
-
-    # CiteProc-Ruby exposes a full CSL API to you; this
-    # makes it possible to just alter CSL styles on the
-    # fly. For example, what if we want names not to be
-    # initialized even though APA style is configured to
-    # do so? We could change the CSL style itself, but
-    # we can also make a quick adjustment at runtime:
-    name = cp.engine.style.macros['author'] > 'names' > 'name'
-
-    # What just happened? We selected the current style's
-    # 'author' macro and then descended to the CSL name
-    # node via its parent names node. Now we can change
-    # this name node and the cite processor output will
-    # pick-up the changes right away:
-    name[:initialize] = 'false'
+    #-> Knuth, D. (1968). The art of computer programming (Vol. 1). Addison-Wesley.
+
+    # CiteProc-Ruby exposes a full CSL API to you;
+    # this makes it possible to just alter CSL styles on the fly.
+    # For example, what if we want names not to be initialized
+    # even though APA style is configured to do so?
+    # We could change the CSL style itself,
+    # but we can also make a quick adjustment at runtime:
+    cp.engine.style.macros['author-bib'].each_descendant do |node|
+      node[:initialize] = 'false' if node.nodename == 'name'
+    end
+
+    # What just happened?
+    # We selected the current style's 'author-bib' macro
+    # and changed all of its CSL name nodes;
+    # the cite processor output will pick-up the changes right away:
 
     cp.render :bibliography, id: 'knuth'
-    #-> Knuth, Donald. (1968). The art of computer programming (Vol. 1). Boston: Addison-Wesley.
+    #-> Knuth, Donald. (1968). The art of computer programming (Vol. 1). Addison-Wesley.
 
     # Note that we have picked 'text' as the output format;
-    # if we want to make us of richer output formats we
-    # can switch to HTML instead:
+    # if we want to make use of richer output formats
+    # we can switch to HTML instead:
     cp.engine.format = 'html'
 
     cp.render :bibliography, id: 'knuth'
-    #-> Knuth, Donald. (1968). <i>The art of computer programming</i> (Vol. 1). Boston: Addison-Wesley.
+    #-> Knuth, Donald. (1968). <i>The art of computer programming</i> (Vol. 1). Addison-Wesley.
 
     # You can also render citations on the fly.
-    cp.render :citation, id: 'knuth', locator: '23'
+    cp.render :citation, id: 'knuth', locator: '23', label: 'page'
     #-> (Knuth, 1968, p. 23)
 
 Documentation
 -------------
-* [CiteProc Documentation](http://rubydoc.info/gems/citeproc/)
-* [CiteProc-Ruby API Documentation](http://rubydoc.info/gems/citeproc-ruby/)
-* [CSL-Ruby API Documentation](http://rubydoc.info/gems/csl/)
+* [CiteProc Documentation](https://rubydoc.info/gems/citeproc/)
+* [CiteProc-Ruby API Documentation](https://rubydoc.info/gems/citeproc-ruby/)
+* [CSL-Ruby API Documentation](https://rubydoc.info/gems/csl/)
 
 Optional Dependencies
 ---------------------
 CiteProc-Ruby tries to minimize hard dependencies for increased compatibility.
 You can speed up the XML parsing by installing
-[Nokogiri](https://rubygems.org/gems/nokogiri); otherwise the REXML from the
-Ruby standard library will be used.
+[Nokogiri](https://rubygems.org/gems/nokogiri);
+otherwise the REXML from the Ruby standard library will be used.
 
-Similarly, you can install either of the gems
-[EDTF](https://rubygems.org/gems/edtf) or
-[Chronic](https://rubygems.org/gems/chronic) to support a wide range of
-additional inputs for date variables.
+Similarly, you can install the
+[EDTF](https://rubygems.org/gems/edtf)
+gem to support a wide range of additional inputs for date variables.
 
 CSL Styles and Locales
 ----------------------
-You can load CSL styles and locales by passing a respective XML string, file
-name, or URL. You can also load styles and locales by name if the
-corresponding files are installed in your local styles and locale directories.
+You can load CSL styles and locales
+by passing a respective XML string, file name, or URL.
+You can also load styles and locales by name
+if the corresponding files are installed
+in your local styles and locale directories.
 By default, CSL-Ruby looks for CSL styles and locale files in
 
     /usr/local/share/csl/styles
     /usr/local/share/csl/locales
 
-You can change these locations by changing the value of `CSL::Style.root` and
-`CSL::Locale.root` respectively.
+You can change these locations
+by changing the value of `CSL::Style.root` and `CSL::Locale.root` respectively.
 
-Alternatively, you can `gem install csl-styles` to install all official CSL
-styles and locales. To make the styles and locales available, simply
-`require 'csl/styles`.
-
-Compatibility
--------------
-The cite processor and the CSL API libraries have been developed for MRI,
-Rubinius, and JRuby. Please note that we try to support only Ruby versions
-1.9.3 and upwards.
+Alternatively, you can `gem install csl-styles`
+to install all official CSL styles and locales.
+To make the styles and locales available,
+simply `require 'csl/styles'`.
 
 Credits
 -------
 Thanks to Rintze M. Zelle, Sebastian Karcher, Frank G. Bennett, Jr.,
-and Bruce D'Arcus of CSL and citeproc-js fame for their support!
+and Bruce D'Arcus of CSL and citeproc-js fame
+for their support!
 
-Thanks to Google and the Berkman Center at Harvard University for supporting
-this project as part of [Google Summer of Code](https://developers.google.com/open-source/soc/).
+Thanks to Google and the Berkman Center at Harvard University
+for supporting this project as part of
+[Google Summer of Code](https://developers.google.com/open-source/soc/).
 
 Copyright
 ---------
-Copyright 2009-2025 Sylvester Keil. All rights reserved.
+Copyright 2009-2026 Sylvester Keil.
+All rights reserved.
 
 Copyright 2012 President and Fellows of Harvard College.
 

data/lib/citeproc/attributes.rb

@@ -37,7 +37,7 @@ module CiteProc
       return false if value.nil?
       return false if value.respond_to?(:empty?) && value.empty?
 
-      value.to_s !~ /^(false|no|never)$/i
+      value.to_s !~ /^(false|no|never|0)$/i
     end
 
     def filter_key(key)
@@ -108,7 +108,7 @@ module CiteProc
       case
       when equal?(other)
         true
-      when self.class != other.class, length != other.length
+      when self.class != other.class, attributes.length != other.attributes.length
         false
       else
         other.attributes.each_pair do |key, value|

data/lib/citeproc/bibliography.rb

@@ -193,7 +193,7 @@ module CiteProc
     end
 
     def hanging_indent?
-      options[:'hanging_indent']
+      CiteProc.boolean(options[:'hanging-indent'])
     end
 
     def join()

data/lib/citeproc/citation_data.rb

@@ -11,12 +11,72 @@ module CiteProc
     include Comparable
 
     @labels = [
-      :book, :chapter, :column, :figure, :folio, :issue, :line, :note, :opus,
-      :page, :paragraph, :part, :section, :'sub-verbo', :verse, :volume
+      :act,
+      :appendix,
+      :'article-locator',
+      :book,
+      :canon,
+      :chapter,
+      :column,
+      :elocation,
+      :equation,
+      :figure,
+      :folio,
+      :issue,
+      :line,
+      :note,
+      :opus,
+      :page,
+      :paragraph,
+      :part,
+      :rule,
+      :scene,
+      :section,
+      :'sub-verbo',
+      :supplement,
+      :table,
+      :timestamp,
+      :'title-locator',
+      :verse,
+      :version,
+      :volume
     ].freeze
 
+    # Abbreviations of locator labels (for extraction)
+    @locator_abbreviations = {
+      'app.' => 'appendix',
+      'art.' => 'article-locator',
+      'bk.' => 'book',
+      'ch.' => 'chapter',
+      'col.' => 'column',
+      'fig.' => 'figure',
+      'fol.' => 'folio',
+      'l.' => 'line',
+      'n.' => 'note',
+      'no.' => 'issue',
+      'op.' => 'opus',
+      'p.' => 'page',
+      'pp.' => 'page',
+      'para.' => 'paragraph',
+      'pt.' => 'part',
+      'r.' => 'rule',
+      'sec.' => 'section',
+      'supp.' => 'supplement',
+      'sv.' => 'sub-verbo',
+      'tbl.' => 'table',
+      'tit.' => 'title-locator',
+      'vol.' => 'volume',
+      'vrs.' => 'verse'
+    }.freeze
+
     class << self
-      attr_reader :labels
+      attr_reader :labels, :locator_abbreviations
+
+      # @param abbreviations [Hash<String,String>] label abbreviations
+      # @return [Regexp] a pattern matching any of the abbreviations
+      def locator_label_pattern(abbreviations = locator_abbreviations)
+        Regexp.union(abbreviations.keys.sort_by { |abbr| -abbr.length })
+      end
     end
 
     # @!attribute id
@@ -66,6 +126,32 @@ module CiteProc
       yield self if block_given?
     end
 
+    # @return [String, nil] the locator label;
+    #   defaults to "page" if there is a locator
+    def label
+      read_attribute(:label) || ('page' if locator?)
+    end
+
+    # Moves a label at the start of the locator into the label
+    # (e.g., "vol. 1" becomes "1" with the label "volume") unless
+    # the item has a label other than "page".
+    #
+    # @param abbreviations [Hash<String,String>] label abbreviations
+    # @return [self]
+    def parse_locator!(abbreviations = CitationItem.locator_abbreviations)
+      return self unless locator? && label.to_s == 'page'
+
+      pattern = CitationItem.locator_label_pattern(abbreviations)
+      match = /\A(#{pattern})\s+(.+)\z/m.match(locator.to_s)
+
+      unless match.nil?
+        self.label = abbreviations[match[1]]
+        self.locator = match[2]
+      end
+
+      self
+    end
+
     def initialize_copy(other)
       @attributes = other.attributes.deep_copy
     end
@@ -83,8 +169,6 @@ module CiteProc
   end
 
 
-
-
   class CitationData
 
     extend Forwardable

data/lib/citeproc/compatibility.rb

@@ -7,8 +7,6 @@
 if RUBY_PLATFORM =~ /java/i
   require 'java'
 
-  puts java.lang.System.getProperty('file.encoding')
-
   module CiteProc
     def upcase(string)
       java.lang.String.new(string).to_upper_case(java.util.Locale::ENGLISH).to_s
@@ -22,39 +20,12 @@ if RUBY_PLATFORM =~ /java/i
 else
 
   module CiteProc
-    if RUBY_VERSION >= '2.4'
-      def upcase(string)
-        string.upcase
-      end
-
-      def downcase(string)
-        string.downcase
-      end
-    else
-      # Ruby 2.3 and older require extra Gems
-      begin
-        require 'unicode_utils'
-        def upcase(string)
-          UnicodeUtils.upcase(string)
-        end
-
-        def downcase(string)
-          UnicodeUtils.downcase(string)
-        end
-      rescue LoadError
-        begin
-          require 'unicode'
-          def upcase(string)
-            Unicode.upcase(string)
-          end
+    def upcase(string)
+      string.upcase
+    end
 
-          def downcase(string)
-            Unicode.downcase(string)
-          end
-        rescue LoadError
-          warn "CiteProc requires the `unicode_utils` or `unicode` Gem on Ruby 2.3"
-        end
-      end
+    def downcase(string)
+      string.downcase
     end
   end
 end

data/lib/citeproc/date.rb

@@ -7,8 +7,8 @@ module CiteProc
   #
   # {Date Dates} can be constructed from a wide range of input values,
   # including Ruby date objects, integers, date ranges, ISO 8601 and
-  # CiteProc JSON strings or hashes, and - provided you have the respective
-  # gems installed - EDTF strings all strings supported by Chronic.
+  # CiteProc JSON strings or hashes, and - provided you have the EDTF gem
+  # installed - EDTF strings.
   #
   # @example Initialization
   #   CiteProc::Date.new
@@ -17,9 +17,6 @@ module CiteProc
   #   CiteProc::Date.today
   #   #-> #<CiteProc::Date "[2012, 6, 10]">
   #
-  #   CiteProc::Date.new('Yesterday')
-  #   #-> #<CiteProc::Date "[[2012, 6, 9]]">
-  #
   #   CiteProc::Date.new(1966)
   #   #-> #<CiteProc::Date "[1966]">
   #
@@ -129,6 +126,18 @@ module CiteProc
         !bc? && year < 1000
       end
 
+      # Seasons may be encoded as months 21 to 24 (Spring to Winter).
+      # @return [Integer, nil] the season (1 to 4) or nil if the
+      #   month does not encode a season
+      def season
+        month - 20 if month && month.between?(21, 24)
+      end
+
+      # @return [Boolean] whether or not the month encodes a season
+      def season?
+        !season.nil?
+      end
+
       # Formats the date parts according to the passed-in format string.
       # @param format [String] a format string
       # @return [String,nil] the formatted date string; nil if the date
@@ -148,8 +157,10 @@ module CiteProc
       # @return [Fixnum,nil] the result of the comparison (-1, 0, 1 or nil)
       def <=>(other)
         case
+        when other.is_a?(DateParts) && season? && other.season?
+          [year, season] <=> [other.year, other.season]
         when other.is_a?(DateParts)
-          to_citeproc <=> other.to_citeproc
+          comparable <=> other.comparable
         when other.respond_to?(:to_date)
           to_date <=> other.to_date
         else
@@ -192,6 +203,14 @@ module CiteProc
       def inspect
         "#<DateParts #{to_s}>"
       end
+
+      protected
+
+      # Seasons are compared like dates without month.
+      # @return [Array<Fixnum>] the date parts used for comparison
+      def comparable
+        season? ? to_citeproc.take(1) : to_citeproc
+      end
     end
 
     #
@@ -210,13 +229,11 @@ module CiteProc
     # List of date parsers (must respond to #parse)
     @parsers = []
 
-    [%w{ edtf EDTF }, %w{ chronic Chronic }].each do |date_parser, module_id|
-      begin
-        require date_parser
-        @parsers << ::Object.const_get(module_id)
-      rescue LoadError
-        # warn "failed to load `#{date_parser}' gem"
-      end
+    begin
+      require 'edtf'
+      @parsers << ::EDTF
+    rescue LoadError
+      # warn "failed to load `edtf' gem"
     end
 
     @parsers << ::Date
@@ -229,9 +246,8 @@ module CiteProc
       # A list of available date parsers. Each parser must respond to a
       # #parse method that converts a date string into a Ruby date object.
       # By default, the list will include Ruby's date parser from the
-      # standard library, as well as the parsers of the Chronic and EDTF
-      # gems if they are available; to install the latter on your system
-      # make sure to `gem install chronic edtf`.
+      # standard library, as well as the parser of the EDTF gem if it is
+      # available; to install it on your system run `gem install edtf`.
       #
       # @return [Array] the available date parsers
       attr_reader :parsers
@@ -276,12 +292,44 @@ module CiteProc
     end
 
 
-    # Make Date behave like a regular Ruby Date
-    def_delegators :to_ruby, *::Date.instance_methods(false).reject { |m|
-      m.to_s =~ /^[\W_]|[!=_]$|^(to_s|inspect|dup|clone|change)$|^(marshal|season|year|month|day|certain|uncertain)/
-    }
+    def_delegators :to_ruby, :strftime
+
+    attr_predicates :circa, :literal, :'date-parts'
+
+    # @return [Boolean] whether or not the date has a season field
+    def has_season?
+      attribute?(:season)
+    end
+
+    def season=(season)
+      write_attribute :season, season
+    end
+
+    # Season names recognized in the season field
+    SEASONS = {
+      'spring' => 1, 'summer' => 2, 'autumn' => 3, 'fall' => 3, 'winter' => 4
+    }.freeze
+
+    # A season takes the place of the month. If the (start) date has a
+    # month, the season is encoded by the month (21 to 24); otherwise
+    # the season field is used. Season numbers (1 to 4) and names in
+    # the season field are converted to integers.
+    #
+    # @return [Integer, String, nil] the season (1 to 4), the season
+    #   field as a string if it is not a season number or name, or nil
+    def season
+      return parts[0].season if month
 
-    attr_predicates :circa, :season, :literal, :'date-parts'
+      value = read_attribute(:season) or return
+      name = value.to_s.strip.downcase
+
+      SEASONS[name] || (name.match?(/\A[1-4]\z/) ? name.to_i : value.to_s)
+    end
+
+    # @return [Boolean] whether or not the date has a season (see #season)
+    def season?
+      !season.nil?
+    end
 
     def initialize(value = {})
       super
@@ -321,11 +369,15 @@ module CiteProc
       when value.is_a?(Hash)
         attributes = value.symbolize_keys
 
-        if attributes.has_key?(:raw)
-          @value = Date.parse(attributes.delete(:raw)).value
+        if attributes.has_key?(:raw) && Array(attributes[:'date-parts']).empty?
+          raw = attributes.delete(:raw)
+          attributes.delete(:'date-parts')
+          date = Date.parse(raw)
+
+          @value = date.nil? ? { :literal => raw } : date.value
           @value.merge!(attributes)
         else
-          @value = attributes.deep_copy
+          @value = attributes.except(:raw).deep_copy
         end
         convert_parts!
 
@@ -397,34 +449,16 @@ module CiteProc
       d
     end
 
-    # @return [::Date,nil] the date (start date if this instance is a range); or nil
-    def start_date
-      d = parts[0] and d.to_date
-    end
-
-    def start_date=(date)
-      parts[0] = DateParts.new(date.strftime('%Y-%m-%d').split(/-/))
-    end
-
-    def end_date=(date)
-      parts[1] = DateParts.new(date.nil? ? 0 : date.strftime('%Y-%m-%d').split(/-/))
-    end
-
-    # @return [Date,Range] the date as a Ruby date object or as a Range if
-    #   this instance is closed range
+    # @return [::Date, Range, nil] the date as a Ruby date object or as
+    #   a Range if this instance is closed range
     def to_ruby
       if closed_range?
-        start_date..end_date
+        parts[0].to_date..parts[1].to_date
       else
-        start_date
+        d = parts[0] and d.to_date
       end
     end
 
-    # @return [::Date,nil] the range's end date; or nil
-    def end_date
-      d = parts[1] and d.to_date
-    end
-
     # @return [Boolean] whether or not the date-parts contain an end date
     def has_end_date?
       parts[1] && !parts[1].empty?
@@ -506,7 +540,7 @@ module CiteProc
       case
       when literal?
         literal
-      when season?
+      when has_season?
         season
       else
         parts.map(&:to_citeproc).inspect
@@ -516,8 +550,14 @@ module CiteProc
     def <=>(other)
       case other
       when CiteProc::Date
-        return nil if season? || other.season?
-        parts <=> other.parts
+        result = parts <=> other.parts
+
+        # Seasons are ordered among themselves only
+        if result == 0 && season? && other.season?
+          result = season.to_i <=> other.season.to_i
+        end
+
+        result
       when ::Date
         parts <=> [other]
       else