uc3-citation 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a8f1ca6a2e8720d0137706a9788c6d55759a04106e53dd5d8f21dae4c43911b
+  data.tar.gz: '09ac870471ad1a5602a7acc6794bc3197bacedad41477626a0fe92b4f2bddbf8'
+SHA512:
+  metadata.gz: a196e0002d906a33f9c5177e78717c994f6a635bf81a68894b611bf09cc3399a661e47c16c559050c015b3dfab316cadd70287c887232ec268c922ef1476c618
+  data.tar.gz: 1aa7b8cca0823887eaaa80ed9690d2056c46ee2eefbf7395e83d30815cf8538e451e624f033c2c2b79374e27c2653d50f748a723ea351a3af87154c909de7aed

data/README.md

@@ -0,0 +1,54 @@
+uc3-citation
+===============
+
+A library that retrieves an citation for the specified DOI following the Chicago Author-Date standard.
+
+This service makes a request to the DOI registrar and asks for the BibTeX version of the DOI's metadata.
+
+If BibTeX metadata is received the service will use the CiteProc gem to build a citation that follows the Chicago Author-Date format (CiteProc uses [Citation Style Language (CSL)](https://citationstyles.org/) to build the citation). The citation is in HTML format.
+
+You can override the default Chicago style by specifying one from the list of CSLs located in the following repository: https://github.com/citation-style-language/styles-distribution/tree/f8524f9b9df60e94e98f824f242a1fb27cc9fc59
+For example `Uc3::Citation.fetch(doi: '10.1234/article.ef34', work_type: 'article', style: 'apa')`
+
+## Basic Usage -
+
+Add the following to your Gemfile and then run bundle install:
+`gem 'uc3-citation', git: 'https://github.com/CDLUC3/uc3-citation', branch: 'main'`
+
+Once installed you can then use the service like this:
+```ruby
+  class YourClass
+    include Uc3Citation
+
+    article = fetch_citation(
+      doi: 'https://doi.org/10.3897/BDJ.9.e67426',
+      work_type: 'dataset'
+    )
+
+    p article
+    # Will display:
+    #
+    # Reboleira, Ana Sofia, and Rita Eus\'ebio. 2021. “Cave-Adapted Beetles from Continental
+    # Portugal.” [Dataset]. Biodiversity Data Journal 9 (August).
+    # https://doi.org/10.3897/BDJ.9.e67426.
+  end
+```
+
+The `fetch_citation` method accepts the following arguments:
+- **doi**: The fully qualified URl or the DOI as a string. (e.g. 'https://doi.org/10.3897/BDJ.9.e67426', 'doi:10.3897/BDJ.9.e67426', or '10.3897/BDJ.9.e67426'). In the case where you are only passing the DOI, it will prepend 'https://doi.org/' when trying to acquire the citation. If the DOI is not resolvable from that domain then you will need to send the full URL
+- **work_type**: Default is nil. If present, the value you specify will be added to the citation after the title to provide context as to what type of work the DOI represents. See example above.
+- **style**: Default is 'chicago-author-date'. You can specify [any of the CSL defined in this list](https://github.com/citation-style-language/styles-distribution/tree/f8524f9b9df60e94e98f824f242a1fb27cc9fc59)
+- **debug**: Default is false. If true it will log the results of the request for the BibTeX metadata from the DOI registrar and the result of the citation generation from the CitProc library
+
+Although unlikely, since citations are acquired from external sources, it is a good idea to wrap the citation in a sanitization method when displaying on a web page to prevent any malicious HTML. For example in a Rails view you can use: `sanitize(article)`
+
+You should consider the fact that this gem calls out to external systems when incorporating it into your projects. For example adding to a Model or Controller method in Rails can potentially cause slow response times. You may want to use ActiveJob or at the very least an `after_save` callback to prevent it from slowing down the Rails thread that is handling the Request-Response cycle.
+
+## Troubleshooting
+
+If you are not receiving a citation for a specific DOI and you believe you should, you should:
+
+1. Verify that the DOI is able to produce the BibTeX format. For exmaple: `curl -vLH 'Accept: application/x-bibtex' https://doi.org/10.3897/BDJ.9.e67426`
+2. Specify `debug: true` when calling `fetch_citation` which will output the BibTex and CiteProc responses to your log file.
+
+NOTE that errors encountered by the gem are always written to the logs regardless of the `:debug` flag specification

data/lib/uc3-citation/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Uc3Citation
+  VERSION = '0.0.5'
+end

data/lib/uc3-citation.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'bibtex'
+require 'citeproc'
+require 'csl/styles'
+require 'httparty'
+require 'logger'
+
+# This service provides an interface to Datacite API.
+module Uc3Citation
+
+  DEFAULT_DOI_URL = 'https://doi.org'.freeze
+
+  # Create a new DOI
+  # rubocop:disable Metrics/CyclomaticComplexity
+  def fetch_citation(doi:, work_type: '', style: 'chicago-author-date', debug: false)
+    return nil unless doi.is_a?(String) && doi.strip != ''
+
+    # Set the logger
+    logger = Object.const_defined?("Rails") ? Rails.logger : Logger.new(STDOUT)
+
+    uri = doi_to_uri(doi: doi.strip)
+    logger.debug("Uc3Citation - Fetching BibTeX from: '#{uri}'") if debug
+    resp = fetch_bibtex(uri: uri)
+    return nil if resp.code != 200
+
+    bibtex = BibTeX.parse(resp.body)
+    logger.debug('Uc3Citation - Received BibTeX') if debug
+    logger.debug(bibtex.data.inspect) if debug
+
+    work_type = determine_work_type(bibtex: bibtex) if work_type.nil? || work_type.split == ''
+
+    citation = bibtex_to_citation(
+      uri: uri,
+      work_type: work_type,
+      bibtex: bibtex,
+      style: style
+    )
+    logger.debug('Uc3Citation - Citation accquired') if debug
+    logger.debug(citation) if debug
+
+    citation
+  rescue URI::InvalidURIError => e
+    logger.error("Uc3Citation - URI: '#{uri}' - InvalidURIError: #{e.message}")
+    nil
+  rescue HTTParty::Error => e
+    logger.error("Uc3Citation - URI: '#{uri}' - HTTPartyError: #{e.message}")
+    logger.error(e&.backtrace)
+    nil
+  rescue SocketError => e
+    logger.error("Uc3Citation - URI: '#{uri}' - CiteProc SocketError: #{e.message}")
+    logger.error(bibtex&.inspect)
+    logger.error(e&.backtrace)
+    nil
+  rescue StandardError => e
+    logger.error("Uc3Citation - error - #{e.class.name}: #{e.message}")
+    logger.error(e&.backtrace)
+    nil
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity
+
+  private
+
+  # Will convert 'doi:10.1234/abcdefg' to 'http://doi.org/10.1234/abcdefg'
+  def doi_to_uri(doi:)
+    return nil unless doi.is_a?(String) && doi.strip != ''
+
+    doi.start_with?('http') ? doi : "#{DEFAULT_DOI_URL}/#{doi.gsub('doi:', '')}"
+  end
+
+  # If no :work_type was specified we can try to derive it from the BibTeX metadata
+  def determine_work_type(bibtex:)
+    return '' if bibtex.nil? || bibtex.data.nil? || bibtex.data.first.nil?
+
+    return 'article' unless bibtex.data.first.journal.nil?
+
+    ''
+  end
+
+  # Recursively call the URI for application/x-bibtex
+  def fetch_bibtex(uri:)
+    return nil unless uri.is_a?(String) && uri.strip != ''
+
+    # Cannot use underlying Base Service here because the Accept seems to
+    # be lost after multiple redirects
+    resp = HTTParty.get(uri, headers: { 'Accept': 'application/x-bibtex' },
+                              follow_redirects: false)
+    return resp if resp.headers['location'].nil?
+
+    fetch_bibtex(uri: resp.headers['location'])
+  end
+
+  # Convert the BibTeX item to a citation
+  def bibtex_to_citation(uri:, work_type:, bibtex:, style:)
+    return nil unless uri.is_a?(String) && uri.strip != ''
+    return nil if bibtex.nil? || bibtex.data.nil? || bibtex.data.first.nil?
+
+    cp = CiteProc::Processor.new(style: style, format: 'html')
+    cp.import(bibtex.to_citeproc)
+    citation = cp.render(:bibliography, id: bibtex.data.first.id)
+    return nil unless citation.is_a?(Array) && citation.any?
+
+    # The CiteProc renderer has trouble with some things so fix them here
+    #
+    #   - It has a '{textendash}' sometimes because it cannot render the correct char
+    #   - For some reason words in all caps in the title get wrapped in curl brackets
+    #   - We want to add the work type after the title. e.g. `[Dataset].`
+    #
+    citation = citation.first.gsub(/{\\Textendash}/i, '-')
+                              .gsub('{', '').gsub('}', '')
+
+    unless work_type.nil? || work_type.strip == ''
+      # This supports the :apa and :chicago-author-date styles
+      citation = citation.gsub(/\.”\s+/, "\.” [#{work_type.gsub('_', ' ').capitalize}]. ")
+                         .gsub(/<\/i>\.\s+/, "<\/i>\. [#{work_type.gsub('_', ' ').capitalize}]. ")
+    end
+
+    # Convert the URL into a link. Ensure that the trailing period is not a part of
+    # the link!
+    citation.gsub(URI.regexp) do |url|
+      if url.start_with?('http')
+        '<a href="%{url}" target="_blank">%{url}</a>.' % {
+          url: url.end_with?('.') ? uri : "#{uri}."
+        }
+      else
+        url
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: uc3-citation
+version: !ruby/object:Gem::Version
+  version: 0.0.5
+platform: ruby
+authors:
+- Brian Riley
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bibtex-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: citeproc-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: csl-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+description: Send this service a DOI and receive back a citation
+email:
+- brian.riley@ucop.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/uc3-citation.rb
+- lib/uc3-citation/version.rb
+homepage: https://github.com/CDLUC3/uc3-citation
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: UC3 - Citation Service
+test_files: []