asciidoctor-bibliography 0.2.1 → 0.3.0

data/lib/asciidoctor-bibliography/bibliographer.rb

@@ -24,19 +24,18 @@ module AsciidoctorBibliography
     end
 
     def sort
-      if options['order'] == 'alphabetical'
-        @occurring_keys = @occurring_keys.sort_by do |target|
-          first_author_family_name(target)
-        end
+      return unless options["order"] == "alphabetical"
+      @occurring_keys = @occurring_keys.sort_by do |target|
+        first_author_family_name(target)
       end
     end
 
     private
 
     def first_author_family_name(key)
-      authors = database.find { |h| h['id'] == key }['author']
-      return '' if authors.nil?
-      authors.map { |h| h['family'] }.compact.first # TODO: is the first also alphabetically the first?
+      authors = database.find_entry_by_id(key)["author"]
+      return "" if authors.nil?
+      authors.map { |h| h["family"] }.compact.first # TODO: is the first also alphabetically the first?
     end
   end
 end

data/lib/asciidoctor-bibliography/citation.rb

@@ -1,12 +1,13 @@
-require 'securerandom'
-require_relative 'formatters/csl'
-require_relative 'formatters/tex'
-require_relative 'citation_item'
+require "securerandom"
+require_relative "formatters/csl"
+require_relative "formatters/tex"
+require_relative "citation_item"
 
 module AsciidoctorBibliography
   class Citation
-    TEX_MACROS_NAMES = Formatters::TeX::MACROS.keys.map { |s| Regexp.escape s }.concat(['fullcite']).join('|')
-    REGEXP = /\\?(#{TEX_MACROS_NAMES}):(?:(\S*?)?\[(|.*?[^\\])\])(?:\+(\S*?)?\[(|.*?[^\\])\])*/
+    MACRO_NAME_REGEXP = Formatters::TeX::MACROS.keys.concat(%w[cite fullcite]).
+      map { |s| Regexp.escape s }.join("|").freeze
+    REGEXP = /\\?(#{MACRO_NAME_REGEXP}):(?:(\S*?)?\[(|.*?[^\\])\])(?:\+(\S*?)?\[(|.*?[^\\])\])*/
     REF_ATTRIBUTES = %i[chapter page section clause].freeze
 
     attr_reader :macro, :citation_items
@@ -25,70 +26,72 @@ module AsciidoctorBibliography
     end
 
     def render(bibliographer)
-      if macro == 'cite'
+      case macro
+      when "cite"
         render_citation_with_csl(bibliographer)
-      elsif macro == 'fullcite'
+      when "fullcite"
         render_fullcite_with_csl(bibliographer)
-      elsif Formatters::TeX::MACROS.keys.include? macro
-        formatter = Formatters::TeX.new(bibliographer.options['citation-style'])
+      when *Formatters::TeX::MACROS.keys
+        formatter = Formatters::TeX.new(bibliographer.options.tex_style)
         formatter.import bibliographer.database
-        formatter.render(bibliographer, self)
+        formatter.render bibliographer, self
       end
     end
 
-    def render_citation_with_csl(bibliographer)
-      formatter = Formatters::CSL.new(bibliographer.options['reference-style'])
+    def render_fullcite_with_csl(bibliographer)
+      formatter = Formatters::CSL.new(bibliographer.options.style)
+      prepare_fullcite_item bibliographer, formatter
+      formatted_citation = formatter.render(:bibliography, id: citation_items.first.key).join
+      formatted_citation = Helpers.html_to_asciidoc formatted_citation
+      # We prepend an empty interpolation to avoid interferences w/ standard syntax (e.g. block role is "\n[foo]")
+      "{empty}" + formatted_citation
+    end
 
-      cites_with_local_attributes = citation_items.map { |cite| prepare_cite_metadata bibliographer, cite }
-      formatter.import cites_with_local_attributes
-      formatter.sort(mode: :citation)
-      items = formatter.data.map(&:cite)
-      items.each { |item| prepare_citation_item item, hyperlink: bibliographer.options['hyperlinks'] == 'true' }
+    def prepare_fullcite_item(bibliographer, formatter)
+      formatter.import([bibliographer.database.find_entry_by_id(citation_items.first.key)])
+    end
 
+    def render_citation_with_csl(bibliographer)
+      formatter = Formatters::CSL.new(bibliographer.options.style)
+      items = prepare_items bibliographer, formatter
       formatted_citation = formatter.engine.renderer.render(items, formatter.engine.style.citation)
+      escape_brackets_inside_xref! formatted_citation
       # We prepend an empty interpolation to avoid interferences w/ standard syntax (e.g. block role is "\n[foo]")
-      '{empty}' + formatted_citation.gsub(/{{{(?<xref_label>.*?)}}}/) do
-        # We escape closing square brackets inside the xref label.
-        ['[', Regexp.last_match[:xref_label].gsub(']', '\]'), ']'].join
-      end
+      "{empty}" + formatted_citation
     end
 
-    def prepare_cite_metadata(bibliographer, cite)
-      bibliographer.database.find { |e| e['id'] == cite.key }
-                   .merge('citation-number': bibliographer.appearance_index_of(cite.key))
-                   .merge('citation-label': cite.key) # TODO: smart label generators
-                   .merge('locator': cite.locators.any? ? ' ' : nil)
-      # TODO: why is 'locator' necessary to display locators? (and not just in the item, later)
+    def escape_brackets_inside_xref!(string)
+      string.gsub!(/{{{(?<xref_label>.*?)}}}/) do
+        ["[", Regexp.last_match[:xref_label].gsub("]", '\]'), "]"].join
+      end
     end
 
-    def prepare_citation_item(item, hyperlink:)
-      # Wrap into hyperlink
-      if hyperlink
-        item.prefix = "xref:#{xref_id(item.id)}{{{" + item.prefix.to_s
-        item.suffix = item.suffix.to_s + '}}}'
-      end
-      # Assign locator
-      locator = citation_items.find { |cite| cite.key == item.id }.locators.first
-      item.label, item.locator = locator unless locator.nil?
-      # TODO: suppress_author and only_author options?
+    def prepare_items(bibliographer, formatter)
+      cites_with_local_attributes = citation_items.map { |cite| prepare_metadata bibliographer, cite }
+      formatter.import cites_with_local_attributes
+      formatter.sort(mode: :citation)
+      formatter.data.map(&:cite).each { |item| prepare_item bibliographer.options, item }
     end
 
-    def render_fullcite_with_csl(bibliographer)
-      formatter = Formatters::CSL.new(bibliographer.options['reference-style'])
+    def prepare_metadata(bibliographer, cite)
+      bibliographer.database.find_entry_by_id(cite.key).
+        merge('citation-number': bibliographer.appearance_index_of(cite.key)).
+        merge('citation-label': cite.key). # TODO: smart label generators
+        merge('locator': cite.locator.nil? ? nil : " ")
+      # TODO: why is a non blank 'locator' necessary to display locators set at a later stage?
+    end
 
-      # NOTE: being able to overwrite a more general family of attributes would be neat.
-      mergeable_attributes = Helpers.slice(citation_items.first.named_attributes || {}, *REF_ATTRIBUTES.map(&:to_s))
+    def prepare_item(options, item)
+      # TODO: hyperlink, suppress_author and only_author options
+      ci = citation_items.detect { |c| c.key == item.id }
+      wrap_item item, ci.prefix, ci.suffix
+      wrap_item item, "xref:#{xref_id(item.id)}{{{", "}}}" if options.hyperlinks?
+      item.label, item.locator = ci.locator
+    end
 
-      # reject empty values
-      mergeable_attributes.reject! do |_key, value|
-        value.nil? || value.empty?
-      end
-      # TODO: as is, citation items other than the first are simply ignored.
-      database_entry = bibliographer.database.find { |e| e['id'] == citation_items.first.key }
-      database_entry.merge!(mergeable_attributes)
-      formatter.import([database_entry])
-      '{empty}' + Helpers.html_to_asciidoc(formatter.render(:bibliography, id: citation_items.first.key).join)
-      # '{empty}' + Helpers.html_to_asciidoc(formatter.render(:citation, id: citation_items.first.key))
+    def wrap_item(item, prefix, suffix)
+      item.prefix = prefix.to_s + item.prefix.to_s
+      item.suffix = item.suffix.to_s + suffix.to_s
     end
 
     def uuid
@@ -96,7 +99,7 @@ module AsciidoctorBibliography
     end
 
     def xref_id(key)
-      ['bibliography', key].compact.join('-')
+      ["bibliography", key].compact.join("-")
     end
 
     def xref(key, label)

data/lib/asciidoctor-bibliography/citation_item.rb

@@ -1,26 +1,35 @@
-require 'asciidoctor/attribute_list'
+require "asciidoctor/attribute_list"
 
 module AsciidoctorBibliography
   class CitationItem
+    LOCATORS = CiteProc::CitationItem.labels.map(&:to_s).push("locator").freeze
+
     attr_accessor :key, :target, :positional_attributes, :named_attributes, :locators
 
     def initialize
       yield self if block_given?
     end
 
+    def prefix
+      named_attributes["prefix"]
+    end
+
+    def suffix
+      named_attributes["suffix"]
+    end
+
     def locators
-      Helpers
-        .slice(named_attributes || {}, *CiteProc::CitationItem.labels.map(&:to_s))
-        .reject { |_, value| value.nil? || value.empty? } # equivalent to Hash#compact
+      named_attributes.select { |key, _| LOCATORS.include? key }
+    end
+
+    def locator
+      locators.first
     end
 
     def parse_attribute_list(string)
-      parsed_attributes =
-        ::Asciidoctor::AttributeList.new(string).parse
-                                    .group_by { |hash_key, _| hash_key.is_a? Integer }
-                                    .values.map { |a| Hash[a] }
-      self.positional_attributes = parsed_attributes.first.values
-      self.named_attributes = parsed_attributes.last
+      parsed_attributes = ::Asciidoctor::AttributeList.new(string).parse
+      self.named_attributes = parsed_attributes.reject { |key, _| key.is_a? Integer }
+      self.positional_attributes = parsed_attributes.select { |key, _| key.is_a? Integer }.values
       self.key = positional_attributes.shift
     end
   end

data/lib/asciidoctor-bibliography/database.rb

@@ -1,5 +1,5 @@
-require_relative 'databases/bibtex'
-require_relative 'exceptions'
+require_relative "databases/bibtex"
+require_relative "errors"
 
 module AsciidoctorBibliography
   # This is an array of citeproc entries.
@@ -14,13 +14,25 @@ module AsciidoctorBibliography
       concat Database.load(filename)
     end
 
+    def find_entry_by_id(id)
+      result = detect { |entry| entry["id"] == id }
+      if result.nil?
+        message = "No entry with id '#{id}' was found in the bibliographic database."
+        raise Errors::Database::IdNotFound, message
+      end
+      result
+    end
+
     def self.load(filename)
-      case File.extname(filename)
+      filepath = File.expand_path filename
+      raise Errors::Database::FileNotFound, filepath unless File.exist?(filepath)
+
+      fileext = File.extname filepath
+      case fileext
       when *Databases::BibTeX::EXTENSIONS
-        Databases::BibTeX.load(filename)
+        Databases::BibTeX.load filepath
       else
-        raise Exceptions::DatabaseFormatNotSupported,
-              'Bibliographic database format not supported.'
+        raise Errors::Database::UnsupportedFormat, fileext
       end
     end
   end

data/lib/asciidoctor-bibliography/databases/bibtex.rb

@@ -1,12 +1,12 @@
-require 'bibtex'
-require 'bibtex/filters'
-require 'latex/decode/base'
-require 'latex/decode/maths'
-require 'latex/decode/accents'
-require 'latex/decode/diacritics'
-require 'latex/decode/punctuation'
-require 'latex/decode/symbols'
-require 'latex/decode/greek'
+require "bibtex"
+require "bibtex/filters"
+require "latex/decode/base"
+require "latex/decode/maths"
+require "latex/decode/accents"
+require "latex/decode/diacritics"
+require "latex/decode/punctuation"
+require "latex/decode/symbols"
+require "latex/decode/greek"
 
 module AsciidoctorBibliography
   module Databases
@@ -33,7 +33,7 @@ module AsciidoctorBibliography
           LaTeX::Decode::Symbols.decode!(text)
           LaTeX::Decode::Greek.decode!(text)
           text.gsub!(/\\url\{(.+?)\}/, ' \\1 ')
-          text.gsub!(/\\\w+(?=\s+\w)/, '')
+          text.gsub!(/\\\w+(?=\s+\w)/, "")
           text.gsub!(/\\\w+(?:\[.+?\])?\s*\{(.+?)\}/, '\\1')
           LaTeX::Decode::Base.strip_braces(text)
           LaTeX.normalize_C(text)

data/lib/asciidoctor-bibliography/errors.rb

@@ -0,0 +1,16 @@
+module AsciidoctorBibliography
+  module Errors
+    class Error < StandardError; end
+
+    module Options
+      class Missing < Error; end
+      class Invalid < Error; end
+    end
+
+    module Database
+      class UnsupportedFormat < Error; end
+      class FileNotFound < Error; end
+      class IdNotFound < Error; end
+    end
+  end
+end

data/lib/asciidoctor-bibliography/formatters/csl.rb

@@ -1,5 +1,6 @@
-require 'citeproc'
-require 'csl/styles'
+require "citeproc"
+require "csl/styles"
+require "yaml"
 
 module AsciidoctorBibliography
   module Formatters
@@ -8,6 +9,16 @@ module AsciidoctorBibliography
         super style: style, format: :html
       end
 
+      def replace_bibliography_sort(array)
+        new_keys = array.map(&::CSL::Style::Sort::Key.method(:new))
+        new_sort = ::CSL::Style::Sort.new.add_children(*new_keys)
+
+        bibliography = engine.style.find_child("bibliography")
+        bibliography.find_child("sort")&.unlink
+
+        bibliography.add_child new_sort
+      end
+
       def sort(mode:)
         # Valid modes are :citation and :bibliography
         engine.sort! data, engine.style.send(mode).sort_keys if engine.style.send(mode).sort?

data/lib/asciidoctor-bibliography/formatters/tex.rb

@@ -3,20 +3,19 @@ module AsciidoctorBibliography
     # This formatter emulates the behaviour of traditional Bib(La)TeX/NatBib citations.
     class TeX
       MACROS = {
-        # NOTE: cite = citet
-        'cite'        => { type: :textual,       bracketed: true,  authors: :abbreviated },
-        'citet'       => { type: :textual,       bracketed: true,  authors: :abbreviated },
-        'citet*'      => { type: :textual,       bracketed: true,  authors: :full },
-        'citealt'     => { type: :textual,       bracketed: false, authors: :abbreviated },
-        'citealt*'    => { type: :textual,       bracketed: false, authors: :full },
-        'citep'       => { type: :parenthetical, bracketed: true,  authors: :abbreviated },
-        'citep*'      => { type: :parenthetical, bracketed: true,  authors: :full },
-        'citealp'     => { type: :parenthetical, bracketed: false, authors: :abbreviated },
-        'citealp*'    => { type: :parenthetical, bracketed: false, authors: :full },
-        'citeauthor'  => { type: :authors_only,  bracketed: false, authors: :abbreviated },
-        'citeauthor*' => { type: :authors_only,  bracketed: false, authors: :full },
-        'citeyear'    => { type: :years_only,    bracketed: false },
-        'citeyearpar' => { type: :years_only,    bracketed: true }
+        # NOTE: \citet is equivalent to \cite, so we reserve the latter for CSL styling.
+        "citet"       => { type: :textual,       bracketed: true,  authors: :abbreviated },
+        "citet*"      => { type: :textual,       bracketed: true,  authors: :full },
+        "citealt"     => { type: :textual,       bracketed: false, authors: :abbreviated },
+        "citealt*"    => { type: :textual,       bracketed: false, authors: :full },
+        "citep"       => { type: :parenthetical, bracketed: true,  authors: :abbreviated },
+        "citep*"      => { type: :parenthetical, bracketed: true,  authors: :full },
+        "citealp"     => { type: :parenthetical, bracketed: false, authors: :abbreviated },
+        "citealp*"    => { type: :parenthetical, bracketed: false, authors: :full },
+        "citeauthor"  => { type: :authors_only,  bracketed: false, authors: :abbreviated },
+        "citeauthor*" => { type: :authors_only,  bracketed: false, authors: :full },
+        "citeyear"    => { type: :years_only,    bracketed: false },
+        "citeyearpar" => { type: :years_only,    bracketed: true },
       }.freeze
 
       attr_accessor :opening_bracket,
@@ -27,10 +26,10 @@ module AsciidoctorBibliography
                     :years_separator
 
       def initialize(format)
-        if format == 'numbers'
-          bibpunct = '{[}{]}{,}{n}{,}{,}'
-        elsif format == 'authoryear'
-          bibpunct = '{(}{)}{;}{a}{,}{,}'
+        if format == "numbers"
+          bibpunct = "{[}{]}{,}{n}{,}{,}"
+        elsif format == "authoryear"
+          bibpunct = "{(}{)}{;}{a}{,}{,}"
         else
           raise StandardError, "Unknown TeX citation format: #{format}"
         end
@@ -50,56 +49,55 @@ module AsciidoctorBibliography
         macro_options = MACROS[citation.macro]
         output = []
         case macro_options[:type]
-        when :full
         # NOTE: deliberately repetitive to improve redability.
         when :textual
           citation.citation_items.each do |cite|
             authors = authors(macro_options[:authors], cite)
-            year = if @style == 'n'
+            year = if @style == "n"
                      bibliographer.appearance_index_of(cite.key)
                    else
                      year(cite)
                    end
-            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + ' ')
+            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + " ")
             cetera = bracket(cetera) if macro_options[:bracketed]
-            label = Helpers.join_nonempty([authors, cetera], ' ')
+            label = Helpers.join_nonempty([authors, cetera], " ")
             output << citation.xref(cite.key, label)
           end
-          output = output.join(@cites_separator + ' ')
+          output = output.join(@cites_separator + " ")
         when :parenthetical
           citation.citation_items.each do |cite|
-            if @style == 'n'
+            if @style == "n"
               authors = nil
               year = bibliographer.appearance_index_of(cite.key)
             else
               authors = authors(macro_options[:authors], cite)
               year = year(cite)
             end
-            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + ' ')
-            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + ' ')
+            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + " ")
+            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + " ")
             output << citation.xref(cite.key, label)
           end
-          output = output.join(@cites_separator + ' ')
+          output = output.join(@cites_separator + " ")
           output = bracket(output) if macro_options[:bracketed]
         when :authors_only
           citation.citation_items.each do |cite|
             authors = authors(macro_options[:authors], cite)
             year = nil
-            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + ' ')
-            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + ' ')
+            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + " ")
+            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + " ")
             output << citation.xref(cite.key, label)
           end
-          output = output.join(@cites_separator + ' ')
+          output = output.join(@cites_separator + " ")
           output = bracket(output) if macro_options[:bracketed]
         when :years_only
           citation.citation_items.each do |cite|
             authors = nil
             year = year(cite)
-            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + ' ')
-            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + ' ')
+            cetera = Helpers.join_nonempty([year].concat(extra(cite)), @years_separator + " ")
+            label = Helpers.join_nonempty([authors, cetera], @author_year_separator + " ")
             output << citation.xref(cite.key, label)
           end
-          output = output.join(@cites_separator + ' ')
+          output = output.join(@cites_separator + " ")
           output = bracket(output) if macro_options[:bracketed]
         else
           raise StandardError, "Unknown TeX citation macro type: #{macro_options[:type]}"
@@ -115,24 +113,24 @@ module AsciidoctorBibliography
       end
 
       def find_entry(key)
-        entry = @database.find { |h| h['id'] == key }
+        entry = @database.detect { |h| h["id"] == key }
         raise StandardError, "Can't find entry: #{key}" if entry.nil?
         entry
       end
 
       def year(cite)
         entry = find_entry(cite.key)
-        issued = entry['issued']
+        issued = entry["issued"]
 
         if issued.nil?
-          puts "asciidoctor-bibliography: citation (#{cite.key}) has no 'issued' information"
-          return ''
+          warn "asciidoctor-bibliography: citation (#{cite.key}) has no 'issued' information"
+          return ""
         end
 
-        date_parts = issued['date-parts']
-        return '' if date_parts.nil?
+        date_parts = issued["date-parts"]
+        return "" if date_parts.nil?
 
-        return '' if date_parts.first.nil?
+        return "" if date_parts.first.nil?
         date_parts.first.first
       end
 
@@ -168,20 +166,20 @@ module AsciidoctorBibliography
 
       def authors_list(cite)
         entry = find_entry(cite.key)
-        authors = entry['author']
+        authors = entry["author"]
         return [] if authors.nil?
-        authors.map { |h| h['family'] }.compact
+        authors.map { |h| h["family"] }.compact
       end
 
       def authors_abbreviated(cite)
         authors = authors_list(cite)
-        return '' if authors.empty?
+        return "" if authors.empty?
         authors.length > 1 ? "#{authors.first} et al." : authors.first
       end
 
       def authors_full(cite)
         authors = authors_list(cite)
-        return '' if authors.empty?
+        return "" if authors.empty?
         Helpers.to_sentence authors
       end
     end