citeproc-ruby 2.1.8 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 310c28ad4f8db98a36c203d79fc7b8e5aa51367371f81daf6d4d6b03dc97888c
-  data.tar.gz: f2b7597549a33ca318635d0b54d1ff49179938e50f2b7f25c3cf596221519d05
+  metadata.gz: 711627337c8ad301400254ed5e9143c43ac710f4aeeed58e2497384d067e7d88
+  data.tar.gz: b50e0a76599302904b67922a7799d1e88bc57e57994936a50753c45a54d74aab
 SHA512:
-  metadata.gz: 6151f0f5f16d34b77c07627116baca5294ef8090a69051e0f353f521d63ad6a41cbf805e8bbc7679bfc8cec67f0fdb566b166fbab1c41adb472a6e3ccf53e45e
-  data.tar.gz: cc1e8d512be419a3e1ee6d46b7d3a5a79c9adb4b9a74796557abef3f93ea7d5221382565fdfcb1a54aaae4ae7bc4038cdc3a58c4169317d00ab81bcb701248c5
+  metadata.gz: 2922fa4307ebe6a89970118a55be01322ee21fd47f7512f7b34656842c61e3ec409180bc25ae2555a48faf8c63a6d2e87aff1148085af52f011d1ce9ca2b723d
+  data.tar.gz: ff9ceb486663023a3c4fbe2d01eacb17208cb26743ba60aecf1fc707423d0c8a0a5a39e9e3f48e2e2f2fe5b4b21a759b81556ae6d0d4834b8ac3d4e574798bb4

data/README.md

@@ -1,9 +1,10 @@
 CiteProc-Ruby
 =============
-CiteProc-Ruby is a [Citation Style Language](http://citationstyles.org/) (CSL)
-1.0.2 cite processor written in pure Ruby. This Ruby gem contains the
-processor's rendering engine only; for more documentation on the whole
-cite processor, please refer to the documentation of the
+CiteProc-Ruby is a [Citation Style Language](https://citationstyles.org/) (CSL)
+1.0.2 cite processor written in pure Ruby.
+This Ruby gem contains the processor's rendering engine only;
+for more documentation on the whole cite processor,
+please refer to the documentation of the
 [citeproc](https://rubygems.org/gems/citeproc) gem instead.
 
 Quickstart
@@ -13,64 +14,65 @@ 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!
 
 ```ruby
 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)
 
 # Pass an array if you want to render multiple citations:
@@ -80,44 +82,40 @@ cp.render :citation, [{ id: 'knuth' }, { id: 'perez' }]
 
 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'`.
 
 Development
 -----------
@@ -131,24 +129,28 @@ To get started, install the development dependencies and run all tests:
 
     $ cd citeproc-ruby
     $ bundle install
-    $ rake
+    $ bundle exec 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/citeproc-ruby/issues).
-Or, for extra credit, clone the CiteProc-Ruby repository, write a failing
-example, fix the bug and submit a pull request.
+Or, for extra credit, clone the CiteProc-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-2024 Sylvester Keil. All rights reserved.
+Copyright 2009-2026 Sylvester Keil.
+All rights reserved.
 
 Copyright 2012 President and Fellows of Harvard College.
 

data/lib/citeproc/ruby/engine.rb

@@ -13,7 +13,7 @@ module CiteProc
       attr_reader :renderer, :style
 
       def_delegators :renderer,
-        :format, :format=, :locale, :locale=
+        :format, :format=, :locale, :locale=, :clear_cache!
 
       def initialize(*arguments)
         super(*arguments)
@@ -22,8 +22,10 @@ module CiteProc
         update! unless processor.nil?
       end
 
+      # @param new_style [CSL::Style, String] a style or a style name, path,
+      #   or URL; styles are used as is and never changed by the engine
       def style=(new_style)
-        @style = CSL::Style.load new_style
+        @style = new_style.is_a?(CSL::Style) ? new_style : CSL::Style.load(new_style)
       end
 
       def process(data)
@@ -35,6 +37,7 @@ module CiteProc
         # populate item data
         data.each do |item|
           item.data = processor[item.id].dup
+          item.parse_locator!(renderer.locator_abbreviations)
         end
 
         # TODO implement sort in citation data
@@ -100,6 +103,7 @@ module CiteProc
 
           data.each do |item|
             item.data = processor[item.id].dup
+            item.parse_locator!(renderer.locator_abbreviations)
           end
 
           renderer.render_citation data, node
@@ -109,23 +113,15 @@ module CiteProc
         end
       end
 
-
+      # Applies the processor's format, locale, and style options.
+      #
+      # @return [self]
       def update!
+        renderer.clear_cache!
         renderer.format = processor.options[:format]
         renderer.locale = processor.options[:locale]
 
-        if processor.options[:style].is_a? CSL::Style
-          @style = processor.options[:style]
-        else
-          @style = CSL::Style.load processor.options[:style]
-        end
-
-        # Preliminary locale override implementation!
-        # Does not yet reverse merge default region and default locale.
-        @style.locales.sort.reverse.each do |locale|
-          renderer.locale.merge! locale if renderer.locale.like?(locale)
-        end
-
+        self.style = processor.options[:style]
         self
       end
 

data/lib/citeproc/ruby/format.rb

@@ -7,7 +7,7 @@ module CiteProc
 
       @available = []
 
-      @squeezable = /^[\s\.,:;!?\)\(\[\]]+$/
+      @squeezable = /^[\s\.,:;!?]+$/
 
       @stopwords = {
         :en => %w(a about above across afore after against along alongside amid amidst among amongst
@@ -16,7 +16,7 @@ module CiteProc
           forenenst from given in inside into lest like modulo near next nor notwithstanding of off
           on onto or out over per plus pro qua sans since so than the through thru throughout thruout
           till to toward towards under underneath until unto up upon versus vs v via vis-à-vis with
-          within without)
+          within without yet de von van)
       }
 
       class << self
@@ -140,14 +140,16 @@ module CiteProc
         bibliography
       end
 
-      def apply(input, node, locale = nil)
+      # @param language [String] the language of the item being formatted
+      def apply(input, node, locale = nil, language = nil)
         return '' if input.nil?
         return input if input.empty? || node.nil?
 
         return ArgumentError unless node.respond_to?(:formatting_options)
 
 
-        @input, @output, @node, @locale = input, input.dup, node, locale
+        @input, @output, @node, @locale, @language =
+          input, input.dup, node, locale, language
 
         setup!
 
@@ -208,10 +210,10 @@ module CiteProc
       def apply_text_case
         case options[:'text-case']
         when 'lowercase'
-          output.replace CiteProc.downcase output
+          output.replace turkic? ? output.downcase(:turkic) : CiteProc.downcase(output)
 
         when 'uppercase'
-          output.replace CiteProc.upcase output
+          output.replace turkic? ? output.upcase(:turkic) : CiteProc.upcase(output)
 
         when 'capitalize-first'
           output.sub!(/^([^\p{Alnum}]*)(\p{Ll})/) { "#{$1}#{CiteProc.upcase($2)}" }
@@ -224,25 +226,34 @@ module CiteProc
           output.gsub!(/\b(\p{Lu})(\p{Lu}+)\b/) { "#{$1}#{CiteProc.downcase($2)}" }
 
         when 'title'
-          return if locale && locale.language != :en
+          return unless english?
 
           # TODO add support for stop words consisting of multiple words
           #output.gsub!(/\b(\p{Lu})(\p{Lu}+)\b/) { "#{$1}#{CiteProc.downcase($2)}" }
 
           # TODO exceptions: word followed by colon
           first = true
-          output.gsub!(/\b(\p{L})([\p{L}\.]+)\b/) do |word|
+          output.gsub!(/(?<!['’])\b(\p{L})([\p{L}\.]+)\b/) do |word|
             first_letter = $1
             rest_of_word = $2
+            before, after = Regexp.last_match.pre_match, Regexp.last_match.post_match
             result = word
 
-            if first_letter.match(/^\p{Ll}/) && (!Format.stopword?(word) || first)
+            # Stop words are capitalized at the start of hyphenated words
+            capitalize = first || !Format.stopword?(word) ||
+              after.start_with?('-') && !before.end_with?('-')
+
+            # Words in mixed case like "iPad" are left as is
+            if first_letter.match(/^\p{Ll}/) && !rest_of_word.match?(/\p{Lu}/) && capitalize
               result = "#{CiteProc.upcase(first_letter)}#{rest_of_word}"
             end
             first = false
             result
           end
 
+          # Capitalize the first word after a colon
+          output.gsub!(/(:\s+)(\p{Ll})(?=\p{Ll}*\b)/) { "#{$1}#{CiteProc.upcase($2)}" }
+
           output.gsub!(/(\.|\b)(\p{Ll})([\p{L}\.]+)\b$/) do |word|
             word_boundary = $1
             first_letter = $2
@@ -257,6 +268,21 @@ module CiteProc
         end
       end
 
+      # Title case applies only to English items: items whose language
+      # is English or, if they have no language, when the locale is English.
+      def english?
+        if @language.nil? || @language.empty?
+          locale.nil? || locale.language == :en
+        else
+          @language.match?(/\Aen(-|\z)/i)
+        end
+      end
+
+      # @return [Boolean] whether the item's language uses Turkic case mappings
+      def turkic?
+        @language.to_s.match?(/\A(tr|az)(-|\z)/i)
+      end
+
       def punctuation_in_quotes?
         !locale.nil? && locale.punctuation_in_quotes?
       end

data/lib/citeproc/ruby/formats/default.rb

@@ -20,14 +20,15 @@ module CiteProc
       class Sort < Text
         #A special format to use when sorting which prevents formatting of extraneous things like quotes
 
-        def apply(input, node, locale = nil)
+        def apply(input, node, locale = nil, language = nil)
           return '' if input.nil?
           return input if input.empty? || node.nil?
 
           return ArgumentError unless node.respond_to?(:formatting_options)
 
 
-          @input, @output, @node, @locale = input, input.dup, node, locale
+          @input, @output, @node, @locale, @language =
+            input, input.dup, node, locale, language
 
           setup!
 

data/lib/citeproc/ruby/formats/html.rb

@@ -58,7 +58,7 @@ module CiteProc
           end
 
           if bibliography.hanging_indent?
-            hanging_indent = "#{config[:bib_hanging_indent]}#{bib_unit}"
+            hanging_indent = "#{config[:bib_hanging_indent]}#{unit}"
 
             container_options['style']['padding-left'] = hanging_indent
             entry_options['style']['text-indent'] = "-#{hanging_indent}"
@@ -118,6 +118,14 @@ module CiteProc
           )
         end
 
+        # The suffix of a layout goes into a trailing display block
+        def apply_suffix
+          close = closing_tag(config[:display])
+          return super unless node.is_a?(CSL::Style::Layout) && output.end_with?(close)
+
+          output.replace "#{squeeze_suffix(output.delete_suffix(close), suffix)}#{close}"
+        end
+
         def prefix
           CSL.encode_xml_text(options[:prefix])
         end
@@ -131,7 +139,7 @@ module CiteProc
         end
 
         def strip(string)
-          string.split(/((?:^<\p{Alpha}[^>]*>)|(?:<\/\p{Alpha}[^>]*>))$/, 2)
+          string.split(/((?:\A<\p{Alpha}[^>]*>)|(?:<\/\p{Alpha}[^>]*>))\z/, 2)
         end
 
         protected
@@ -162,7 +170,7 @@ module CiteProc
         private
 
         def content_tag(name, content, options = nil)
-          opening_tag(name, options) << content << closing_tag(name)
+          "#{opening_tag(name, options)}#{content}#{closing_tag(name)}"
         end
 
         def style_for(options)
@@ -177,7 +185,7 @@ module CiteProc
 
           return unless !options.empty?
 
-          ' ' << options.map { |k, v| [k, v.inspect].join('=') }.join(' ')
+          " #{options.map { |k, v| [k, v.inspect].join('=') }.join(' ')}"
         end
 
         def opening_tag(name, options = nil)
@@ -194,6 +202,9 @@ module CiteProc
       end
 
       class CiteProcJS < Html
+        # The superscript characters converted to sup tags by citeproc-js
+        SUPERSCRIPTS = /[ª²-³¹-ºʰ-ʸˀ-ˁˠ-ˤۥ-ۦᴬ-ᴮᴰ-ᴺᴼ-ᵍᵏ-ᵡ⁰-ⁱ⁴-ⁿ℠™㆒-㆟]/
+
         def initialize
           super(
             :bib_container => 'div',
@@ -222,6 +233,35 @@ module CiteProc
           bibliography.connector = indent ? "\n" : ''
           bibliography
         end
+
+        def apply_vertical_align
+          case options[:'vertical-align']
+          when 'sup', 'sub'
+            output.replace content_tag(options[:'vertical-align'], output)
+          else
+            super
+          end
+        end
+
+        protected
+
+        def finalize!
+          super
+
+          # Use typographic apostrophes
+          output.gsub!(/(?<=\p{L})'|'(?=\d)/, '’')
+
+          output.gsub!(SUPERSCRIPTS) do |char|
+            content_tag('sup', char.unicode_normalize(:nfkc))
+          end
+        end
+
+        private
+
+        def style_for(options)
+          return unless options && !options.empty?
+          options.map { |k, v| "#{k}:#{v};" }.join
+        end
       end
 
     end

data/lib/citeproc/ruby/formats/latex.rb

@@ -93,7 +93,7 @@ module CiteProc
         private
 
         def content_tag(name, content, options = nil)
-          opening_tag(name, options) << content << closing_tag(name)
+          "#{opening_tag(name, options)}#{content}#{closing_tag(name)}"
         end
 
         def style_for(options)
@@ -108,7 +108,7 @@ module CiteProc
 
           return unless !options.empty?
 
-          ' ' << options.map { |k, v| [k, v.inspect].join('=') }.join(' ')
+          " #{options.map { |k, v| [k, v.inspect].join('=') }.join(' ')}"
         end
 
         def opening_tag(name, options = nil)