asciidoctor-bibliography 0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24be1ddb4ec69d1ffabf68e2fc7cf1c628be6130
-  data.tar.gz: b0abf289da6967d4da9e1aeb75acfadc3a4a5f24
+  metadata.gz: 6260e8b2da719aeb370dfe1946181cab10dadd35
+  data.tar.gz: f8e5f843bd9348f0333c1257b042578ce2f435b6
 SHA512:
-  metadata.gz: a46db6e6d83b1faa86df2d69d521a7f1810e0f7bd53ee6abe339328c425aff40b7fe9f804c94fe6fb6d93a5afc19f241311e79caf333fce6fcc12cd5f4a610dc
-  data.tar.gz: dc999d205e2c1d919489ba773eb37ea42253eb4b922e40a9abca0109e76ded8e8446cfe9276959ab92c1dffd8831fb81e610fa425a5910a8f2ae1919769ec52f
+  metadata.gz: 0cec621922c04cbefa6047adf59a648413c72253366172d2beda895708c6559ce52d79c07a13a71f20b573e04b3c6de69e0dc30c69ef07def99afc2689c3284b
+  data.tar.gz: a927d96b5e3c2725643ae0b20aea75147281d288de88d5dd578306c83559c2a27227217c4afb8e3639d7afa2fa4d8498365b6b142b3d8b976a5b9a44cd36e40e

data/.gitignore

@@ -48,3 +48,6 @@ Gemfile.lock
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+**/.byebug
+.byebug_history

data/.rubocop.yml

@@ -0,0 +1,17 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  Excludes:
+    - deprecated/**/*.rb
+    - spec/**/*.rb
+
+Metrics/LineLength:
+  Max: 120
+
+FrozenStringLiteralComment:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Documentation:
+  Enabled: false

data/Gemfile

@@ -1,3 +1,3 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 gemspec

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/asciidoctor-bibliography.gemspec

@@ -1,40 +1,42 @@
 # coding: utf-8
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "asciidoctor-bibliography/version"
+require 'asciidoctor-bibliography/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "asciidoctor-bibliography"
+  spec.name          = 'asciidoctor-bibliography'
   spec.version       = AsciidoctorBibliography::VERSION
-  spec.authors       = ["Ribose Inc."]
-  spec.email         = ["open.source@ribose.com"]
+  spec.authors       = ['Ribose Inc.']
+  spec.email         = ['open.source@ribose.com']
 
-  spec.summary       = "Bibliographic references for asciidoc"
-  spec.description   = <<-END
-asciidoctor-bibliography adds bibliography support for asciidoc documents by introducing
-two new macros: `cite:[KEY]` and `bibliography::[]`. Citations are parsed and
-replaced with formatted inline texts, and reference lists are automatically
-generated and inserted into where `bibliography::[]` is placed.  The
-references are formatted using styles provided by CSL.
+  spec.summary       = 'Bibliographic references for asciidoc'
+  spec.description   = <<~END
+    asciidoctor-bibliography adds bibliography support for asciidoc documents by introducing
+    two new macros: `cite:[KEY]` and `bibliography::[]`. Citations are parsed and
+    replaced with formatted inline texts, and reference lists are automatically
+    generated and inserted into where `bibliography::[]` is placed.  The
+    references are formatted using styles provided by CSL.
 END
-  spec.homepage      = "https://github.com/riboseinc/asciidoctor-bibliography"
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/riboseinc/asciidoctor-bibliography'
+  spec.license       = 'MIT'
 
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
   spec.files         = `git ls-files`.split("\n")
   spec.test_files    = `git ls-files -- {spec}/*`.split("\n")
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.0.0")
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
 
-  spec.add_dependency "asciidoctor"
-  spec.add_dependency "citeproc-ruby"
-  spec.add_dependency "csl-styles", "~> 1"
-  spec.add_dependency "latex-decode", "~> 0.2"
-  spec.add_dependency "bibtex-ruby"
+  spec.add_dependency 'asciidoctor'
+  spec.add_dependency 'citeproc-ruby'
+  spec.add_dependency 'csl-styles', '~> 1'
+  spec.add_dependency 'latex-decode', '~> 0.2'
+  spec.add_dependency 'bibtex-ruby'
 
-  spec.add_development_dependency "bundler", "~> 1.14"
-  spec.add_development_dependency "byebug"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rubocop'
 end

data/lib/asciidoctor-bibliography.rb

@@ -1,3 +1,6 @@
-# require 'byebug' if Gem.gem("byebug")
+begin
+  require 'byebug'
+rescue LoadError
+end
 
 require_relative 'asciidoctor-bibliography/asciidoctor'

data/lib/asciidoctor-bibliography/asciidoctor.rb

@@ -1,17 +1,11 @@
 require 'asciidoctor/extensions'
 
 require_relative 'asciidoctor/bibliographer_preprocessor'
+require_relative 'asciidoctor/document_ext'
 require_relative 'bibliographer'
 
+Asciidoctor::Document.include AsciidoctorBibliography::Asciidoctor::DocumentExt
+
 Asciidoctor::Extensions.register do
   preprocessor AsciidoctorBibliography::Asciidoctor::BibliographerPreprocessor
 end
-
-module Asciidoctor
-  class Document
-    # All our document-level permanence passes through this attribute accessor.
-    def bibliographer
-      @bibliographer ||= AsciidoctorBibliography::Bibliographer.new
-    end
-  end
-end

data/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb

@@ -1,8 +1,7 @@
 require 'asciidoctor'
+require 'pp'
 
 require_relative '../helpers'
-require_relative '../formatters/csl'
-require_relative '../formatters/tex'
 require_relative '../database'
 require_relative '../citation'
 require_relative '../index'
@@ -10,15 +9,16 @@ require_relative '../index'
 module AsciidoctorBibliography
   module Asciidoctor
     class BibliographerPreprocessor < ::Asciidoctor::Extensions::Preprocessor
-      def process document, reader
+      def process(document, reader)
         set_bibliographer_options(document, reader)
 
-        # We're handling single database/formatters; generalization will be straightforward when needed.
+        if document.bibliographer.options['database'].nil?
+          warn "No bibliographic database was provided: all bibliographic macros will be ignored. You can set it using the 'bibliography-database' option in the document's preamble."
+          return reader
+        end
+
+        # Load database(s).
         document.bibliographer.database = Database.new(document.bibliographer.options['database'])
-        document.bibliographer.index_formatter = Formatters::CSL.new(document.bibliographer.options['reference-style'])
-        document.bibliographer.index_formatter.import document.bibliographer.database
-        document.bibliographer.citation_formatter = Formatters::TeX.new(document.bibliographer.options['citation-style'])
-        document.bibliographer.citation_formatter.import document.bibliographer.database
 
         # Find, store and replace citations with uuids.
         processed_lines = reader.read_lines.map do |line|
@@ -31,6 +31,7 @@ module AsciidoctorBibliography
         reader = ::Asciidoctor::Reader.new processed_lines
 
         # NOTE: retrieval and formatting are separated to allow sorting and numeric styles.
+        # document.bibliographer.sort
 
         # Find and replace uuids with formatted citations.
         processed_lines = reader.lines.join("\n") # for quicker matching
@@ -40,7 +41,6 @@ module AsciidoctorBibliography
           end
         end
         processed_lines = processed_lines.lines.map(&:chomp)
-
         reader = ::Asciidoctor::Reader.new processed_lines
 
         # Find and format indices.
@@ -53,19 +53,47 @@ module AsciidoctorBibliography
           end
         end
         processed_lines.flatten!
-        reader = ::Asciidoctor::Reader.new processed_lines
+        ::Asciidoctor::Reader.new processed_lines
       end
 
       private
 
+      OPTIONS_PREFIX = 'bibliography-'.freeze
+
+      OPTIONS_DEFAULTS = {
+        'order' => 'alphabetical',
+        'reference-style' => 'apa',
+        'citation-style' => 'authoryear',
+        'hyperlinks' => 'true',
+        'database' => nil
+      }.freeze
+
       def set_bibliographer_options(document, reader)
         # We peek at the document attributes we need, without perturbing the parsing flow.
         # NOTE: we're in a preprocessor and they haven't been parsed yet; doing it manually.
-        document_attributes =
-          ::Asciidoctor::Parser
-            .parse(reader, ::Asciidoctor::Document.new, header_only: true)
-            .attributes
-        document.bibliographer.options = Hash[Helpers.slice(document_attributes, 'bibliography-citation-style', 'bibliography-order', 'bibliography-reference-style', 'bibliography-database').map {|k, v| [k.sub(/^bibliography-/, ''), v] }]
+        # pp reader
+        header_attributes = extract_header_attributes reader
+        user_options = filter_bibliography_attributes header_attributes
+        document.bibliographer.options = OPTIONS_DEFAULTS.merge user_options
+      end
+
+      def extract_header_attributes(reader)
+        tdoc = ::Asciidoctor::Document.new
+        treader = ::Asciidoctor::PreprocessorReader.new(
+          tdoc,
+          reader.source_lines
+        )
+
+        ::Asciidoctor::Parser
+          .parse(treader, tdoc, header_only: true)
+          .attributes
+      end
+
+      def filter_bibliography_attributes(hash)
+        Helpers
+          .slice(hash, *OPTIONS_DEFAULTS.keys.map { |k| "#{OPTIONS_PREFIX}#{k}" })
+          .map { |k, v| [k[OPTIONS_PREFIX.length..-1], v] }.to_h
+          .reject { |_, value| value.nil? || value.empty? }.to_h
       end
     end
   end

data/lib/asciidoctor-bibliography/asciidoctor/document_ext.rb

@@ -0,0 +1,11 @@
+# Extends Document to support additional method
+module AsciidoctorBibliography
+  module Asciidoctor
+    module DocumentExt
+      # All our document-level permanence passes through this accessor.
+      def bibliographer
+        @bibliographer ||= AsciidoctorBibliography::Bibliographer.new
+      end
+    end
+  end
+end

data/lib/asciidoctor-bibliography/bibliographer.rb

@@ -3,29 +3,40 @@ module AsciidoctorBibliography
     attr_accessor :citations
     attr_accessor :indices
     attr_accessor :database
-    attr_accessor :index_formatter
-    attr_accessor :citation_formatter
     attr_reader :occurring_keys
     attr_accessor :options
 
-    # NOTE: while database and formatter are singular, they're meant for future generalization.
-
     def initialize
       @options = {}
       @citations = []
       @indices = []
       @database = nil
-      @index_formatter = nil
-      @citation_formatter = nil
       @occurring_keys = []
     end
 
     def add_citation(citation)
       citations << citation
-      @occurring_keys.concat(citation.keys).uniq!
-      citations.last.cites.each do |cite|
-        cite.occurrence_index = @occurring_keys.index(cite.key)
+      @occurring_keys.concat(citation.citation_items.map(&:key)).uniq!
+    end
+
+    def appearance_index_of(id)
+      @occurring_keys.index(id) + 1
+    end
+
+    def sort
+      if options['order'] == 'alphabetical'
+        @occurring_keys = @occurring_keys.sort_by do |target|
+          first_author_family_name(target)
+        end
       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?
+    end
   end
 end

data/lib/asciidoctor-bibliography/citation.rb

@@ -1,83 +1,106 @@
 require 'securerandom'
-require 'asciidoctor/attribute_list'
+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*?)?\[(|.*?[^\\])\])*/
-    REF_ATTRIBUTES = %i[chapter page section clause]
+    REF_ATTRIBUTES = %i[chapter page section clause].freeze
 
-    # No need for a fully fledged class right now.
-    Cite = Struct.new(:key, :occurrence_index, :target, :positional_attributes, :named_attributes)
+    attr_reader :macro, :citation_items
 
-    attr_reader :macro, :cites
-
-    def initialize(macro, *targets_and_attributes_list)
+    def initialize(macro, *target_and_attributes_list_pairs)
       @uuid = SecureRandom.uuid
       @macro = macro
-      @cites = []
-      targets_and_attributes_list.compact.each_slice(2).each do |target, attributes|
-        positional_attributes, named_attributes = # true, false
-          ::Asciidoctor::AttributeList.new(attributes).parse
-            .group_by { |hash_key, _| hash_key.is_a? Integer }
-            .values.map { |a| Hash[a] }
-        positional_attributes = positional_attributes.values
-        @cites << Cite.new(
-          positional_attributes.first,
-          nil,
-          target,
-          positional_attributes,
-          named_attributes
-        )
+      @citation_items = []
+      target_and_attributes_list_pairs.compact.each_slice(2).each do |_target, attribute_list|
+        @citation_items << CitationItem.new do |cite|
+          # NOTE: we're not doing anything with targets right now.
+          # cite.target = _target
+          cite.parse_attribute_list attribute_list
+        end
       end
     end
 
     def render(bibliographer)
-      if macro == 'fullcite'
-        formatter = Formatters::CSL.new(bibliographer.options['reference-style'])
-
-        # NOTE: being able to overwrite a more general family of attributes would be neat.
-        mergeable_attributes = Helpers.slice(cites.first.named_attributes || {}, *(REF_ATTRIBUTES.map(&:to_s)))
-
-        # reject empty values
-        mergeable_attributes.reject! do |key, value|
-          value.nil? || value.empty?
-        end
-        # TODO: as is, cites other than the first are simply ignored.
-        database_entry = bibliographer.database.find { |e| e['id'] == cites.first.key }
-        database_entry.merge!(mergeable_attributes)
-        formatter.import([database_entry])
-        '{empty}' + Helpers.html_to_asciidoc(formatter.render(:bibliography, id: cites.first.key).join)
+      if macro == 'cite'
+        render_citation_with_csl(bibliographer)
+      elsif macro == 'fullcite'
+        render_fullcite_with_csl(bibliographer)
       elsif Formatters::TeX::MACROS.keys.include? macro
-        bibliographer.citation_formatter.render(self)
+        formatter = Formatters::TeX.new(bibliographer.options['citation-style'])
+        formatter.import bibliographer.database
+        formatter.render(bibliographer, self)
       end
     end
 
-    def uuid
-      ":#{@uuid}:"
+    def render_citation_with_csl(bibliographer)
+      formatter = Formatters::CSL.new(bibliographer.options['reference-style'])
+
+      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' }
+
+      formatted_citation = formatter.engine.renderer.render(items, formatter.engine.style.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
     end
 
-    def keys
-      @cites.map { |h| h[:key] }
+    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)
     end
 
-    def xref(key, label)
-      "xref:#{self.render_id(key)}[#{label.gsub(']','\]')}]"
+    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?
     end
 
-    def render_id(key)
-      ['bibliography', key].compact.join('-')
+    def render_fullcite_with_csl(bibliographer)
+      formatter = Formatters::CSL.new(bibliographer.options['reference-style'])
+
+      # 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))
+
+      # 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))
     end
 
-    private
+    def uuid
+      ":#{@uuid}:"
+    end
 
-    def render_label(formatter, key)
-      formatter.render(:citation, id: key)
+    def xref_id(key)
+      ['bibliography', key].compact.join('-')
     end
 
-    def render_xref(formatter, key)
-      "xref:#{render_id(key)}[#{render_label(formatter, key)}]"
+    def xref(key, label)
+      "xref:#{xref_id(key)}[#{label.gsub(']', '\]')}]"
     end
   end
 end
-