serrano 0.5.0 → 1.0.0

data/lib/serrano.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+require "erb"
 require "serrano/version"
 require "serrano/request"
 require "serrano/request_cursor"
@@ -6,8 +9,8 @@ require "serrano/cnrequest"
 require "serrano/filters"
 require "serrano/styles"
 
-require 'rexml/document'
-require 'rexml/xpath'
+require "rexml/document"
+require "rexml/xpath"
 
 # @!macro serrano_params
 #   @param offset [Fixnum] Number of record to start at, any non-negative integer up to 10,000
@@ -19,10 +22,10 @@ require 'rexml/xpath'
 #   @param sort [String] Field to sort on, one of score, relevance,
 #       updated (date of most recent change to metadata - currently the same as deposited),
 #       deposited (time of most recent deposit), indexed (time of most recent index),
-#       published (publication date), published-print (print publication date), 
-#       published-online (online publication date), issued (issued date (earliest known publication date)), 
-#       is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or 
-#       references-count (number of references included in the references section of the document 
+#       published (publication date), published-print (print publication date),
+#       published-online (online publication date), issued (issued date (earliest known publication date)),
+#       is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or
+#       references-count (number of references included in the references section of the document
 #       identified by this DOI). Note: If the API call includes a query, then the sort
 #       order will be by the relevance score. If no query is included, then the sort order
 #       will be by DOI update date.
@@ -32,7 +35,7 @@ require 'rexml/xpath'
 #   @param select [String/Array(String)] Crossref metadata records can be
 #       quite large. Sometimes you just want a few elements from the schema. You can "select"
 #       a subset of elements to return. This can make your API calls much more efficient. Not
-#       clear yet which fields are allowed here. 
+#       clear yet which fields are allowed here.
 #   @param verbose [Boolean] Print request headers to stdout. Default: false
 
 # @!macro cursor_params
@@ -60,11 +63,10 @@ require 'rexml/xpath'
 #     - oauth [Hash] A hash with OAuth details
 
 # @!macro field_queries
-#   @param [Hash<Object>] args Field queries, as named parameters. See 
+#   @param [Hash<Object>] args Field queries, as named parameters. See
 #       https://github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#field-queries
 #       Field query parameters mut be named, and must start with `query_`. Any dashes or
 #       periods should be replaced with underscores. The options include:
-#       - query_title: Query title and subtitle
 #       - query_container_title: Query container-title aka. publication name
 #       - query_author: Query author given and family names
 #       - query_editor: Query editor given and family names
@@ -108,7 +110,7 @@ require 'rexml/xpath'
 # searching full text, or even abstracts of articles, but only what is
 # available in the data that is returned to you. That is, they search
 # article titles, authors, etc. For some discussion on this, see
-# https://github.com/CrossRef/rest-api-doc/issues/101
+# https://gitlab.com/crossref/issues/issues/101
 #
 #
 # The Polite Pool
@@ -119,13 +121,13 @@ require 'rexml/xpath'
 # information, then they will send you to a separate pool of machines,
 # with better control the performance of these machines because they can
 # block abusive users.
-# 
+#
 # We have been using `https` in `serrano` for a while now, so that's good
 # to go. To get into the Polite Pool, also set your `mailto` email address
 # with `Serrano.configuration` (example below), or set as an environment
 # variable with the name `CROSSREF_EMAIL` and your mailto will be set
-# for each request automatically. 
-# 
+# for each request automatically.
+#
 # require 'serrano'
 # Serrano.configuration do |config|
 #   config.mailto = "foo@bar.com"
@@ -138,6 +140,12 @@ require 'rexml/xpath'
 # limit is 50 requests per second. Look for the headers `X-Rate-Limit-Limit`
 # and `X-Rate-Limit-Interval` in requests to see what the current rate
 # limits are.
+#
+#
+# URL Encoding
+# We do URL encoding of DOIs for you for all methods except `Serrano.citation_count`
+# which doesn't work if you encode DOIs beforehand. We use `ERB::Util.url_encode`
+# to encode.
 
 module Serrano
   extend Configuration
@@ -193,7 +201,7 @@ module Serrano
   #
   #      # sample
   #      Serrano.works(sample: 2)
-  #  
+  #
   #      # select - pass an array or a comma separated string
   #      Serrano.works(query: "ecology", select: "DOI,title", limit: 30)
   #      Serrano.works(query: "ecology", select: ["DOI","title"], limit: 30)
@@ -222,10 +230,11 @@ module Serrano
   #      Serrano.works(select: ['DOI', 'title'], limit: 3)
   def self.works(ids: nil, query: nil, filter: nil, offset: nil,
     limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    select: nil, options: nil, verbose: false, cursor: nil, 
+    select: nil, options: nil, verbose: false, cursor: nil,
     cursor_max: 5000, **args)
 
-    RequestCursor.new('works', ids, query, filter, offset,
+    assert_valid_filters(filter) if filter
+    RequestCursor.new("works", ids, query, filter, offset,
       limit, sample, sort, order, facet, select, nil, nil, options,
       verbose, cursor, cursor_max, args).perform
   end
@@ -281,8 +290,9 @@ module Serrano
     select: nil, works: false, options: nil, verbose: false,
     cursor: nil, cursor_max: 5000, **args)
 
-    RequestCursor.new('members', ids, query, filter, offset,
-      limit, sample, sort, order, facet, select, works, nil, 
+    assert_valid_filters(filter) if filter
+    RequestCursor.new("members", ids, query, filter, offset,
+      limit, sample, sort, order, facet, select, works, nil,
       options, verbose, cursor, cursor_max, args).perform
   end
 
@@ -317,19 +327,20 @@ module Serrano
   #      items.collect{ |z| z['DOI'] }[0,50]
   #
   #      # field queries
-  #      ## query.title
-  #      res = Serrano.prefixes(ids: "10.1016", works: true, query_title: 'cell biology')
+  #      ## query.bibliographic
+  #      res = Serrano.prefixes(ids: "10.1016", works: true, query_bibliographic: 'cell biology')
   #      res[0]['message']['items'].collect { |x| x['title'] }
   #
   #      # select certain fields
-  #      Serrano.prefixes(ids: "10.1016", works: true, select: ['DOI', 'title'], limit: 3) 
+  #      Serrano.prefixes(ids: "10.1016", works: true, select: ['DOI', 'title'], limit: 3)
   def self.prefixes(ids:, filter: nil, offset: nil,
     limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
     select: nil, works: false, options: nil, verbose: false,
     cursor: nil, cursor_max: 5000, **args)
 
-    RequestCursor.new('prefixes', ids, nil, filter, offset,
-      limit, sample, sort, order, facet, select, works, nil, 
+    assert_valid_filters(filter) if filter
+    RequestCursor.new("prefixes", ids, nil, filter, offset,
+      limit, sample, sort, order, facet, select, works, nil,
       options, verbose, cursor, cursor_max, args).perform
   end
 
@@ -374,13 +385,14 @@ module Serrano
   #      res[0]['message']['items'].collect { |x| x['author'][0]['family'] }
   #
   #      # select certain fields
-  #      Serrano.funders(ids: "10.13039/100000001", works: true, select: ['DOI', 'title'], limit: 3) 
+  #      Serrano.funders(ids: "10.13039/100000001", works: true, select: ['DOI', 'title'], limit: 3)
   def self.funders(ids: nil, query: nil, filter: nil, offset: nil,
     limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
     select: nil, works: false, options: nil, verbose: false,
     cursor: nil, cursor_max: 5000, **args)
 
-    RequestCursor.new('funders', ids, query, filter, offset,
+    assert_valid_filters(filter) if filter
+    RequestCursor.new("funders", ids, query, filter, offset,
       limit, sample, sort, order, facet, select, works, nil, options,
       verbose, cursor, cursor_max, args).perform
   end
@@ -426,13 +438,14 @@ module Serrano
   #      res[0]['message']['items'].collect { |x| x['container-title'] }
   #
   #      # select certain fields
-  #      Serrano.journals(ids: "2167-8359", works: true, select: ['DOI', 'title'], limit: 3) 
+  #      Serrano.journals(ids: "2167-8359", works: true, select: ['DOI', 'title'], limit: 3)
   def self.journals(ids: nil, query: nil, filter: nil, offset: nil,
     limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
     select: nil, works: false, options: nil, verbose: false,
     cursor: nil, cursor_max: 5000, **args)
 
-    RequestCursor.new('journals', ids, query, filter, offset,
+    assert_valid_filters(filter) if filter
+    RequestCursor.new("journals", ids, query, filter, offset,
       limit, sample, sort, order, facet, select, works, nil, options,
       verbose, cursor, cursor_max, args).perform
   end
@@ -448,7 +461,7 @@ module Serrano
   # @param select [String/Array(String)] Crossref metadata records can be
   #     quite large. Sometimes you just want a few elements from the schema. You can "select"
   #     a subset of elements to return. This can make your API calls much more efficient. Not
-  #     clear yet which fields are allowed here. 
+  #     clear yet which fields are allowed here.
   # @return [Array] An array of hashes
   #
   # @example
@@ -470,11 +483,11 @@ module Serrano
   #      res[0]['message']['items'].collect { |x| x['container-title'] }
   #
   #      # select certain fields
-  #      Serrano.types(ids: "journal", works: true, select: ['DOI', 'title'], limit: 3) 
+  #      Serrano.types(ids: "journal", works: true, select: ['DOI', 'title'], limit: 3)
   def self.types(ids: nil, offset: nil, limit: nil, select: nil, works: false,
     options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args)
 
-    RequestCursor.new('types', ids, nil, nil, offset,
+    RequestCursor.new("types", ids, nil, nil, offset,
       limit, nil, nil, nil, nil, select, works, nil, options,
       verbose, cursor, cursor_max, args).perform
   end
@@ -482,9 +495,28 @@ module Serrano
   ##
   # Search the licenses route
   #
-  # @!macro serrano_params
   # @!macro serrano_options
   # @param query [String] A query string
+  # @param offset [Fixnum] Number of record to start at, any non-negative integer up to 10,000
+  # @param limit [Fixnum] Number of results to return. Not relavant when searching with specific dois.
+  #       Default: 20. Max: 1000
+  # @param sample [Fixnum] Number of random results to return. when you use the sample parameter,
+  #       the limit and offset parameters are ignored. This parameter only used when works requested.
+  #       Max: 100.
+  # @param sort [String] Field to sort on, one of score, relevance,
+  #       updated (date of most recent change to metadata - currently the same as deposited),
+  #       deposited (time of most recent deposit), indexed (time of most recent index),
+  #       published (publication date), published-print (print publication date),
+  #       published-online (online publication date), issued (issued date (earliest known publication date)),
+  #       is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or
+  #       references-count (number of references included in the references section of the document
+  #       identified by this DOI). Note: If the API call includes a query, then the sort
+  #       order will be by the relevance score. If no query is included, then the sort order
+  #       will be by DOI update date.
+  # @param order [String] Sort order, one of 'asc' or 'desc'
+  # @param facet [Boolean/String] Include facet results OR a query (e.g., `license:*`) to facet by
+  #       license. Default: false
+  # @param verbose [Boolean] Print request headers to stdout. Default: false
   # @return [Array] An array of hashes
   #
   # @example
@@ -496,7 +528,7 @@ module Serrano
     limit: nil, sample: nil, sort: nil, order: nil,
     facet: nil, options: nil, verbose: false)
 
-    Request.new('licenses', nil, query, nil, offset,
+    Request.new("licenses", nil, query, nil, offset,
       limit, sample, sort, order, facet, nil, nil, nil, options, verbose).perform
   end
 
@@ -512,9 +544,8 @@ module Serrano
   #      Serrano.registration_agency(ids: '10.1371/journal.pone.0033693')
   #      Serrano.registration_agency(ids: ['10.1007/12080.1874-1746','10.1007/10452.1573-5125', '10.1111/(issn)1442-9993'])
   def self.registration_agency(ids:, options: nil, verbose: false)
-
-    Request.new('works', ids, nil, nil, nil,
-      nil, nil, nil, nil, nil, false, true, options, verbose).perform
+    Request.new("works", ids, nil, nil, nil,
+      nil, nil, nil, nil, nil, nil, false, true, options, verbose).perform
   end
 
   ##
@@ -535,10 +566,9 @@ module Serrano
   #      Serrano.random_dois(sample: 10)
   #      Serrano.random_dois(sample: 100)
   def self.random_dois(sample: 10, options: nil, verbose: false)
-
-    tmp = Request.new('works', nil, nil, nil, nil,
+    tmp = Request.new("works", nil, nil, nil, nil,
       nil, sample, nil, nil, nil, nil, false, nil, options, verbose).perform
-    tmp['message']['items'].collect { |x| x['DOI'] }
+    tmp["message"]["items"].collect { |x| x["DOI"] }
   end
 
   ##
@@ -564,7 +594,7 @@ module Serrano
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "crossref-xml")
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text")
   #
-  #     # return an R bibentry type
+  #     # return a bibentry type
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "bibentry")
   #     Serrano.content_negotiation(ids: "10.6084/m9.figshare.97218", format: "bibentry")
   #
@@ -577,30 +607,32 @@ module Serrano
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "oikos")
   #
   #     # example with many DOIs
-  #     dois = cr_r(2)
-  #     Serrano.content_negotiation(dois, format: "text", style: "apa")
+  #     dois = Serrano.random_dois(sample: 2)
+  #     Serrano.content_negotiation(ids: dois, format: "text", style: "apa")
   #
   #     # Using DataCite DOIs
-  #     ## some formats don't work
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "text")
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-xml")
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-tdm")
+  #     doi = "10.1126/science.169.3946.635"
+  #     Serrano.content_negotiation(ids: doi, format: "text")
+  #     Serrano.content_negotiation(ids: doi, format: "crossref-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "crossref-tdm")
   #
   #     ## But most do work
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "datacite-xml")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "rdf-xml")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "turtle")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "citeproc-json")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "ris")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibtex")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibentry")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibtex")
+  #     Serrano.content_negotiation(ids: doi, format: "datacite-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "rdf-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "turtle")
+  #     Serrano.content_negotiation(ids: doi, format: "citeproc-json")
+  #     Serrano.content_negotiation(ids: doi, format: "ris")
+  #     Serrano.content_negotiation(ids: doi, format: "bibtex")
+  #     Serrano.content_negotiation(ids: doi, format: "bibentry")
+  #     Serrano.content_negotiation(ids: doi, format: "bibtex")
   #
   #     # many DOIs
-  #     dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503', '10.5167/UZH-38402','10.5167/UZH-41217']
+  #     dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503',
+  #      '10.5167/UZH-38402','10.5167/UZH-41217']
   #     x = Serrano.content_negotiation(ids: dois)
   #     puts x
-  def self.content_negotiation(ids:, format: "bibtex", style: 'apa', locale: "en-US")
+  def self.content_negotiation(ids:, format: "bibtex", style: "apa", locale: "en-US")
+    ids = Array(ids).map { |x| ERB::Util.url_encode(x) }
     CNRequest.new(ids, format, style, locale).perform
   end
 
@@ -619,17 +651,16 @@ module Serrano
   #   Serrano.citation_count(doi: "10.1016/j.fbr.2012.01.001")
   #   # DOI not found
   #   Serrano.citation_count(doi: "10.1016/j.fbr.2012")
-  def self.citation_count(doi:, url: "http://www.crossref.org/openurl/",
+  def self.citation_count(doi:, url: "https://www.crossref.org/openurl/",
     key: "cboettig@ropensci.org", options: nil)
 
-    args = { id: "doi:" + doi, pid: key, noredirect: true }
-    opts = args.delete_if { |k, v| v.nil? }
-    conn = Faraday.new(:url => url, :request => options)
-    res = conn.get '', opts
+    args = {id: "doi:" + doi, pid: key, noredirect: true}
+    opts = args.delete_if { |_k, v| v.nil? }
+    conn = Faraday.new(url: url, request: options)
+    res = conn.get "", opts
     x = res.body
     oc = REXML::Document.new("<doc>#{x}</doc>")
-    value = REXML::XPath.first(oc, '//query').attributes['fl_count'].to_i
-    return value
+    REXML::XPath.first(oc, "//query").attributes["fl_count"].to_i
   end
 
   # Get csl styles
@@ -639,7 +670,25 @@ module Serrano
   # @example
   #   Serrano.csl_styles
   def self.csl_styles
-    get_styles()
+    fetch_styles
   end
 
+  def self.assert_valid_filters(filters)
+    unless filters.is_a? Hash
+      raise ArgumentError, <<~ERR
+        Filters must be provided as a hash, like:
+
+            Serrano.works(query: "something", filters: { has_abstract: true })
+      ERR
+    end
+
+    filters.each do |name, _|
+      filter_strings = Filters.names.map(&:to_s)
+      next if filter_strings.include?(name.to_s)
+
+      raise ArgumentError, <<~ERR
+        The filter "#{name}" is not a valid filter. Please run `Serrano.filters.filters` to see all valid filters.
+      ERR
+    end
+  end
 end

data/lib/serrano/cn.rb

@@ -1,14 +1,14 @@
+# frozen_string_literal: true
+
 require "serrano/version"
 require "serrano/cnrequest"
 
 ##
 # ContentNegotiation - Content Negotiation class
 #
-# @see http://www.crosscite.org/cn/ for details
+# @see https://citation.crosscite.org/docs.html for details
 module Serrano
-
   class ContentNegotiation
-
     attr_accessor :ids
     attr_accessor :format
     attr_accessor :style
@@ -22,9 +22,7 @@ module Serrano
     end
 
     def cn
-      CNRequest.new(self.ids, self.format, self.style, self.locale).perform
+      CNRequest.new(ids, format, style, locale).perform
     end
-
   end
-
 end

data/lib/serrano/cnrequest.rb

@@ -1,10 +1,22 @@
+# frozen_string_literal: true
+
 require "faraday"
 require "faraday_middleware"
 require "multi_json"
 require "serrano/error"
-require "serrano/constants"
-require 'serrano/utils'
-require 'serrano/helpers/configuration'
+require "serrano/utils"
+require "serrano/helpers/configuration"
+
+CN_FORMAT_HEADERS = {"rdf-xml" => "application/rdf+xml",
+                     "turtle" => "text/turtle",
+                     "citeproc-json" => "transform/application/vnd.citationstyles.csl+json",
+                     "text" => "text/x-bibliography",
+                     "ris" => "application/x-research-info-systems",
+                     "bibtex" => "application/x-bibtex",
+                     "crossref-xml" => "application/vnd.crossref.unixref+xml",
+                     "datacite-xml" => "application/vnd.datacite.datacite+xml",
+                     "bibentry" => "application/x-bibtex",
+                     "crossref-tdm" => "application/vnd.crossref.unixsd+xml"}.freeze
 
 ##
 # Serrano::CNRequest
@@ -12,12 +24,16 @@ require 'serrano/helpers/configuration'
 # Class to perform HTTP requests to the Crossref API
 module Serrano
   class CNRequest #:nodoc:
-
     attr_accessor :ids
     attr_accessor :format
     attr_accessor :style
     attr_accessor :locale
 
+    CN_FORMATS = %w[rdf-xml turtle citeproc-json
+      citeproc-json-ish text ris bibtex
+      crossref-xml datacite-xml bibentry
+      crossref-tdm].freeze
+
     def initialize(ids, format, style, locale)
       self.ids = ids
       self.format = format
@@ -26,37 +42,35 @@ module Serrano
     end
 
     def perform
-      if !$cn_formats.include? self.format
+      unless CN_FORMATS.include? format
         raise "format not one of accepted types"
       end
 
-      $conn = Faraday.new "https://doi.org/" do |c|
+      conn = Faraday.new "https://doi.org/" do |c|
         c.use FaradayMiddleware::FollowRedirects
         c.adapter :net_http
       end
 
-      if self.ids.length == 1
-        if self.ids.class == Array
-          self.ids = self.ids[0]
-        end
-        return make_request(self.ids, self.format, self.style, self.locale)
+      if ids.length == 1
+        self.ids = ids[0] if ids.class == Array
+        make_request(conn, ids, format, style, locale)
       else
         coll = []
-        Array(self.ids).each do |x|
-          coll << make_request(x, self.format, self.style, self.locale)
+        Array(ids).each do |x|
+          coll << make_request(conn, x, format, style, locale)
         end
-        return coll
+        coll
       end
     end
   end
 end
 
-def make_request(ids, format, style, locale)
-  type = $cn_format_headers.select { |x, _| x.include? format }.values[0]
+def make_request(conn, ids, format, style, locale)
+  type = CN_FORMAT_HEADERS.select { |x, _| x.include? format }.values[0]
 
   if format == "citeproc-json"
-    endpt = "http://api.crossref.org/works/" + ids + "/" + type
-    cr_works = Faraday.new(:url => endpt)
+    endpt = "https://api.crossref.org/works/" + ids + "/" + type
+    cr_works = Faraday.new(url: endpt)
     cr_works.headers[:user_agent] = make_ua
     cr_works.headers["X-USER-AGENT"] = make_ua
     res = cr_works.get
@@ -65,15 +79,15 @@ def make_request(ids, format, style, locale)
       type = type + "; style = " + style + "; locale = " + locale
     end
 
-    res = $conn.get do |req|
+    res = conn.get { |req|
       req.url ids
-      req.headers['Accept'] = type
+      req.headers["Accept"] = type
       req.headers[:user_agent] = make_ua
       req.headers["X-USER-AGENT"] = make_ua
-    end
+    }
   end
 
-  return res.body
+  res.body
 end
 
 # parser <- cn_types[[self.format]]