biblesearch-api 1.0.3 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea80ca9332cf2efd85b7e0bafe26cda4502cf137
+  data.tar.gz: 5721a597d24d248254a58b182b6f0cd6e514c61b
+SHA512:
+  metadata.gz: 5027d70b070bb8af63ab66368973a153d163e6b47083067173966432759300c90081af263487bba384bf23c374f2e2ea69774bf6561eb67201db449fc89a0b79
+  data.tar.gz: 86e5223f125886015391a65c631e7cf3ad35d87f7cdb70d43828ca907656823043599f5571d173b1ef2974ec81430aa0bdfc1015e30ab13552c9646e9b3cd788

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+*.log
 .bundle
 .config
 .yardoc
@@ -12,9 +13,11 @@ lib/bundler/man
 pkg
 rdoc
 spec/reports
-spec/cassettes
+#spec/cassettes
 test/tmp
 test/version_tmp
 tmp
 *~
 *.swp
+.idea
+API_KEY

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+- 1.9.3
+- 2.0.0
+notifications:
+  hipchat:
+    rooms:
+      secure: WfUu7pViMsCPwe/eGKViF0y37PnqiyLWzxr+OAn4GHWmSKpbdBtzBy/QbPVuxzERMjAQFljt+U7f9Ix8PjQHN3tuDJuLxVhv+8yYiQf1yvFbSuMV9Sk/hJdSUu6itW6tb5sm75fHxe//UuJT03qS0N1vRXbZwPu6hrt6UOsmie4=
+    template:
+      - '%{repository}#%{build_number} (%{branch} - %{commit} : %{author}): %{message}'

data/Guardfile

@@ -0,0 +1,28 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :minitest do
+  # with Minitest::Unit
+  # watch(%r{^test/(.*)\/?test_(.*)\.rb})
+  # watch(%r{^lib/(.*/)?([^/]+)\.rb})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  # watch(%r{^test/test_helper\.rb})      { 'test' }
+
+  # with Minitest::Spec
+  watch(%r{^spec/(.*)_spec\.rb})
+  watch(%r{^lib/(.+)\.rb})         { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb}) { 'spec' }
+
+  # Rails 4
+  # watch(%r{^app/(.+)\.rb})                               { |m| "test/#{m[1]}_test.rb" }
+  # watch(%r{^app/controllers/application_controller\.rb}) { 'test/controllers' }
+  # watch(%r{^app/controllers/(.+)_controller\.rb})        { |m| "test/integration/#{m[1]}_test.rb" }
+  # watch(%r{^app/views/(.+)_mailer/.+})                   { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
+  # watch(%r{^lib/(.+)\.rb})                               { |m| "test/lib/#{m[1]}_test.rb" }
+  # watch(%r{^test/.+_test\.rb})
+  # watch(%r{^test/test_helper\.rb}) { 'test' }
+
+  # Rails < 4
+  # watch(%r{^app/controllers/(.*)\.rb}) { |m| "test/functional/#{m[1]}_test.rb" }
+  # watch(%r{^app/helpers/(.*)\.rb})     { |m| "test/helpers/#{m[1]}_test.rb" }
+  # watch(%r{^app/models/(.*)\.rb})      { |m| "test/unit/#{m[1]}_test.rb" }
+end

data/HISTORY.md

@@ -1,3 +1,4 @@
-1.0.3 - Client now uses version 2 of the API, all calls now mostly uniform.
-0.0.2 - #versions and #verses now always respond in the plural, tested
-0.0.1 - Basic functionality, no tests
+* 1.1.0 - now enables include_marginalia and include_chapters
+* 1.0.3 - Client now uses version 2 of the API, all calls now mostly uniform.
+* 0.0.2 - #versions and #verses now always respond in the plural, tested
+* 0.0.1 - Basic functionality, no tests

data/README.md

@@ -1,6 +1,13 @@
 # BibleSearch::API
 
-Ruby wrapper for BibleSearch API (bibles.org)
+Ruby wrapper for [BibleSearch API (bibles.org)](http://bibles.org).
+
+## Status
+
+Gem hosted at [RubyGems](http://rubygems.org/gems/biblesearch-api), API docs at [RubyDoc](http://rubydoc.info/gems/biblesearch-api).
+
+* Stable Version (1.1.0): [![Build Status](https://travis-ci.org/americanbible/biblesearch-api-ruby.png?branch=master)](https://travis-ci.org/americanbible/biblesearch-api-ruby)
+* Development Version: [![Build Status](https://travis-ci.org/americanbible/biblesearch-api-ruby.png?branch=develop)](https://travis-ci.org/americanbible/biblesearch-api-ruby)
 
 ## Installation
 
@@ -24,43 +31,43 @@ biblesearch = BibleSearch.new('YOUR_API_KEY')
 # Let's get some versions
 versions = biblesearch.versions
 spanish_versions = biblesearch.versions(:language => 'spa')
-version = biblesearch.version('GNT')
-# You can also add a language to a singular version
-spanish_version = biblesearch.version('spa-GNT')
+
+# When you request a version, you'll need to include it's language-code prefix
+version = biblesearch.version('spa-TLA')
 
 # Let's get some books
-books = biblesearch.books('GNT')
+books = biblesearch.books('spa-TLA')
 # You can also provide a testament
-old_testament_books = biblsearch.books('GNT', 'OT')
+old_testament_books = biblsearch.books('spa-TLA', 'OT')
 # A single book can be specified as a hash ...
-book = biblesearch.book(:version_id => 'GNT', :book_id => '2Tim')
+book = biblesearch.book(:version_id => 'spa-TLA', :book_id => '2Tim')
 # ... or as a string
-book = biblesearch.book('GNT:2Tim')
+book = biblesearch.book('spa-TLA:2Tim')
 
 # Let's get some chapters for the book, either via hash ...
-chapters = biblesearch.chapters(:version_id => 'GNT', :book_id => '2Tim')
+chapters = biblesearch.chapters(:version_id => 'spa-TLA', :book_id => '2Tim')
 # ... or string
-chapters = biblesearch.chapters('GNT:2Tim')
+chapters = biblesearch.chapters('spa-TLA:2Tim')
 # A single chapter can be specified as a hash ...
-chapter = biblesearch.chapter(:version_id => 'GNT', :book_id => '2Tim', :chapter => 1)
+chapter = biblesearch.chapter(:version_id => 'spa-TLA', :book_id => '2Tim', :chapter => 1)
 # ... or as a string
-chatper = biblesearch.chapter('GNT:2Tim.1')
+chatper = biblesearch.chapter('spa-TLA:2Tim.1')
 
 # Let's get some verses
-verses = biblesearch.verses("CEV:John.1","16","17")
+verses = biblesearch.verses("eng-CEV:John.1","16","17")
 # A single verse can be specified as a hash ...
-verse = biblesearch.verse(:version_id => 'GNT', :book_id => 'Acts', :chapter => '8', :verse => '34')
+verse = biblesearch.verse(:version_id => 'spa-TLA', :book_id => 'Acts', :chapter => '8', :verse => '34')
 # ... or as a string
-verse = biblesearch.verse('GNT:Acts.8.34')
+verse = biblesearch.verse('spa-TLA:Acts.8.34')
 
 # Let's do a search
 results = biblesearch.search('john 3:16') #passage search
 results = biblesearch.search('mary') #keyword search
 
 # Let's get some passages for a single version ...
-passages = biblesearch.passages('john 3:16', :version => 'KJV')
+passages = biblesearch.passages('john 3:16', :version => 'eng-KJVA')
 # ... or for multiple versions
-passages = biblesearch.passages('john 3:16', :versions => ['KJV', 'CEV'])
+passages = biblesearch.passages('john 3:16', :versions => ['eng-KJVA', 'eng-CEV'])
 ```
 
 ### Return values
@@ -74,18 +81,18 @@ Singular calls (#version, #verse, etc) respond to #value with a mash.
 ## Contributing
 
 1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Test against all supported rubies (`rake overtest` (see below))
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+1. Create your feature branch (`git checkout -b my-new-feature`)
+1. Frequently test your code with `rake test:all`, adding tests for your new features. (*Note* that this Gem uses the `minitest` framework, not `RSpec`, despite the `spec/` directory name.)
+1. Test against all supported rubies (`rake test:overtest` (see below))
+1. Commit your changes (`git commit -am 'Added some feature'`)
+1. Push to the branch (`git push origin my-new-feature`)
+1. Create new Pull Request
 
 ### Supported Rubies
 
 As of this release, the following MRI versions are verified as supported:
 
-* 1.8.7
-* 1.9.2-p180
 * 1.9.3
+* 2.0.0
 
-In order to test against all of them, an "overtest" rake task is supplied that uses RVM to test against each of the supported versions. You will, however, have to bundle against each of them independently.
+In order to test against all of them, an "test:overtest" rake task is supplied that uses RVM to test against each of the supported versions. You will, however, have to bundle against each of them independently.

data/Rakefile

@@ -3,6 +3,11 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 require "bundler/gem_tasks"
 require 'rake/testtask'
+require 'rake/clean'
+
+# one way to remove cassette files
+# require 'rake/clean'
+CLOBBER.include('spec/cassettes/*.yml')
 
 RUBY_TEST_VERSIONS = [
   '1.8.7',
@@ -10,15 +15,29 @@ RUBY_TEST_VERSIONS = [
   '1.9.3'
 ]
 
-Rake::TestTask.new do |t|
-  t.libs.push "spec"
-  t.pattern = 'spec/**/*_spec.rb'
-  t.verbose = true
-end
+namespace "test" do
+
+  desc 'Run all of the gem minitests.'
+  Rake::TestTask.new(:all) do |t|
+    t.libs.push "spec"
+    t.pattern = 'spec/**/*_spec.rb'
+    t.verbose = true
+  end
+
+  desc 'Focus on a particular test file (hardcoded for now).'
+  Rake::TestTask.new(:focus) do |t|
+    t.libs.push "spec"
+    t.pattern = 'spec/**/chapters_spec.rb'
+    t.verbose = true
+  end
+
+  desc 'Tests the library against several rubies'
+  task :overtest do
+    system "rvm #{RUBY_TEST_VERSIONS.map{|x| "#{x}@biblesearch-api"}.join(',')} do bundle exec rake test"
+  end
 
-task :default => :test
 
-desc 'Tests the library against several rubies'
-task :overtest do
-  system "rvm #{RUBY_TEST_VERSIONS.map{|x| "#{x}@biblesearch-api"}.join(',')} do bundle exec rake test"
 end
+
+task :default => "test:all"
+

data/biblesearch-api.gemspec

@@ -18,8 +18,10 @@ Gem::Specification.new do |gem|
   gem.add_dependency "oj"
   gem.add_dependency "hashie"
   gem.add_dependency "httparty"
-  gem.add_development_dependency 'vcr'
-  gem.add_development_dependency 'webmock'
+  gem.add_development_dependency 'vcr', '= 2.6.0'
+  gem.add_development_dependency 'webmock' , '>= 1.8.0', '< 1.14'
   gem.add_development_dependency 'minitest', '= 3.3.0'
   gem.add_development_dependency 'rake', '= 0.9.2.2'
+  gem.add_development_dependency 'minitest-reporters', '>= 0.5.0'
+  gem.add_development_dependency 'guard-minitest'
 end

data/lib/biblesearch-api.rb

@@ -37,51 +37,56 @@ class BibleSearch
   format :json
 
   attr_accessor :api_key
+
   def initialize(api_key, base_uri = 'bibles.org/v2')
     self.class.base_uri base_uri
     self.class.basic_auth(@api_key = api_key, 'X')
+    @version_re =    /[A-Za-z]{3}+-[A-Za-z0-9]+/
+    @book_re =       /[A-Za-z]{3}+-[A-Za-z0-9]+:[A-Za-z0-9]+/
+    @chapter_re =    /[A-Za-z]{3}+-[A-Za-z0-9]+:[A-Za-z0-9]+\.[A-Za-z0-9]+/
+    @verse_re =      /[A-Za-z]{3}+-[A-Za-z0-9]+:[A-Za-z0-9]+\.[A-Za-z0-9]+\.[A-Za-z0-9]+/
   end
 
   private
-    def mashup(response)
-      response = Hashie::Mash.new(response)
-      # => raise BibleSearchError.new("Code #{response.code} -- #{response.desc}") unless response.stat == "ok"
-      response
-    end
-
-    def required_keys_present?(hash, required)
-      hash.keys.sort_by {|key| key.to_s} == required.sort_by {|key| key.to_s}
-    end
+  def mashup(response)
+    response = Hashie::Mash.new(response)
+    # => raise BibleSearchError.new("Code #{response.code} -- #{response.desc}") unless response.stat == "ok"
+    response
+  end
 
-    def get_mash(*args)
-      api_response = self.class.get(*args)
-      result = {}
-      result['meta'] = {}
-      begin
-        result['meta'] = api_response['response'].delete('meta')
-        result['response'] = api_response['response']
-      rescue MultiJson::LoadError
-        result['meta']['message'] = api_response.body
-      ensure
-        result['meta']['http_code'] = api_response.code
-        return mashup(result)
-      end
-    end
+  def required_keys_only?(hash, required)
+    hash.keys.sort_by { |key| key.to_s } == required.sort_by { |key| key.to_s }
+  end
 
-    def pluralize_result(result)
-      result.kind_of?(Array) ? result : [result]
+  def get_mash(*args)
+    api_response = self.class.get(*args)
+    result = {}
+    result['meta'] = {}
+    begin
+      result['meta'] = api_response['response'].delete('meta')
+      result['response'] = api_response['response']
+    rescue JSON::JSONError #MultiJSON dropped from httpparty 14JUN2013
+      result['meta']['message'] = api_response.body
+    ensure
+      result['meta']['http_code'] = api_response.code
+      return mashup(result)
     end
+  end
 
-    def fumsify(api_result, value)
-      fumsified = Hashie::Mash.new
-      fumsified.fums = api_result.meta.fums
+  def pluralize_result(result)
+    result.kind_of?(Array) ? result : [result]
+  end
 
-      if value.kind_of?(Array)
-        fumsified.collection = value
-      else
-        fumsified.value = value
-      end
+  def fumsify(api_result, value)
+    fumsified = Hashie::Mash.new
+    fumsified.fums = api_result.meta.fums
 
-      fumsified
+    if value.kind_of?(Array)
+      fumsified.collection = value
+    else
+      fumsified.value = value
     end
+
+    fumsified
+  end
 end

data/lib/biblesearch-api/client_version.rb

@@ -1,3 +1,3 @@
 class BibleSearch
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end

data/lib/biblesearch-api/endpoints/books.rb

@@ -1,38 +1,63 @@
 class BibleSearch
+
+  # accept a hash or string book signature, validate it, and return a string
+  def valid_book(book_sig)
+    # if it's a hash, convert it to a string
+    if book_sig.is_a?(Hash)
+      begin
+        book_sig = "#{book_sig.fetch(:version_id)}:#{book_sig.fetch(:book_id)}"
+      rescue
+        raise ArgumentError.new('Book signature hash must include :version_id and :book_id')
+      end
+    end
+
+    # then check
+    unless book_sig.match(@book_re)
+      raise ArgumentError.new('Book signature must be in the form "LANGUAGE_ID-VERSION_ID:BOOK_ID"')
+    end
+    book_sig
+  end
+
   module Books
-    def books(version_id, testament_id = nil)
+    def books(version_id, options={})
+      defaults = {testament_id: nil, include_chapters: false}
+      options = defaults.merge(options)
+      testament_id = options[:testament_id]
+      include_chapters = options[:include_chapters]
+
       api_endpoint = "/versions/#{version_id}/books.js"
       api_endpoint += "?testament=#{testament_id}" unless testament_id.nil?
+      api_endpoint += "?include_chapters=true" if include_chapters
+
+      unless @version_re.match(version_id)
+        raise ArgumentError.new('version_id must be in the form "LANGUAGE_CODE-VERSION_ID:BOOK_ID"')
+      end
 
       api_result = get_mash(api_endpoint)
 
-      books = []
       if api_result.meta.http_code == 200
+        books = []
         books = pluralize_result(api_result.response.books)
+        fumsify(api_result, books)
+      else
+        []
       end
-      
-      fumsify(api_result, books)
     end
 
     def book(book_sig)
-      if book_sig.is_a?(Hash)
-        unless required_keys_present?(book_sig, [:version_id, :book_id])
-          raise ArgumentError.new('Book signature hash must include :version_id and :book_id')
-        end
-        return book("#{book_sig[:version_id]}:#{book_sig[:book_id]}")
-      end
+      book_sig = valid_book(book_sig)
 
-      unless book_sig.match(/([A-Za-z0-9]+-)?[A-Za-z0-9]+:[A-Za-z0-9]+/)
-        raise ArgumentError.new('Book signature must be in the form "VERSION_ID:BOOK_ID"')
-      end
-
-      book = nil
       api_result = get_mash("/books/#{book_sig}.js")
       if api_result.meta.http_code == 200
+        book = nil
         book = api_result.response.books.first
+        fumsify(api_result, book)
+      else
+        nil
       end
 
-      fumsify(api_result, book)
     end
+
+
   end
 end

data/lib/biblesearch-api/endpoints/chapters.rb

@@ -1,47 +1,53 @@
 class BibleSearch
-  module Chapters
-    def chapters(book_sig)
-      if book_sig.is_a?(Hash)
-        unless required_keys_present?(book_sig, [:version_id, :book_id])
-          raise ArgumentError.new('Book signature hash must include :version_id and :book_id')
-        end
 
-        return chapters("#{book_sig[:version_id]}:#{book_sig[:book_id]}")
+  def valid_chapter(chapter_sig)
+    if chapter_sig.is_a?(Hash)
+      begin
+        # chapter_sig = chapter_sig.fetch(:version_id) + ':' + chapter_sig.fetch(:book_id) +  ".#{chapter_sig.fetch(:chapter)}"
+        chapter_sig = "#{valid_book(chapter_sig)}.#{chapter_sig.fetch(:chapter)}"
+      rescue
+        raise ArgumentError.new('Chapter signature hash must include :version_id, :book_id, and :chapter')
       end
+    end
 
-      unless book_sig.match(/([A-Za-z0-9]+-)?[A-Za-z0-9]+:[A-Za-z0-9]+/)
-        raise ArgumentError.new('Book signature must be in the form "VERSION_ID:BOOK_ID"')
-      end
+    unless chapter_sig.match(@chapter_re)
+      raise ArgumentError.new('Chapter signature must be in the form "VERSION_ID:BOOK_ID.CHAPTER_NUMBER"')
+    end
+    chapter_sig
+  end
 
-      chapters = []
+  module Chapters
+    def chapters(book_sig)
+      book_sig = valid_book(book_sig)
       api_result = get_mash("/books/#{book_sig}/chapters.js")
       if api_result.meta.http_code == 200
+        chapters = []
         chapters = pluralize_result(api_result.response.chapters)
+        fumsify(api_result, chapters)
+      else
+        # raise ArgumentError.new("Unrecognized book signature.")
+        []
       end
 
-      fumsify(api_result, chapters)
     end
 
-    def chapter(chapter_sig)
-      if chapter_sig.is_a?(Hash)
-        unless required_keys_present?(chapter_sig, [:version_id, :book_id, :chapter])
-          raise ArgumentError.new('Chapter signature hash must include :version_id, :book_id, and :chapter')
-        end
-
-        return chapter("#{chapter_sig[:version_id]}:#{chapter_sig[:book_id]}.#{chapter_sig[:chapter]}")
-      end
+    # def chapter(chapter_sig) #original
+    def chapter(chapter_sig, options={}) #option 1
+    # def chapter(options) #option 2 (options merged with sig, breaks string sig)
+      chapter_sig = valid_chapter(chapter_sig)
 
-      unless chapter_sig.match(/([A-Za-z0-9]+-)?[A-Za-z0-9]+:[A-Za-z0-9]+\.[0-9]+/)
-        raise ArgumentError.new('Chapter signature must be in the form "VERSION_ID:BOOK_ID.CHAPTER_NUMBER"')
-      end
-
-      chapter = nil
-      api_result = get_mash("/chapters/#{chapter_sig}.js")
+      # uri += '?include_marginalia=true' if options.fetch(:include_marginalia, false)
+      api_result = get_mash("/chapters/#{chapter_sig}.js", query: options)
       if api_result.meta.http_code == 200
+        chapter = nil
         chapter = api_result.response.chapters.first
+        fumsify(api_result, chapter)
+      else
+        nil
       end
 
-      fumsify(api_result, chapter)
     end
+
+
   end
 end