Module: BokChoy

Extended by:
Configuration
Defined in:
lib/bok_choy.rb,
lib/bok_choy/error.rb,
lib/bok_choy/request.rb,
lib/bok_choy/version.rb

Overview

The BokChoy module provides a Ruby interface to the BHL Names API

Defined Under Namespace

Classes: BadGateway, BadRequest, Error, GatewayTimeout, InternalServerError, NotFound, Request, ServiceUnavailable

Constant Summary collapse

VERSION = 
"0.0.3"

Class Method Summary collapse

Methods included from Configuration

configuration, define_setting

Class Method Details

.cached_refs(id, verbose: false) ⇒ Hash

Finds a nomenclatural event in BHL by an external ID from a data source

Parameters:

  • id (String) —

    An external ID from a data source

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A result hash



46
47
48
49
50
51
 
# File 'lib/bok_choy.rb', line 46

def self.cached_refs(id, verbose: false)
  raise "ID required" if id.nil?

  endpoint = "cached_refs/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.items(id, verbose: false) ⇒ Hash

Get metadata and taxonomic statistics for a BHL item

Parameters:

  • id (String) —

    A BHL item ID

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A result hash



59
60
61
62
63
64
 
# File 'lib/bok_choy.rb', line 59

def self.items(id, verbose: false)
  raise "ID required" if id.nil?

  endpoint = "items/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.name_refs(name: nil, author: nil, year: nil, reference: nil, nomen_event: true, json: nil, verbose: false) ⇒ Hash

Finds BHL references for a name

Parameters:

  • name (String) (defaults to: nil) —

    A canonical scientific name (e.g., Pardosa moesta)

  • author (String, nil) (defaults to: nil) —

    An author string (e.g., Banks)

  • year (String, nil) (defaults to: nil) —

    A year string (e.g., 1892)

  • reference (String, nil) (defaults to: nil) —

    A reference string (e.g., Docums Mycol. 34(nos 135-136))

  • nomen_event (Boolean, nil) (defaults to: true) —

    If true, tries to find nomenclatural event reference (default: true)

  • json (Hash, nil) (defaults to: nil) —

    An optional JSON hash of name and reference data (overrides all other parameters)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A result hash



25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/bok_choy.rb', line 25

def self.name_refs(name: nil, author: nil, year: nil, reference: nil, nomen_event: true, json: nil, verbose: false)
  raise "Name or json required" if name.nil? && json.nil?

  if json.nil?
    json = {'name': {}, 'reference': {}, 'params': {}}
    json[:name][:nameString] = name
    json[:name][:author] = author unless author.nil?
    json[:name][:year] = year unless year.nil?
    json[:reference][:refString] = reference unless reference.nil?
    json[:params][:nomenEvent] = nomen_event
  end
  endpoint = "name_refs"
  Request.new(endpoint: endpoint, json: json, verbose: verbose).perform
end

.page(id, verbose: false) ⇒ Hash, ...

Get BHL reference metadata by page ID

Parameters:

  • id (String) —

    A page ID from BHL

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, String, Boolean) —

    A JSON-LD hash or CSV



72
73
74
75
76
77
 
# File 'lib/bok_choy.rb', line 72

def self.page(id, verbose: false)
  raise "ID required" if id.nil?

  endpoint = "references/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.ping(verbose: false) ⇒ String

Check the API status

Parameters:

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (String) —

    A pong string



111
112
113
114
115
116
117
 
# File 'lib/bok_choy.rb', line 111

def self.ping(verbose: false)
  endpoint = "ping"
  Request.new(
    endpoint: endpoint,
    verbose: verbose
  ).perform
end

.references(id, verbose: false) ⇒ Hash

Gets BHL reference metadata by page ID

Parameters:

  • id (String) —

    A page ID from BHL

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A result hash



99
100
101
102
103
104
 
# File 'lib/bok_choy.rb', line 99

def self.references(id, verbose: false)
  raise "ID required" if id.nil?

  endpoint = "references/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.taxon_items(taxon_name: nil, verbose: false) ⇒ Hash

Finds BHL items in which a given higher taxon is prevalent

Parameters:

  • taxon_name (String) (defaults to: nil) —

    A taxonomic name (e.g., Lepidoptera)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A result hash



85
86
87
88
89
90
91
 
# File 'lib/bok_choy.rb', line 85

def self.taxon_items(taxon_name: nil, verbose: false)
  raise "Taxon name required" if taxon_name.nil?

  taxon_url = ERB::Util.url_encode(taxon_name)
  endpoint = "taxon_items/#{taxon_url}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.version(verbose: false) ⇒ Hash

Check the API version

Parameters:

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A version hash



124
125
126
127
128
129
130
 
# File 'lib/bok_choy.rb', line 124

def self.version(verbose: false)
  endpoint = "version"
  Request.new(
    endpoint: endpoint,
    verbose: verbose
  ).perform
end