rubyBHL 0.1.0 → 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4fe4ab96d43bf545970f210e8206eade90e44ae1
+  data.tar.gz: fad6f419ccccf43eed88fbb6161194fa40f84f17
+SHA512:
+  metadata.gz: 1d7c31281e01a8bd1c1dcf7ffc3b7c8d1d0ec7633302a0b58fccf40e85ef06abf5790694d55c54a0daac9162c40874039f43b29df33a8e72e941bd30536206d2
+  data.tar.gz: 5c7a705dd079fb25288b2fdf46ae70ecdebe295150ef15cc1cebdf5844e40a2ee78f4fe8176c3a5890965f80c9610180683952befd2c44c71ddd3bfe10e6be52

data/.env

@@ -0,0 +1 @@
+BHL_API_KEY=sekret_key_here

data/.gitignore

@@ -0,0 +1,7 @@
+pkg
+doc
+Manifest
+*~
+*.swp
+.bhl_api_key
+.bundle

data/.rspec

@@ -0,0 +1,2 @@
+--format nested
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p353

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    rubyBHL (0.2.1)
+      dotenv
+      json (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    awesome_print (1.2.0)
+    columnize (0.3.6)
+    debugger (1.6.5)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.3.1)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.3.1)
+    diff-lcs (1.2.5)
+    dotenv (0.9.0)
+    git (1.2.6)
+    json (1.8.1)
+    rake (10.1.1)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print (~> 1.2)
+  bundler (~> 1.3)
+  debugger (~> 1.6)
+  dotenv
+  git (~> 1.2)
+  rake (~> 10.1)
+  rspec (~> 2.14)
+  rubyBHL!

data/LICENSE

@@ -0,0 +1,16 @@
+University of Illinois/NCSA Open Source License
+
+Copyright (c) 2014 Species File Group 
+All rights reserved.
+
+Developed by: 		Species File Group
+                  Illinois Natural History Survey 
+                  http://speciesfilegroup.blogspot.com/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal with the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+    Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers.
+    Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimers in the documentation and/or other materials provided with the distribution.
+    Neither the names of <Name of Development Group, Name of Institution>, nor the names of its contributors may be used to endorse or promote products derived from this Software without specific prior written permission. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. 

data/README.rdoc

@@ -1,16 +1,129 @@
 = RubyBHL
 
-A very simple Ruby hook to the BHL.
+A simple Ruby wrapper to {version 2.5.x of the BHL API}[http://www.biodiversitylibrary.org/api2/docs/docs.html]. 
 
-== Install 
+== Really quick start 
 
-  gem install mjy-RubyBHL --source http://gems.github.com
+Add your key (http://www.biodiversitylibrary.org/getapikey.aspx) to <em>~/.bhl_api_key</em>.
 
-== Usage
+  gem install rubyBHL
 
-See tests.
+  require 'rubyBHL'
+  RubyBHL.quick_request() # => {"Status":"ok","ErrorMessage":null,"Result":[]}
 
-== Todo
+== API Key
 
-Lots.
+You need a BHL key from http://www.biodiversitylibrary.org/getapikey.aspx. Do one of: 
+
+1) Add it to the file <em>~/.bhl_api_key</em>. 
+
+2) Add it to the file _.env_ in the root of your application: 
+  BHL_API_KEY=sekret_key_here
+
+3) Set BHL_API_KEY in your shell profile.
+
+4) Pass it explicitly to your request:
+   RubyBHL::Request.new(api_key: '123_343_etc')  
+
+If the key is set in multiple places priority is reverse order listed here.
+
+== Requests
+
+Construct one all at once:
+
+  r = RubyBHL::Request.new(method: :TitleSearch, params: {'title' => 'Dark and Storm Night'}, format: 'xml', api_key: 'top_sekret_key')
+
+Build it piece by piece if you need to
+
+  r = RubyBHL::Request.new()   # => #<RubyBHL::Request:0x0000010189bf28
+                                      @api_key="redacted_secret_key", 
+                                      @method=:NameSearch, @format="json", @params={}>  
+
+The method defaults to :NameSearch
+
+  r.method                           #  => :NameSearch 
+  r.method = :TitleSearchSimple      #  => :TitleSearchSimple
+
+Parameters are passed as a hash, keys are strings:
+
+  r.params = {'title' => 'Hen in the Foxhouse.'}   # => {"title"=>"Hen in the Foxhouse."} 
+
+Format is one of `xml` or `json` (default):
+
+  r.format = 'xml'                   # => "xml"
+
+It's possible to set your API key per request: 
+
+  r.api_key = 'top_sekret_key'       #  => "top_sekret_key" 
+
+Test that your params are supported:
+
+  r.params = {'foo' => 'bar'}        #  => {"foo"=>"bar"} 
+  r.params_are_supported?            # => false
+
+Test that method has the required params?
+
+  r.params = {}                      # => {} 
+  r.method = :NameSearch             # => :NameSearch 
+  r.has_required_params?             # false => false
+  r.params = {'name' => "Yeti"}      # => {"name"=>"Yeti"} 
+  r.has_required_params?             # => true 
+
+Test the overall validity of the present request:
+
+  r.valid?   # => true
+
+Return the search_url: 
+
+  r.search_url   # => "http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameSearch&name=Yeti&format=xml&apikey=top_sekret_key"
+
+Get a response
+
+ r.response      # =>  #<RubyBHL::Response: ... >
+
+== Responses
+
+Require a RubyBHL::Request:
+
+  request = RubyBHL::Request.new(params: {'name' => 'blorf'})
+  response = RubyBHL::Response.new(request: request)
+
+Get the json:
+
+  response.json  # => {"Status"=>"ok", "ErrorMessage"=>nil, "Result"=>[]}
+
+== Mining 
+
+Just some examples at present.
+
+For a taxon name, and a list of "attributes", generate a CSV table with one page per row, and 0 (absent) or 1 (present) for each "attribute".  You can limit the number of pages returned.
+
+  require 'rubyBHL'
+  r = RubyBHL::Mine.taxon_attribute_table('Apis melifera', ['honey', 'disease', 'parasite'], 5)   
+  # => "honey\tdisease\tparasite\tPageID\n0\t0\t0\t15995011\n0\t0\t0\t16445239\n0\t0\t0\t27274823\n0\t0\t0\t18188723\n0\t0\t0\t37765472\n1\t0\t0\t34216230\n1\t0\t1\t31898980\n0\t0\t1\t32014594\n0\t0\t0\t32014638\n1\t1\t0\t32015159\n"  
+  CSV.parse(r, col_sep: "\t")
+   # => [["honey", "disease", "parasite", "PageID"],
+        ["0", "0", "0", "15995011"], 
+        ["0", "0", "0", "16445239"],
+        ["0", "0", "0", "27274823"],
+        ["0", "0", "0", "18188723"],
+        ["0", "0", "0", "37765472"],
+        ["1", "0", "0", "34216230"],
+        ["1", "0", "1", "31898980"],
+        ["0", "0", "1", "32014594"],
+        ["0", "0", "0", "32014638"],
+        ["1", "1", "0", "32015159"]]
+   # ... <clickity> R-stats </clickity>  
+
+== Contributing
+
+Fork the repo, hack, test, submit a pull request.
+
+== Acknowledgements
+
+Katja Seltmann provided code and requirements for the original incarnation of the gem.  The general pattern for this gem, including some baseline tests, is pilfered from dwc-archive by Dmitry Mozzherin. Mx A. Matienzo (@anarchivist) wrote a {Python translation of the original version}[http://www.biodiversitylibrary.org/api2/docs/docs.html], and inspired the different architecture used now.  Thanks BHL for being awesome!
+
+== License
+
+Open, NCSA[http://opensource.org/licenses/NCSA]. See LICENSE.
 

data/Rakefile

@@ -1,18 +1,9 @@
-# follows Bate's screencast 135
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
 
-require 'rubygems'
-require 'rake'
-require 'echoe'
-
-Echoe.new('rubyBHL', '0.1.0') do |p|
-  p.description = "Hook to the Biodiversity Heritage Library API plus some screen scraping for OCR."
-  p.url = "http://github.com/mjy/rubyBHL"
-  p.author = "Yoder & Seltmann"
-  p.email = "diapriid@gmail.com"
-  p.ignore_pattern = ["tmp/*", "script/*"]
-  p.development_dependencies = []
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
 end
 
-Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each {|ext| load ext}
-
-  
+task :default => :spec
+   

data/lib/rubyBHL.rb

@@ -1,116 +1,28 @@
-module RubyBHL
-  
- # Some quick hacks, only configured for json right now.
-
- require 'net/http'
- # require 'json'
- require 'json/add/rails'
+# encoding: UTF-8
 
- class RbhlError < StandardError
- end
+recent_ruby = RUBY_VERSION >= '2.0.0'
+raise "IMPORTANT:  gem requires ruby >= 2.0.0" unless recent_ruby
 
- class Rbhl
-   
- # some notes   
- #http://www.biodiversitylibrary.org/openurl?url_ver=Z39.88-2004&ctx_ver=Z39.88-2004
- #rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Abook
- #rft.btitle
- #rft.jtitle
- #rft.au
- #rft.aufirst
- #rft.aulast
- #rft.publisher
- #rft.pub
- #rft.place
- #rft.date
- #rft.issn
- #rft.isbn
- # rft.coden
- # rft.stitle
- # rft.volume
- # rft.issue
- # rft.spage
- # rft_id=info:oclcnum/XXXX
- # rft_id=info:lccn/XXXX
- # rft_id=http://www.biodiversitylibrary.org/bibliography/XXXX
- # rft_id=http://www.biodiversitylibrary.org/page/XXXX
-  
-  # "constants" (defaults really)
-  SEARCH_URL =  'http://www.biodiversitylibrary.org/openurl?' 
-  FORMAT = 'json'
-  #  METHOD = '' # openURL0.1, openURL1.0 
+require "json"
+require 'net/http'
 
-  PARAMETERS = [
-                  :title,
-                  :au,
-                  :aufirst,
-                  :aulast,
-                  :publisher,
-                  :date,
-                  :issn,
-                  :isbn,
-                  :coden,
-                  :stitle,
-                  :volume,
-                  :issue,
-                  :spage]
-  
-  # created from response
-  attr_reader(:json_data)
-  attr_reader(:citations)
-  attr :search_url
+require_relative 'rubyBHL/request'
+require_relative 'rubyBHL/response'
+require_relative 'rubyBHL/mine'
 
- def initialize(options = {}) 
-   @opt = {
-    #  :method => METHOD,
-      :format => FORMAT,
-      :params => {}
-   }.merge!(options)
-   
-   # check for legal parameters
-   @opt[:params].keys.each do |p|
-      raise RbhlError, "#{p} is not a valid parameter" if !PARAMETERS.include?(p)
-   end 
-     
-   @json_data = {}
-     
-   @search_url = SEARCH_URL + 
-       @opt[:params].keys.sort{|a,b| a.to_s <=> b.to_s}.collect{|k| "#{k}=#{@opt[:params][k].gsub(/\s/, "+")}"}.join("&") +
-      '&format=' + @opt[:format]       
-       
-   @json_data = JSON.parse(Net::HTTP.get_response(URI.parse(@search_url)).body)
-   @citations = @json_data['citations'] if @json_data['Status'] == 1 # a simpler reference
-   
-   true
- end
+class RubyBHL
 
- # this works on a redirect
- def OCR_text(citation_index)
-   return nil if !citation_index
-   fetch(OCR_url(citation_index))
- end
- 
- # from the ruby doc
- def fetch(uri_string, limit = 10)
-   return nil if !uri_string
-   limit = 10 # Justin Case we get in some redirect loop
-   raise RbhlError, 'HTTP redirect too deep' if limit == 0 # should tweak
-   response = Net::HTTP.get_response(URI.parse(uri_string))
-   case response
-   when Net::HTTPSuccess then response.body
-   when Net::HTTPRedirection then fetch(response['location'], limit - 1)
-   else
-     response.error!
-    end
+  #DEFAULT_TMP_DIR = "/tmp"
+  
+  def self.quick_request(options = {})
+    opts = {
+      params: {'name' => 'blorf'},
+      method: :NameSearch
+    }.merge!(options)
+    request = RubyBHL::Request.new(opts)
+    request.response
   end
 
- # Since the API doesn't return a link to the OCR we screen scrape it the URL
- def OCR_url(citation_index)
-   Net::HTTP.get_response(URI.parse(@citations[citation_index]["Url"])).body =~ /http:\/\/.*?\.txt/
-   return $& # the matched results
- end
-
 end
 
 
-end

data/lib/rubyBHL/mine.rb

@@ -0,0 +1,48 @@
+class RubyBHL
+
+  require 'csv'
+
+  # Some rudimentary methods for mining the BHL.
+  class Mine 
+
+    # Takes a string, and a list of "attributes" (keyword). 
+    # Returns a CSV object with one line per page, 
+    # one column per attribute, 
+    # 1 if keyword was found, 0 if not.
+    def self.taxon_attribute_table(taxon_name = nil, attributes = [], page_limit = 10)
+      name_search = RubyBHL::Request.new(method: :NameGetDetail , params: {'name' => taxon_name}) 
+
+      json = name_search.response.json
+      pages = pages_from_result(json['Result'])
+
+      csv = CSV.generate(col_sep: "\t") do |csv|
+        csv << [*attributes, 'PageID']
+        pages[0..page_limit - 1].each do |p|
+          result = []
+          ocr = RubyBHL::Request.new(method: :GetPageOcrText, params: {'pageid' => p['PageID']}).response.json['Result']
+          result += bit_vector_for_keywords(ocr, attributes)
+          result.push p['PageID']
+          csv << [*result]
+        end
+      end
+      csv
+    end
+
+    # Return an Array of 0 or 1 given the presence or absence of each keyword in the text.
+    def self.bit_vector_for_keywords(text = "", keywords = [])
+      keywords.inject([]) {|ary, k| ary.push(text =~ /#{k}/ ? 1 : 0) }
+    end 
+
+    # TODO: Use JSON fu to make this simpler
+    def self.pages_from_result(results = [])
+      pages = []
+      results['Titles'].each do |t|
+        t['Items'].each do |i|
+          pages += i['Pages']
+        end
+      end
+      pages
+    end
+
+  end
+end

data/lib/rubyBHL/request.rb

@@ -0,0 +1,151 @@
+class RubyBHL
+
+  API_KEY_FILE_PATH = File.expand_path("~/.bhl_api_key")
+  key = nil
+  key = File.read(API_KEY_FILE_PATH).strip if File.exists?(API_KEY_FILE_PATH)
+  API_KEY_FILE = key 
+  API_KEY_ENV = ENV['BHL_API_KEY'] 
+
+  API_KEY = API_KEY_FILE || API_KEY_ENV || nil
+
+  warn "\n\n !! API key not set in ~/.bhl_api_key, .env, or ENV.  You must pass requests an :api_key. !! \n\n"  if API_KEY.nil? || API_KEY == 'sekret_key_here'
+
+  # Target API http://www.biodiversitylibrary.org/api2/docs/docs.html
+  class RubyBHL::Request
+    BASE_URL = 'http://www.biodiversitylibrary.org'
+    API_VERSION = 'api2'  
+    INTERFACE = 'httpquery.ashx?'
+    FORMAT = 'json'
+    SEARCH_BASE = [BASE_URL, API_VERSION, INTERFACE].join("/") 
+
+    METHODS = { 
+      AuthorSearch: %w{name},
+      BookSearch: %w{title lname volume edition year subject language collectionid}, 
+      GetAuthorParts: %w{creatorid}, 
+      GetAuthorTitles: %w{creatorid},  
+      GetCollections: %w{},        # no params
+      GetItemByIdentifier: %w{type value}, 
+      GetItemMetadata: %w{itemid pages oc parts}, 
+      GetItemPages: %w{itemid ocr}, 
+      GetItemParts: %w{itemid}, 
+      GetLanguages: %w{},          # no params
+      GetPageMetadata: %w{pageid ocr names}, 
+      GetPageNames: %w{pageid}, 
+      GetPageOcrText: %w{pageid}, 
+      GetPartBibTeX: %w{partid}, 
+      GetPartByIdentifier: %w{type value}, 
+      GetPartEndNote: %w{partid}, 
+      GetPartMetadata: %w{partid}, 
+      GetPartNames: %w{partid}, 
+      GetSubjectParts: %w{subject}, 
+      GetSubjectTitles: %w{subject}, 
+      GetTitleBibTex: %w{titleid}, 
+      GetTitleByIdentifier: %w{type value}, 
+      GetTitleEndNote: %w{titleid}, 
+      GetTitleItems: %w{titleid}, 
+      GetTitleMetadata: %w{titleid items}, 
+      GetUnpublishedItems: %w{},      # No params 
+      GetUnpublishedParts: %w{},      # No params 
+      GetUnpublishedTitles: %w{},     # No params 
+      NameCount: %w{startdate enddate}, 
+      NameGetDetail: %w{namebankid name},            # !! Not in list below part of V1, see || criteria
+      NameCountBetweenDates: %w{},                   # !! No documentation provided
+     # NameGetDetailForName: %w{},                   # !! No documentation provided, can't confirm it works
+     # NameGetDetailForNameBankID: %w{},             # !! No documentation provided, can't confirm it works
+      NameList: %w{startrow batchsize stardate enddate},   # part of V1 !! may be problems
+      NameListBetweenDates: %w{}, # !! No documentation provided 
+      NameSearch: %w{name},                                # part of V1 !! may be problems
+      PartSearch: %w{title containerTitle author date volume series issue}, 
+      SubjectSearch: %w{subject}, 
+      TitleSearchSimple: %w{title}, 
+    }
+
+    REQUIRED_PARAMS = {
+      'name' => [:AuthorSearch, :NameSearch],
+      'creatorid' => [:GetAuthorParts, :GetAuthorTitles],
+      'type' => [:GetItemByIdentifier, :GetPartByIdentifier, :GetTitleByIdentifier],
+      'value' => [:GetItemByIdentifier, :GetPartByIdentifier, :GetTitleByIdentifier],
+      'itemid' => [:GetItemMetadata, :GetItemPages, :GetItemParts],
+      'pageid' => [:GetPageMetadata, :GetPageNames, :GetPageOcrText, :GetPartBibTeX],
+      'partid'  => [:GetPartBibTeX, :GetPartEndNote, :GetPartMetadata, :GetPartNames],
+      'subject' => [:GetSubjectParts, :GetSubjectTitles, :SubjectSearch],
+      'titleid' => [:GetTitleBibTex, :GetTitleEndNote, :GetTitleItems, :GetTitleMetadata],
+      'title' => [:TitleSearchSimple] 
+    }
+
+    mrp = {}
+    REQUIRED_PARAMS.each do |k,v|
+      v.each do |m|
+        mrp[m].push(k) if mrp[m] 
+        mrp[m] ||= [k]
+      end
+    end
+
+    METHODS_REQUIRED_PARAMS = mrp
+
+    attr_accessor :params, :method, :format, :api_key
+    attr_reader :search_url
+
+    def initialize(options = {})
+      opts = {
+        api_key: RubyBHL::API_KEY,
+        format:  RubyBHL::Request::FORMAT,
+        method:  :NameSearch,
+        params: { }
+      }.merge!(options)
+
+      assign_options(opts)
+      build_url if valid?
+    end
+
+    def assign_options(opts)
+      @api_key = opts[:api_key]
+      @method = opts[:method]
+      @format = opts[:format]
+      @params = opts[:params]
+    end
+
+    def search_url
+      build_url
+      @search_url
+    end
+
+    def response
+      build_url
+      if valid?
+        Response.new(request: self)
+      else
+        false # raise?
+      end
+    end
+
+    def params_are_supported? 
+      return false if @method.nil?
+      return true if METHODS[@method] == []
+      @params.keys - METHODS[@method] == []
+    end
+
+    def has_required_params?
+      return false if @method.nil?
+      return true if METHODS_REQUIRED_PARAMS[@method].nil?
+      METHODS_REQUIRED_PARAMS[@method].select{|v| !@params.keys.include?(v)} == []
+    end
+
+    def valid?
+      raise API_KEY_MESSAGE if @api_key.nil?
+      raise "Method #{@method} not recognized." if @method && !RubyBHL::Request::METHODS.keys.include?(@method)
+      raise "Format #{@format} not recognized." if @format && !%w{json xml}.include?(@format)
+
+      !@method.nil? && !@format.nil? && params_are_supported? && has_required_params?
+    end
+
+    private 
+
+    def build_url
+      @search_url = SEARCH_BASE + 'op=' + @method.to_s +
+        @params.keys.sort{|a,b| a.to_s <=> b.to_s}.collect{|k| "&#{k}=#{@params[k].to_s.gsub(/\s/, "+")}"}.join +
+      '&format=' + @format + '&apikey=' + @api_key
+    end
+
+  end
+end

data/lib/rubyBHL/response.rb

@@ -0,0 +1,47 @@
+
+class RubyBHL
+
+  class Response
+    attr_reader :json
+
+    def initialize(options = {}) 
+      opts = {
+        request: nil 
+      }.merge!(options)
+
+      raise if opts[:request].nil? || opts[:request].class != RubyBHL::Request
+
+      @json = {}
+      @json = JSON.parse(Net::HTTP.get_response(URI.parse(opts[:request].search_url)).body)
+    end
+
+  end
+end
+
+
+# Crud from 0.1.0
+#   # # from the ruby doc
+  # def fetch(uri_string, limit = 10)
+  #   return nil if !uri_string
+  #   limit = 10 # Justin Case we get in some redirect loop
+  #   raise RbhlError, 'HTTP redirect too deep' if limit == 0 # should tweak
+  #   response = Net::HTTP.get_response(URI.parse(uri_string))
+  #   case response
+  #   when Net::HTTPSuccess then response.body
+  #   when Net::HTTPRedirection then fetch(response['location'], limit - 1)
+  #   else
+  #     response.error!
+  #   end
+  # end
+  # 
+  # # this works on a redirect
+  # def OCR_text(citation_index)
+  #   return nil if !citation_index
+  #   fetch(OCR_url(citation_index))
+  # end
+
+  # # Since the API doesn't return a link to the OCR we screen scrape the URL
+  # def OCR_url(citation_index)
+  #   Net::HTTP.get_response(URI.parse(@citations[citation_index]["Url"])).body =~ /http:\/\/.*?\.txt/
+  #   return $& # the matched results
+  # end

data/lib/rubyBHL/version.rb

@@ -0,0 +1,3 @@
+class RubyBHL 
+    VERSION = "0.2.1"
+end

data/rubyBHL.gemspec

@@ -1,31 +1,31 @@
-# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/rubyBHL/version', __FILE__)
 
-Gem::Specification.new do |s|
-  s.name = %q{rubyBHL}
-  s.version = "0.1.0"
+Gem::Specification.new do |gem|
+  gem.name = 'rubyBHL'
+  gem.version = RubyBHL::VERSION #"0.1.0
+  gem.authors = ["Matt Yoder"]
+  gem.email = %q{diapriid@gmail.com}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Yoder & Seltmann"]
-  s.date = %q{2009-10-19}
-  s.description = %q{Hook to the Biodiversity Heritage Library API plus some screen scraping for OCR.}
-  s.email = %q{diapriid@gmail.com}
-  s.extra_rdoc_files = ["README.rdoc", "lib/rubyBHL.rb"]
-  s.files = ["Manifest", "README.rdoc", "Rakefile", "init.rb", "lib/rubyBHL.rb", "test/helper.rb", "test/rubyBHL_test.rb", "rubyBHL.gemspec"]
-  s.homepage = %q{http://github.com/mjy/rubyBHL}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "rubyBHL", "--main", "README.rdoc"]
-  s.require_paths = ["lib"]
-  s.rubyforge_project = %q{rubybhl}
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Hook to the Biodiversity Heritage Library API plus some screen scraping for OCR.}
-  s.test_files = ["test/rubyBHL_test.rb"]
+  gem.description = %q{RubyBHL is a simple but flexible request/response wrapper for the Biodiversity Heritage Libary API.  It includes (some) validation for request formatting.  It has excellent unit-test coverage.}
+  gem.summary = %q{RubyBHL is a simple request/response wrapper for the Biodiversity Heritage Libary API.}
+  gem.homepage = 'http://github.com/SpeciesFileGroup/rubyBHL'
+  gem.license = "University of Illinois/NCSA Open Source License (NCSA)"
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  gem.files         = `git ls-files`.split($/) # be sure to commit!
+  gem.test_files =  gem.files.grep(%r{^(spec|features)/}) 
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '~> 2.0'
+
+  gem.add_runtime_dependency 'json', '~> 1.8'
+  gem.add_runtime_dependency 'dotenv'
+
+  gem.add_development_dependency 'rake', '~> 10.1'
+  gem.add_development_dependency 'bundler', '~> 1.3'
+  gem.add_development_dependency 'rspec', '~> 2.14'
+  gem.add_development_dependency 'debugger', '~> 1.6'
+  gem.add_development_dependency 'git', '~> 1.2'
+  gem.add_development_dependency 'dotenv'
+  gem.add_development_dependency 'awesome_print', '~> 1.2'
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
 end

data/spec/lib/mine_spec.rb

@@ -0,0 +1,24 @@
+require_relative '../spec_helper'
+describe RubyBHL::Mine do
+  subject { RubyBHL::Mine }
+ 
+  describe "`taxon_attribute_table`" do
+
+    it 'can be called with multiple attributes ' do
+      expect(RubyBHL::Mine.taxon_attribute_table('Apis melifera', ['honey', 'yellow', 'plant'], 3)).to be_true
+    end
+
+    it 'can be limited to a number of pages' do
+      t =  RubyBHL::Mine.taxon_attribute_table('Apis melifera', ['honey'], 5)
+      expect(CSV.parse(t, col_sep: "\t").count).to eq(6) 
+    end
+
+    it 'returns a CSV formatted text string (tab delimited)' do
+      t =  RubyBHL::Mine.taxon_attribute_table('Apis melifera', ['honey'], 1)
+      expect(t.class).to eq(String)
+      expect(CSV.parse(t, col_sep: "\t", headers: true)).to be_true
+    end
+  end
+
+
+end

data/spec/lib/request_spec.rb

@@ -0,0 +1,114 @@
+require_relative '../spec_helper'
+describe RubyBHL::Request do
+
+  subject { RubyBHL::Request }
+
+  describe 'instance' do
+    it 'has a default FORMAT' do
+      expect(RubyBHL::Request::FORMAT).to eq('json')
+    end
+
+    it 'uses API version 2' do
+      expect(RubyBHL::Request::API_VERSION).to eq('api2')
+    end
+
+    it 'uses the http interface' do
+      expect(RubyBHL::Request::INTERFACE).to eq('httpquery.ashx?')
+    end
+
+    it 'knows the API methods' do
+      expect(RubyBHL::Request::METHODS).to have(37).things
+    end
+
+    it 'has a base URL' do
+      expect(RubyBHL::Request::BASE_URL).to eq('http://www.biodiversitylibrary.org')
+    end
+
+    it 'has a SEARCH_BASE' do
+      expect(RubyBHL::Request::SEARCH_BASE).to eq('http://www.biodiversitylibrary.org/api2/httpquery.ashx?')
+    end
+
+
+    describe 'search_url' do
+      before(:each) {
+        @r = RubyBHL::Request.new()
+      }
+
+      it 'can validate that "foo" is not a supported param for :NameSearch `params_are_supported?`' do
+        @r.params = {'foo' => 'bar'}
+        expect(@r.params_are_supported?).to be_false
+      end
+
+      it 'can validate that "name" is a supported param for :NameSearch `params_are_supported?`' do
+        @r.params = {"name" => 'bar'}
+        expect(@r.params_are_supported?).to be_true
+      end
+
+      it 'can validate that required params are not present with `has_required_params?`' do
+        @r.params = {'foo' => 'bar'}
+        expect(@r.has_required_params?).to be_false
+      end
+
+      it 'can validate that required params are present with `has_required_params?`' do
+        @r.params = {'name' => 'bar'}
+        expect(@r.has_required_params?).to be_true
+      end
+
+      it 'can be invalidated with `valid?`' do
+        expect(@r.valid?).to be_false
+      end
+
+      it 'can be validated with `valid?`' do
+        @r.params = {'name' => 'bar'}
+        expect(@r.valid?).to be_true
+      end
+
+      it 'replaces spaces with plus in params' do
+       @r.params = {'name' => 'Aus bus'}
+       expect(@r.search_url =~ /\s/).to_not be_true
+      end
+
+    end
+
+    describe 'API keys' do
+      it "are stored in an `api_key` attribute" do
+        expect(RubyBHL::Request.new()).to respond_to(:api_key)
+      end
+
+      it 'are required' do
+        expect{RubyBHL::Request.new(api_key: nil)}.to raise_error
+      end
+
+      it "can come from `ENV['BHL_API_KEY']`" do
+        expect(RubyBHL::Request.new(api_key: RubyBHL::API_KEY_ENV).api_key).to eq('sekret_key_here')
+      end
+
+      it 'can come from `~/.bhl_api_key`' do
+        if File.exists?(RubyBHL::API_KEY_FILE_PATH)
+          expect(RubyBHL::Request.new()).to be_true
+        else
+          expect{RubyBHL::Request.new()}.to raise_error, API_KEY_MESSAGE
+        end
+      end
+
+      it "are from ~/.bhl_api_key instead of ENV['BHL_API_KEY'] when both provided" do
+        if RubyBHL::API_KEY_FILE.nil? || RubyBHL::API_KEY_ENV.nil?
+          pending API_KEY_MESSAGE
+        else
+          expect(RubyBHL::Request.new().api_key).to eq(RubyBHL::API_KEY_FILE )
+        end
+      end
+
+      it "are from opts(:api_key) instead of ENV or ~/.bhl_api_key when provided" do
+        if RubyBHL::API_KEY_FILE.nil? || RubyBHL::API_KEY_ENV.nil?
+          pending API_KEY_MESSAGE
+        else
+          expect(RubyBHL::Request.new(api_key: 'foo').api_key).to eq('foo')
+        end
+      end
+
+   end
+  end
+
+end
+

data/spec/lib/response_spec.rb

@@ -0,0 +1,21 @@
+require_relative '../spec_helper'
+describe RubyBHL::Response do
+  subject { RubyBHL::Response }
+
+  it 'requires a response' do
+    expect{ RubyBHL::Response.new() }.to raise_error
+  end
+
+  it 'a valid request does not raise' do
+    request = RubyBHL::Request.new(params: {'name' => 'blorf'})
+    expect(request.valid?).to be_true
+    expect{ RubyBHL::Response.new(request: request) }.to_not raise_error
+  end
+end
+
+#   def test_OCR_text_scraping
+#     @bhl = RubyBHL::Rbhl.new(:params => {:title => "Manual of North American Diptera"}) 
+#     assert @bhl.OCR_text(0).size > 0
+#     assert @bhl.OCR_text(0) =~ /Diptera/ 
+#   end
+

data/spec/lib/ruby_bhl_spec.rb

@@ -0,0 +1,41 @@
+require_relative '../spec_helper'
+
+describe RubyBHL do
+  subject { RubyBHL }
+
+  it 'breaks for ruby 1.9.3 and older' do
+    %w{1.8.7 1.9.2 1.9.3}.each do |v|
+      stub_const('RUBY_VERSION', v) 
+      expect{load File.expand_path('../../../lib/rubyBHL.rb', __FILE__)}.
+        to raise_error
+    end
+  end
+
+  it 'has version' do
+    expect(RubyBHL::VERSION =~ /\d+\.\d+\.\d/).to be_true
+  end
+
+  it 'has API_KEY_FILE_PATH' do
+    expect(RubyBHL::API_KEY_FILE_PATH).to eq( File.expand_path("~/.bhl_api_key") )
+  end
+
+  describe '`quick_request`' do
+    it 'exists as a class method' do
+      expect(RubyBHL.public_methods.include?(:quick_request)).to be_true
+    end
+
+    it 'responds with a RubyBHL::Response' do
+      expect(RubyBHL.quick_request().class).to eq(RubyBHL::Response) 
+    end
+
+    it 'makes a Net::HTTP request, and turns it into json' do
+      expect(RubyBHL.quick_request().json).to eq({"Status"=>"ok", "ErrorMessage"=>nil, "Result"=>[]}) 
+    end
+
+  end
+
+
+
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# require 'coveralls'
+# Coveralls.wear!
+
+require 'dotenv'
+Dotenv.load
+
+require 'rubyBHL' 
+require 'awesome_print'
+# require 'rspec'
+# require 'rspec/mocks'
+# require 'socket'
+
+API_KEY_MESSAGE =  "Add a key to ~/.bhl_api_key and/or ensure ENV['BHL_API_KEY'] is set for this test to pass or be tested."
+
+RSpec.configure do |config|
+
+end

metadata

@@ -1,68 +1,197 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: rubyBHL
-version: !ruby/object:Gem::Version 
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 0.2.1
 platform: ruby
-authors: 
-- Yoder & Seltmann
+authors:
+- Matt Yoder
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2009-10-19 00:00:00 -04:00
-default_executable: 
-dependencies: []
-
-description: Hook to the Biodiversity Heritage Library API plus some screen scraping for OCR.
+date: 2014-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: debugger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: RubyBHL is a simple but flexible request/response wrapper for the Biodiversity
+  Heritage Libary API.  It includes (some) validation for request formatting.  It
+  has excellent unit-test coverage.
 email: diapriid@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
-- README.rdoc
-- lib/rubyBHL.rb
-files: 
-- Manifest
+extra_rdoc_files: []
+files:
+- .env
+- .gitignore
+- .rspec
+- .ruby-version
+- Gemfile
+- Gemfile.lock
+- LICENSE
 - README.rdoc
 - Rakefile
-- init.rb
 - lib/rubyBHL.rb
-- test/helper.rb
-- test/rubyBHL_test.rb
+- lib/rubyBHL/mine.rb
+- lib/rubyBHL/request.rb
+- lib/rubyBHL/response.rb
+- lib/rubyBHL/version.rb
 - rubyBHL.gemspec
-has_rdoc: true
-homepage: http://github.com/mjy/rubyBHL
-licenses: []
-
+- spec/lib/mine_spec.rb
+- spec/lib/request_spec.rb
+- spec/lib/response_spec.rb
+- spec/lib/ruby_bhl_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/SpeciesFileGroup/rubyBHL
+licenses:
+- University of Illinois/NCSA Open Source License (NCSA)
+metadata: {}
 post_install_message: 
-rdoc_options: 
-- --line-numbers
-- --inline-source
-- --title
-- rubyBHL
-- --main
-- README.rdoc
-require_paths: 
+rdoc_options: []
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "1.2"
-  version: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ~>
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: rubybhl
-rubygems_version: 1.3.5
+rubyforge_project: 
+rubygems_version: 2.1.11
 signing_key: 
-specification_version: 3
-summary: Hook to the Biodiversity Heritage Library API plus some screen scraping for OCR.
-test_files: 
-- test/rubyBHL_test.rb
+specification_version: 4
+summary: RubyBHL is a simple request/response wrapper for the Biodiversity Heritage
+  Libary API.
+test_files:
+- spec/lib/mine_spec.rb
+- spec/lib/request_spec.rb
+- spec/lib/response_spec.rb
+- spec/lib/ruby_bhl_spec.rb
+- spec/spec_helper.rb

data/Manifest

@@ -1,7 +0,0 @@
-Manifest
-README.rdoc
-Rakefile
-init.rb
-lib/rubyBHL.rb
-test/helper.rb
-test/rubyBHL_test.rb

data/init.rb

@@ -1 +0,0 @@
-#require 'ruby_BHL'

data/test/helper.rb

@@ -1,3 +0,0 @@
-require 'test/unit'
-require 'rubygems'
-require 'ruby-debug'

data/test/rubyBHL_test.rb

@@ -1,36 +0,0 @@
-require File.expand_path(File.join(File.dirname(__FILE__), 'helper'))
-require File.expand_path(File.join(File.dirname(__FILE__), '../lib/rubyBHL'))
-
-class RubyBHLTest < Test::Unit::TestCase
-
-  def setup
-  end
-
-  def test_foo_is_not_a_legal_param
-    assert_raise(RubyBHL::RbhlError) {RubyBHL::Rbhl.new(:params => {:foo => "BAR!"}) }   
-  end
-  
-  def test_search_url_for_default_url_is_properly_formed
-    @bhl = RubyBHL::Rbhl.new(:params => {:title => "BAR!", :volume => "2"})
-    assert_equal "http://www.biodiversitylibrary.org/openurl?title=BAR!&volume=2&format=json", @bhl.search_url 
-  end
-  
-  def test_search_url_convert_space_to_plus
-    @bhl = RubyBHL::Rbhl.new(:params => {:title => "BAR FOO"})
-    assert_equal "http://www.biodiversitylibrary.org/openurl?title=BAR+FOO&format=json", @bhl.search_url 
-  end
-  
-  def test_basic_response_is_returned
-   # this is a crummy test, we need a reference to the status codes.
-   @bhl = RubyBHL::Rbhl.new(:params => {:title => "BAR FOO"}) # should match nothing, I hope
-   assert @bhl.json_data["Status"] == 1
-   assert @bhl.json_data["citations"].size == 0
-  end
-  
-  def test_response_with_citations_is_returned
-   # this is a crummy test, we need a reference to the status codes.
-   @bhl = RubyBHL::Rbhl.new(:params => {:title => "Manual of North American Diptera"}) # should match nothing, I hope
-   assert @bhl.json_data["citations"].size > 0
-  end
-
-end