csl 2.2.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d0cf629adc60121035ae2b8b86b8042a2a3da87b264402fa93fdc7da093f709
-  data.tar.gz: 6d2c61c0e05a1214fcc8653142fcac1a45d63f357f24a434e453d7932caad645
+  metadata.gz: c70f967fbf46ada97d0c2b3164d3fc1b843d24d6125f1c6364d2d7f408c5fa7e
+  data.tar.gz: 59d241370ed43b45a191e938ebbe20b51ed74419a503feb0c71e37d2770facd3
 SHA512:
-  metadata.gz: 5fe9697ec7d2c7308397fe192e912542d255c4317a310f83c51a066463a2f4a3c80a346edf528ead70ae3c95487a40870bfedb7f6d6db23cc1e38d37a022b73a
-  data.tar.gz: 959edc27ca855e1083d4b2e2e23bde12607334d3d38647e0185753c584c10abbcecf48735f9f95e8e8b85db13acad20c405a3419c008f22d100291730ee75e42
+  metadata.gz: ee00896662db7e3f7ccdc6644f208428a392ad2a66ae09ad93bb37ac4a6366915d9f4cea1cb274526466e8a0441f6c40afdfcbf953735e2d6a744587f41f6777
+  data.tar.gz: 2807a5c96c581af1a9314d75b5b24b09e461c6fbf956b475d9bde1f8c1f7a6bc420095a9af6380ee7879129b80f6dc0ce1505dcd555dafdff7355b89e09979cc

data/README.md

@@ -1,48 +1,56 @@
 CSL-Ruby
 ========
 CSL-Ruby provides a Ruby parser and a comprehensive API for the
-[Citation Style Language](http://citationstyles.org) (CSL), an XML-based
-format to describe the formatting of citations, notes and bibliographies.
+[Citation Style Language](https://citationstyles.org) (CSL),
+an XML-based format to describe the formatting
+of citations, notes and bibliographies.
 
 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`.
+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'`.
 
 Usage
 -----
-CSL-Ruby is broadly aimed at two very different usage scenarios: on the one
-hand, you can use the parser to load existing styles and locales and
-manipulate, query or otherwise work with them using a dedicated API: that is
-to say, you do not have to resort to XML-related methods of access, but can
-make use of a large set of library methods which are specific to CSL. This
-is useful, primarily, for citation processors like
-[CiteProc-Ruby](https://github.com/inukshuk/citeproc).
-
-On the other hand, CSL-Ruby makes it easy to create new styles and locales
-using Ruby; this is useful, for example, if you need to change or adapt
-styles on-the-fly or for writing an interactive style editor.
-
-To get you started, here are a few usage examples; for the full set of
-available features, please consult the
-[API documentation](http://rubydoc.info/gems/csl/).
+CSL-Ruby is broadly aimed at two very different usage scenarios:
+on the one hand,
+you can use the parser to load existing styles and locales
+and manipulate, query or otherwise work with them using a dedicated API:
+that is to say,
+you do not have to resort to XML-related methods of access,
+but can make use of a large set of library methods which are specific to CSL.
+This is useful, primarily, for citation processors like
+[CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby).
+
+On the other hand,
+CSL-Ruby makes it easy to create new styles and locales using Ruby;
+this is useful, for example,
+if you need to change or adapt styles on-the-fly
+or for writing an interactive style editor.
+
+To get you started, here are a few usage examples;
+for the full set of available features, please consult the
+[API documentation](https://rubydoc.info/gems/csl/).
 
     require 'csl'
 
     # Load a style from the Zotero style repository
-    jps = CSL::Style.load 'http://zotero.org/styles/american-journal-of-political-science'
+    jps = CSL::Style.load 'https://www.zotero.org/styles/american-journal-of-political-science'
 
     # Query style information
     jps.title #-> "American Journal of Political Science"
@@ -53,7 +61,7 @@ available features, please consult the
     jps.valid? #-> true
 
     # Load another style
-    amc = CSL::Style.load 'http://zotero.org/styles/applied-mathematics-and-computation'
+    amc = CSL::Style.load 'https://www.zotero.org/styles/applied-mathematics-and-computation'
 
     amc.independent? #-> false
 
@@ -68,9 +76,9 @@ available features, please consult the
     # Load a locally installed style
     apa = CSL::Style.load :apa
 
-    # Fetch the a macro
-    authors = apa.macros['authors'].children[0]
-    #-> #<CSL::Style::Names variable="author" children=[2]>
+    # Fetch the first child of a macro
+    authors = apa.macros['author-bib'].children[0]
+    #-> #<CSL::Style::Group delimiter=" " children=[2]>
 
     # Load a locally installed locale
     fr = CSL::Locale.load :fr
@@ -82,7 +90,7 @@ available features, please consult the
 
     # Ordinalize a number
     fr.ordinalize 42 #=> "42ᵉ"
-    fr.ordinalize 3, form: 'long' => "troisième"
+    fr.ordinalize 3, form: 'long' #=> "troisième"
 
     # Create a new style
     style = CSL::Style.new
@@ -101,11 +109,12 @@ available features, please consult the
 
 Dependencies
 ------------
-CSL-Ruby was written with portability in mind. For performance reasons it
-will use [Nokogiri ](http://nokogiri.org) for XML parsing and validation
-if available; however, CSL-Ruby will fallback to REXML from the Ruby standard
-library. In order to use Nokogiri, simply `gem install nokogiri` or add it
-to your Gemfile.
+CSL-Ruby was written with portability in mind.
+For performance reasons it will use [Nokogiri](https://nokogiri.org)
+for XML parsing and validation if available;
+however, CSL-Ruby will fallback to REXML from the Ruby standard library.
+In order to use Nokogiri,
+simply `gem install nokogiri` or add it to your Gemfile.
 
 Development
 -----------
@@ -114,28 +123,33 @@ You can check out a copy of the latest code using Git:
 
     $ git clone https://github.com/inukshuk/csl-ruby.git
 
-To get started, install the development dependencies and run all tests:
+To get started,
+install the development dependencies and run all tests:
 
     $ cd csl-ruby
     $ bundle install
     $ rake
 
-If you've found a bug or have a question, please open an issue on the
+If you've found a bug or have a question,
+please open an issue on the
 [issue tracker](https://github.com/inukshuk/csl-ruby/issues).
-Or, for extra credit, clone the CSL-Ruby repository, write a failing
-example, fix the bug and submit a pull request.
+Or, for extra credit, clone the CSL-Ruby repository,
+write a failing example, fix the bug and submit a pull request.
 
 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/csl/compatibility.rb

@@ -10,12 +10,8 @@ module CSL
 end
 
 class Module
-  if RUBY_VERSION < '1.9'
-    alias const? const_defined?
-  else
-    def const?(name)
-      const_defined?(name, false)
-    end
+  def const?(name)
+    const_defined?(name, false)
   end
 end
 
@@ -26,30 +22,11 @@ end unless Struct.instance_methods.include?(:__class__)
 module CSL
   module_function
 
-  if RUBY_VERSION < '1.9'
-
-    XML_ENTITY_SUBSTITUTION = Hash[*%w{
-     & &amp; < &lt; > &gt; ' &apos; " &quot;
-    }].freeze
-
-    def encode_xml_text(string)
-      string.gsub(/[&<>]/) { |match|
-        XML_ENTITY_SUBSTITUTION[match]
-      }
-    end
-
-    def encode_xml_attr(string)
-      string.gsub(/[&<>'"]/) { |match|
-        XML_ENTITY_SUBSTITUTION[match]
-      }.inspect
-    end
-  else
-    def encode_xml_text(string)
-      string.encode(string.encoding, :xml => :text)
-    end
+  def encode_xml_text(string)
+    string.encode(string.encoding, :xml => :text)
+  end
 
-    def encode_xml_attr(string)
-      string.encode(string.encoding, :xml => :attr)
-    end
+  def encode_xml_attr(string)
+    string.encode(string.encoding, :xml => :attr)
   end
 end

data/lib/csl/info.rb

@@ -85,18 +85,6 @@ module CSL
       end
     end
 
-    # Ruby 1.8 still has Object#id methods so the attr_children generator
-    # may not have created those; since #id is deprecated in 1.8.7 we're
-    # forcing the override anyway. Live dangerously!
-    remove_method :id
-
-    # @return [Id] the id text node
-    def id
-      children[:id]
-    end
-
-    alias id= set_child_id
-
     def self_link!
       return unless has_id?
       self.self_link = id

data/lib/csl/loader.rb

@@ -9,6 +9,12 @@ module CSL
   #   Base classes are exepcted to define a #parse method.
   module Loader
 
+    class << self
+      attr_accessor :allow_remote
+    end
+
+    @allow_remote = true
+
     attr_accessor :root, :prefix, :extension
 
     # @example
@@ -82,8 +88,11 @@ module CSL
           location = input
         end
 
-        Kernel.open(location, 'r:UTF-8') do |io|
-          io.read
+        if location =~ /\A\w+:\/\//
+          raise 'loading from URLs is disabled' unless Loader.allow_remote
+          URI.open(location, 'r:UTF-8') { |io| io.read }
+        else
+          File.open(location, 'r:UTF-8') { |io| io.read }
         end
       end
     rescue => e

data/lib/csl/locale/term.rb

@@ -80,10 +80,11 @@ module CSL
         return unless has_ordinals?
 
         options = Term.specialize(options)
+        form, options = options[:form], options.except(:form)
         number = number.to_i.abs
 
         # try to match long-ordinals first
-        if options.delete(:form).to_s =~ /^long/i
+        if form.to_s =~ /^long/i
           ordinal = lookup_long_ordinal_for number, options
           return ordinal unless ordinal.nil?
         end
@@ -94,9 +95,9 @@ module CSL
         ordinal = send algorithm, number, options
         return ordinal unless ordinal.nil?
 
-        # fallback to non-gendered version
-        if options.delete(:'gender-form')
-          ordinal = send algorithm, number, options
+        # fallback to neuter
+        if options.key?(:'gender-form')
+          ordinal = send algorithm, number, options.merge(:'gender-form' => nil)
         end
 
         ordinal

data/lib/csl/locale.rb

@@ -15,7 +15,7 @@ module CSL
     @extension = '.xml'.freeze
     @prefix = 'locales-'.freeze
 
-    @tag_pattern = /^[a-z]{2,3}(-[a-z]{4})?(-[a-z]{2})?|-[a-z]{2}$/i
+    @tag_pattern = /\A(?:[a-z]{2,3}(-[a-z]{4})?(-[a-z]{2})?|-[a-z]{2})\z/i
 
     # Default languages/regions.
     # Auto-detection is based on these lists.
@@ -40,10 +40,27 @@ module CSL
       attr_accessor :default
       attr_reader :languages, :regions, :scripts
 
+      # Loads the locale. For IETF tags without a locale file, falls
+      # back to the language's primary dialect and to the default locale.
       def load(input = nil)
         input ||= Locale.default
-        input = normalize input if input.to_s =~ @tag_pattern
-        super(input)
+
+        # Drop extensions and private-use subtags (e.g. "-x-...")
+        tag = input.to_s.sub(/-[a-z0-9]-.*\z/i, '')
+        return super(input) unless tag =~ @tag_pattern
+
+        tag = normalize(tag)
+        candidates = [tag, normalize(tag.split('-')[0]), Locale.default].uniq
+
+        error = nil
+
+        candidates.each do |candidate|
+          return super(candidate).tap { |locale| locale.requested = tag }
+        rescue ParseError => e
+          error ||= e
+        end
+
+        raise error
       end
 
       # Normalizes an IETF tag; adds default language, region, script.
@@ -102,6 +119,10 @@ module CSL
 
     attr_accessor :region, :script
 
+    # @return [String, nil] the IETF tag the locale was loaded for;
+    #   this differs from the locale's own tag if the locale is a fallback
+    attr_accessor :requested
+
     alias_child :metadata, :info
     alias_child :dates, :date
     alias_child :options, :style_options
@@ -154,6 +175,7 @@ module CSL
     def initialize_copy(other)
       @parent, @ancestors, @descendants, @siblings, @root, @depth = nil
       initialize(other.attributes.to_hash.merge(:lang => other.to_s))
+      @requested = other.requested
     end
 
     def added_to(node)
@@ -249,8 +271,9 @@ module CSL
     #   de.ordinalize(13)
     #   #-> "13."
     #
-    #   de.ordinalize(3, :form => :long, :gender => :feminine)
-    #   #-> "dritte"
+    #   fr = Locale.load('fr')
+    #   fr.ordinalize(1, :'gender-form' => 'feminine')
+    #   #-> "1ʳᵉ"
     #
     # @note
     #   For CSL 1.0 (and older) locales that do not define an "ordinal-00"
@@ -262,8 +285,9 @@ module CSL
     # @param options [Hash] formatting options
     #
     # @option options [:short,:long] :form (:short) which ordinals form to use
-    # @option options [:feminine,:masculine,:neutral] :gender (:neutral)
-    #   which ordinals gender-form to use
+    # @option options ['feminine','masculine',nil] :'gender-form' (nil)
+    #   which ordinals gender-form to use; falls back to the neuter
+    #   ordinals (without gender-form)
     #
     # @raise [ArgumentError] if number cannot be converted to an integer
     #
@@ -283,8 +307,7 @@ module CSL
 
     # @return [Boolean] true when the option limit-day-ordinals-to-day-1 is true
     def limit_day_ordinals?
-      return false unless has_options? && options.attribute?(:'limit-day-ordinals-to-day-1')
-      !!(options[:'limit-day-ordinals-to-day-1'].to_s =~ /^true$/i)
+      has_options? && options.boolean_attribute(:'limit-day-ordinals-to-day-1')
     end
 
     def limit_day_ordinals!
@@ -297,8 +320,7 @@ module CSL
 
     # @return [Boolean] true when the option punctuation-in-quote is true
     def punctuation_in_quote?
-      return false unless has_options? && options.attribute?(:'punctuation-in-quote')
-      !!(options[:'punctuation-in-quote'].to_s =~ /^true$/i)
+      has_options? && options.boolean_attribute(:'punctuation-in-quote')
     end
     alias punctuation_in_quotes? punctuation_in_quote?
 
@@ -382,13 +404,13 @@ module CSL
 
     # @returns [Boolean] whether or not the Locale is the default locale
     def default?
-      to_s == Locale.default
+      default_tag?(language, script, region)
     end
 
     # @return [Boolean] whehter or not the Locale's region is the default
     #   region for its language
     def default_region?
-      region && region == Locale.regions[language]
+      default_region_for?(language, region)
     end
 
     # @return [Boolean] whether or not the Locale's language is the default
@@ -397,11 +419,25 @@ module CSL
       language && language == Locale.languages[region]
     end
 
+    # Whether or not the passed-in locale (e.g., an in-style locale)
+    # matches this locale. This is the case for universal locales and
+    # for locales of the language this locale was requested for.
     def like?(other)
       return false unless other.is_a? Locale
       return true  if other.universal?
 
-      language == other.language
+      requested_language == other.language
+    end
+
+    # @return [Symbol, nil] the language this locale was requested for
+    def requested_language
+      requested.nil? ? language : requested.split('-')[0].to_sym
+    end
+
+    # @return [Boolean] whether or not the locale was loaded as a
+    #   fallback for a different locale
+    def fallback?
+      !requested.nil? && requested != to_s
     end
 
     def universal?
@@ -444,44 +480,76 @@ module CSL
     # de-DE will come before de-AT even though the alphabetical order
     # would be different).
     #
+    # Fallback locales are compared as the locale they were requested
+    # for (see #requested); locale data (terms, dates, and options) is
+    # not compared.
+    #
     # @param other [Locale] the locale used for comparison
     # @return [1,0,-1,nil] the result of the comparison
     def <=>(other)
+      return nil unless other.is_a?(Locale)
+      compare(identity, other.identity)
+    end
+
+    # @return [String] the Locale's IETF tag
+    def to_s
+      [language, script, region].compact.join('-')
+    end
+
+    # @return [String] a string representation of the Locale
+    def inspect
+      "#<#{self.class.name} #{to_s}>"
+    end
+
+    protected
+
+    # @return [Array<Symbol, nil>] language, script, and region of the
+    #   locale or, for fallback locales, of the requested tag
+    def identity
+      return [language, script, region] unless fallback?
+
+      language, *rs = requested.split('-').map(&:to_sym)
+      region, script = rs.reverse
+
+      [language, script, region]
+    end
+
+    private
+
+    # Compares two locale identities (see #identity).
+    def compare(a, b)
+      language, script, region = a
+      other_language, other_script, other_region = b
+
       case
-      when !other.is_a?(Locale)
-        nil
-      when [language, region] == [other.language, other.region]
-        script <=> other.script
-      when default?
+      when [language, region] == [other_language, other_region]
+        script <=> other_script
+      when default_tag?(*a)
         -1
-      when other.default?
+      when default_tag?(*b)
         1
-      when language == other.language
+      when language == other_language
         case
-        when default_region?
+        when default_region_for?(language, region)
           -1
-        when other.default_region?
+        when default_region_for?(other_language, other_region)
           1
         else
-          region.to_s <=> other.region.to_s
+          region.to_s <=> other_region.to_s
         end
       else
-        language.to_s <=> other.language.to_s
+        language.to_s <=> other_language.to_s
       end
     end
 
-    # @return [String] the Locale's IETF tag
-    def to_s
-      [language, script, region].compact.join('-')
+    def default_tag?(language, script, region)
+      [language, script, region].compact.join('-') == Locale.default
     end
 
-    # @return [String] a string representation of the Locale
-    def inspect
-      "#<#{self.class.name} #{to_s}>"
+    def default_region_for?(language, region)
+      region && region == Locale.regions[language]
     end
 
-    private
-
     alias original_locale_attribute_assignments attribute_assignments
 
     def attribute_assignments
@@ -493,7 +561,7 @@ module CSL
     end
 
     def preamble
-      Schema.preamble.dup
+      Schema.preamble
     end
 
     # @param other [Locale] an other locale whose options should be merged
@@ -532,6 +600,9 @@ module CSL
     def merge_terms(other)
       return self unless other.has_terms?
 
+      # Ordinals are replaced as a set
+      terms.drop_ordinals if has_terms? && other.terms.has_ordinals?
+
       other.each_term do |term|
         store term.deep_copy
       end

data/lib/csl/node.rb

@@ -131,8 +131,7 @@ module CSL
       def attr_struct(*attributes)
         const_set(:Attributes, Struct.new(*attributes) {
 
-          # 1.8 Compatibility
-          @keys = attributes.map(&:to_sym).freeze
+          @keys = members.freeze
 
           class << self
             attr_reader :keys
@@ -169,13 +168,10 @@ module CSL
           end
 
           def fetch(key, default = nil)
-            value = keys.include?(key.to_sym) && send(:'[]', key)
+            value = send(:'[]', key) if keys.include?(key.to_sym)
+            return value unless value.nil?
 
-            if block_given?
-              value || yield(key)
-            else
-              value || default
-            end
+            block_given? ? yield(key) : default
           end
 
           # Merges the current with the passed-in attributes.
@@ -308,6 +304,17 @@ module CSL
       attributes.fetch(name, false)
     end
 
+    # @param name [Symbol] the name of an xsd:boolean attribute
+    # @param default [Boolean] the value if the attribute is not set
+    # @return [Boolean] the value of the boolean attribute
+    def boolean_attribute(name, default = false)
+      case attributes.fetch(name, nil).to_s
+      when 'true', '1' then true
+      when 'false', '0' then false
+      else default
+      end
+    end
+
     # @param [[String]] names list of attribute names
     # @return [Boolean] true if the node contains attributes for all
     #   passed-in names; false otherwise.
@@ -467,11 +474,11 @@ module CSL
     end
 
     def strip_periods?
-      attribute?(:'strip-periods') && !!(attributes[:'strip-periods'].to_s =~ /^true$/i)
+      boolean_attribute(:'strip-periods')
     end
 
     def quotes?
-      attribute?(:'quotes') && !!(attributes[:'quotes'].to_s =~ /^true$/i)
+      boolean_attribute(:quotes)
     end
 
 
@@ -574,17 +581,6 @@ module CSL
       CSL.encode_xml_text 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.respond_to?(:each_pair)

data/lib/csl/parser.rb

@@ -12,8 +12,7 @@ module CSL
       :nokogiri => lambda { |source|
         Nokogiri::XML::Document.parse(source, nil, nil,
           Nokogiri::XML::ParseOptions::DEFAULT_XML |
-          Nokogiri::XML::ParseOptions::NOBLANKS |
-          Nokogiri::XML::ParseOptions::NOENT)
+          Nokogiri::XML::ParseOptions::NOBLANKS)
       },
       :default  => lambda { |source|
         REXML::Document.new(source, :compress_whitespace => :all, :ignore_whitespace_nodes => :all)

data/lib/csl/pretty_printer.rb

@@ -10,7 +10,7 @@ module CSL
     end
 
     def pretty_print
-      preamble << tags.map { |t| pp t }.join("\n")
+      "#{preamble}#{tags.map { |t| pp t }.join("\n")}"
     end
 
     private

data/lib/csl/style/label.rb

@@ -16,7 +16,7 @@ module CSL
 
       has_no_children
 
-      @variables = [:locator, :page].concat(Schema.variables[:number]).freeze
+      @variables = ([:locator, :page] | Schema.variables[:number]).freeze
 
       @terms = Hash.new { |h,k| h[k] = k }