biblesearch-api 1.0.1

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+spec/cassettes
+test/tmp
+test/version_tmp
+tmp
+*~
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in biblesearch-api.gemspec
+gemspec

data/HISTORY.md

@@ -0,0 +1,3 @@
+1.0.1 - 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/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Bryce Allison
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in 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:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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 AUTHORS 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 IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# BibleSearch::API
+
+Ruby wrapper for BibleSearch API (bibles.org)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'biblesearch-api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install biblesearch-api
+
+## Usage
+
+```ruby
+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')
+
+# Let's get some books
+books = biblesearch.books('GNT')
+# You can also provide a testament
+old_testament_books = biblsearch.books('GNT', 'OT')
+# A single book can be specified as a hash ...
+book = biblesearch.book(:version_id => 'GNT', :book_id => '2Tim')
+# ... or as a string
+book = biblesearch.book('GNT:2Tim')
+
+# Let's get some chapters for the book, either via hash ...
+chapters = biblesearch.chapters(:version_id => 'GNT', :book_id => '2Tim')
+# ... or string
+chapters = biblesearch.chapters('GNT:2Tim')
+# A single chapter can be specified as a hash ...
+chapter = biblesearch.chapter(:version_id => 'GNT', :book_id => '2Tim', :chapter => 1)
+# ... or as a string
+chatper = biblesearch.chapter('GNT:2Tim.1')
+
+# Let's get some verses
+verses = biblesearch.verses("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')
+# ... or as a string
+verse = biblesearch.verse('GNT: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')
+# ... or for multiple versions
+passages = biblesearch.passages('john 3:16', :versions => ['KJV', 'CEV'])
+```
+
+### Return values
+
+All methods return a Hashie::Mash, and all of these mashes respond to #fums, which contains a string describing the FUMS for the call that was made.
+
+Plural calls (#passages, #versions, #search, etc) respond to #collection with an array of mashes.
+
+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
+
+### Supported Rubies
+
+As of this release, the following MRI versions are verified as supported:
+
+* 1.8.7
+* 1.9.2-p180
+* 1.9.3
+
+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.

data/Rakefile

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+RUBY_TEST_VERSIONS = [
+  '1.8.7',
+  '1.9.2-p180',
+  '1.9.3'
+]
+
+Rake::TestTask.new do |t|
+  t.libs.push "spec"
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+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

data/biblesearch-api.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/biblesearch-api/client_version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Bryce Allison"]
+  gem.email         = ["bryceallison@gmail.com"]
+  gem.description   = %q{Wrapper for the American Bible Society Bible Search API}
+  gem.summary       = %q{Wrapper for the American Bible Society Bible Search API}
+  gem.homepage      = "http://bibles.org"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "biblesearch-api"
+  gem.require_paths = ["lib"]
+  gem.version       = BibleSearch::VERSION
+
+  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 'minitest', '= 3.3.0'
+  gem.add_development_dependency 'rake', '= 0.9.2.2'
+end

data/lib/biblesearch-api.rb

@@ -0,0 +1,87 @@
+require 'biblesearch-api/client_version'
+
+require 'biblesearch-api/endpoints/books'
+require 'biblesearch-api/endpoints/chapters'
+require 'biblesearch-api/endpoints/passages'
+require 'biblesearch-api/endpoints/search'
+require 'biblesearch-api/endpoints/verses'
+require 'biblesearch-api/endpoints/versions'
+
+require 'hashie'
+require 'httparty'
+
+directory = File.expand_path(File.dirname(__FILE__))
+
+Hash.send :include, Hashie::HashExtensions
+
+class BibleSearchError < StandardError
+  attr_reader :data
+
+  def initialize(data)
+    @data = data
+    super
+  end
+end
+
+class BibleSearch
+  include HTTParty
+
+  include Books
+  include Chapters
+  include Passages
+  include Search
+  include Verses
+  include Versions
+
+  no_follow = true
+  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')
+  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 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 pluralize_result(result)
+      result.kind_of?(Array) ? result : [result]
+    end
+
+    def fumsify(api_result, value)
+      fumsified = Hashie::Mash.new
+      fumsified.fums = api_result.meta.fums
+
+      if value.kind_of?(Array)
+        fumsified.collection = value
+      else
+        fumsified.value = value
+      end
+
+      fumsified
+    end
+end

data/lib/biblesearch-api/api_interface.rb

@@ -0,0 +1,58 @@
+require 'httparty'
+
+module BibleSearch
+  class APIInterface
+    include HTTParty
+    include Singleton
+
+    no_follow = true
+    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')
+    end
+
+    private
+      def mashup(response)
+        Hashie::Mash.new(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 api_get(*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 pluralize_result(result)
+        result.kind_of?(Array) ? result : [result]
+      end
+
+      def fumsify(api_result, value)
+        fumsified = Hashie::Mash.new
+        fumsified.fums = api_result.meta.fums
+
+        if value.kind_of?(Array)
+          fumsified.collection = value
+        else
+          fumsified.value = value
+        end
+
+        fumsified
+      end
+  end
+end

data/lib/biblesearch-api/client_version.rb

@@ -0,0 +1,3 @@
+class BibleSearch
+  VERSION = "1.0.1"
+end

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

@@ -0,0 +1,38 @@
+class BibleSearch
+  module Books
+    def books(version_id, testament_id = nil)
+      api_endpoint = "/versions/#{version_id}/books.js"
+      api_endpoint += "?testament=#{testament_id}" unless testament_id.nil?
+
+      api_result = get_mash(api_endpoint)
+
+      books = []
+      if api_result.meta.http_code == 200
+        books = pluralize_result(api_result.response.books)
+      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
+
+      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 = api_result.response.books.first
+      end
+
+      fumsify(api_result, book)
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+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]}")
+      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
+
+      chapters = []
+      api_result = get_mash("/books/#{book_sig}/chapters.js")
+      if api_result.meta.http_code == 200
+        chapters = pluralize_result(api_result.response.chapters)
+      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
+
+      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")
+      if api_result.meta.http_code == 200
+        chapter = api_result.response.chapters.first
+      end
+
+      fumsify(api_result, chapter)
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+class BibleSearch
+  module Passages
+    def passages(passage, options = {})
+      versions = options.delete(:versions)
+      unless versions.nil?
+        if versions.is_a?(Array)
+          versions = versions.join(',')
+        end
+        options[:version] = versions
+      end
+      options = options.merge({"q[]" => passage})
+
+      passages = []
+      api_result = get_mash("/passages.js", :query => options)
+      if api_result.meta.http_code == 200
+        passages = pluralize_result(api_result.response.search.result.passages)
+      end
+
+      fumsify(api_result, passages)
+    end
+  end
+end