tankard 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15d6c67b39b0fbce1ddce69adcdbca40366f1281
-  data.tar.gz: e7db9eff7e9a74a9e4794bb509f1a7d73d4980a7
+  metadata.gz: caf2e4adbd1c27dad9227737cec3b9ccb7947d4d
+  data.tar.gz: ce3dbc3b145c38afdcb37c80472ac042d121269d
 SHA512:
-  metadata.gz: 48d66cb484f2726da1caa59f15905f46a1494742793d16a00083c1fb5ae21472f776d0997029f7c77362183eca5e4db79b32463466c9df456fdbd65387efdd2b
-  data.tar.gz: f06bb814da4bb553a938dd77584cdbd0a41fa8bce2ef4aca962bf5e5b615a280be51ad7d78175ba78c1db074511fc0a30cea8b3d13ffc581d531986cfe183c47
+  metadata.gz: 4734b1c05ec5529b9af9105c70308aacf74a5cdd04b76e570c461beb2775ff2a430ec1a3947f64b37d7a065bae75500e91b13e17d42aa233276080d4ff597b72
+  data.tar.gz: 1b27b4d244bb37e09453d9908d8fd91667244f47a5b22de60fe9f36ca89d68aa4128f127795574596811f960aa30740b23dae2b99aea8e7d40f4eb9c360a1575

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v0.1.0 (05/15/2013)
+* Add params method to beers.  Allows passing additional parameters in an additional way.
+* Add params method to beer.  Allows passing additional parameters in an additional way.
+* Add styles method & class.  Allows querying of the /styles route
+* Add style method & class.  Allows querying of the /style/:id route
+* Add search method & class. Allows querying of the /search route
+* Add documentation for beer
+* Add documentation for beers
+* Add documentation for search
+* Add documentation for style
+* Add documentation for styles
+
 ## v0.0.1
 * Support for querying a beer
 * Support for querying a list of beers

data/README.md

@@ -3,6 +3,7 @@
 [![Dependency Status](https://gemnasium.com/matthewshafer/tankard.png)](https://gemnasium.com/matthewshafer/tankard)
 [![Code Climate](https://codeclimate.com/github/matthewshafer/tankard.png)](https://codeclimate.com/github/matthewshafer/tankard)
 [![Coverage Status](https://coveralls.io/repos/matthewshafer/tankard/badge.png?branch=master)](https://coveralls.io/r/matthewshafer/tankard)
+[![Gem Version](https://badge.fury.io/rb/tankard.png)](http://rubygems.org/gems/tankard)
 
 Allows easy quering of the BreweryDB Api
 
@@ -14,11 +15,18 @@ I've also been pretty interested in Jruby as of late and wanted to make Tankard
 
 ## Installation
 
-Soon...
+```ruby
+gem install "tankard"
+```
+
+or add it to your gemfile
 
 ## Documentation
 
-Soon...
+Everytime a commit is pushed to github the documentation regenerates.
+You can find this at http://rubydoc.info/github/matthewshafer/tankard/frames
+
+If you visit rubygems you can find the documentation for a specific gem release.
 
 ## Usage
 
@@ -42,6 +50,45 @@ Tankard.beer.id("some_id").breweries.each { |x| p x}
 beer = Tankard.beer.find(["first_id", "second_id"])
 ```
 
+Alternatively you can send parameters to the request in two ways.  Here are examples:
+
+```ruby
+Tankard.beer(id: "some_id", endpoint: "breweries", anotherParam: "something").each { |x| p x }
+
+Tankard.beer.id("some_id").breweries.params(anotherParam: "something").each { |x| p x }
+```
+
+### Beers
+
+This would return an array with all beers greater than 10% (to_a comes from enumerable in this case)
+
+```ruby
+Tankard.beers.params(abv: "+10").to_a
+```
+### Search
+
+Here is how we could search for everything that matches "stone".
+We would get results that contain more than just beer (EX I would probably get a result for Stone Brewing)
+
+```ruby
+Tankard.search.query("stone").each { |x| p x }
+```
+### Style
+
+This works similiar to Beer, it just has less options
+
+```ruby
+Tankard.style.id("some_id").each { |x| p x }
+```
+
+### Styles
+
+Styles don't have any options so if I would like an array with all styles I can do something like
+
+```ruby
+Tankard.styles.to_a
+```
+
 ## Contributing
 
 ### Issues

data/lib/tankard/api/beer.rb

@@ -1,87 +1,136 @@
 require 'hashie'
 require 'tankard/api/request/get'
+require 'tankard/api/utils/page_finders'
+require 'tankard/api/utils/find'
 
 module Tankard
   module Api
+    # Access for the /beer route on brewerydb
+    #
+    # @see http://www.brewerydb.com/developers/docs-endpoint/beer_index
+    # @author Matthew Shafer
     class Beer
-      include ::Enumerable
       include Tankard::Api::Request::Get
-
+      include Tankard::Api::Utils::PageFinders
+      include Tankard::Api::Utils::Find
+      # @!parse include ::Enumerable
+
+      # Initialize a new object
+      #
+      # @param request [Tankard::Request]
+      # @param options [Hash]
+      # @return [Tankard::Api::Beer]
       def initialize(request, options={})
         @request = request
         @options = Hashie::Mash.new(options)
       end
 
-      def each(&block)
-        find_on_single_page(block)
-      end
-
-      def find(beer_id, options={})
-        @options.merge!(options)
-
-        if beer_id.is_a?(Array)
-          beer_id.map { |beer| request_data_with_nil_on_http_error(@request, "beer/#{beer}", @options) }.compact
-        else
-          request_data_with_nil_on_http_error(@request, "beer/#{beer_id}", @options)
-        end
-      end
-
+      # @!method find(id_or_array, options={})
+      #   Find a single or multiple beers by their id
+      #
+      #   @param id_or_array [String, Array]
+      #   @param options [Hash]
+      #   @return [Hash, Array] if a string with a beer id is passed to find then the hash of the beer is returned.
+      #     if an array is passed to find an array containing hashes with each beer is returned.
+      #     if a beer is not found nothing for that beer is returned.
+
+      # @!method each(&block)
+      #   Calls the given block once for each beer
+      #
+      #   @yieldparam [Hash] hash containing individual beer information
+      #   @raise [Tankard::Error::MissingParameter] when the id is not set
+      #   @raise [Tankard::Error::ApiKeyUnauthorized] when an api key is not valid
+      #   @raise [Tankard::Error::InvalidResponse] when no data is returned fron the api
+      #   @raise [Tankard::Error::HttpError] when a status other than 200 or 401 is returned
+      #   @raise [Tankard::Error::LoadError] when multi json is unable to decode json
+
+      # BeerID to query
+      #
+      # @param beer_id [String]
+      # @return [self] returns itself
       def id(beer_id)
         @options.id = beer_id
         self
       end
 
+      # Sets the request to beer/:id/breweries
+      #
+      # @return [self] returns itself
       def breweries
         @options.endpoint = "breweries"
         self
       end
 
+      # Sets the request to beer/:id/events
+      #
+      # @return [self] returns itself
       def events
         @options.endpoint = "events"
         self
       end
 
+      # Sets the request to beer/:id/ingredients
+      #
+      # @return [self] returns itself
       def ingredients
         @options.endpoint = "ingredients"
         self
       end
 
+      # Sets the request to beer/:id/socialaccounts
+      #
+      # @return [self] returns itself
       def social_accounts
         @options.endpoint = "socialaccounts"
         self
       end
 
+      # Sets the request to beer/:id/variations
+      #
+      # @return [self] returns itself
       def variations
         @options.endpoint = "variations"
         self
       end
 
+      # Additional parameters to send with the request
+      #
+      # @param options [Hash]
+      # @return [self] returns itself
+      def params(options={})
+        options.each_pair do |key,value|
+          @options[key] = value
+        end
+        self
+      end
+
       private
 
-        def request_data_from_options
-          endpoint = "beer/#{raise_if_no_id_in_options}"
+        def http_request_uri
+          endpoint = "#{route}/#{raise_if_no_id_in_options}"
 
           if @options.endpoint?
             endpoint += "/#{@options.delete(:endpoint)}"
           end
 
-          request_data(@request, endpoint, @options)
+          endpoint
         end
 
         def raise_if_no_id_in_options
-          raise Tankard::Error::NoBeerId unless @options.id?
+          raise Tankard::Error::MissingParameter, "No Beer ID is set" unless @options.id?
           @options.delete(:id)
         end
 
-        def find_on_single_page(block)
-          data = request_data_from_options
-          raise Tankard::Error::InvalidResponse unless data
+        def route
+          "beer"
+        end
 
-          if data.is_a?(Hash)
-            block.call(data)
-          else
-            data.each { |beer| block.call(beer) }
-          end
+        def http_client
+          @request
+        end
+
+        def http_request_parameters
+          @options
         end
     end
   end

data/lib/tankard/api/beers.rb

@@ -1,64 +1,78 @@
 require 'hashie'
 require 'tankard/api/request/get'
+require 'tankard/api/utils/page_finders'
 
 module Tankard
   module Api
+    # Access for the /beers route on brewerydb
+    #
+    # @see http://www.brewerydb.com/developers/docs-endpoint/beer_index
+    # @author Matthew Shafer
     class Beers
-      include ::Enumerable
       include Tankard::Api::Request::Get
+      include Tankard::Api::Utils::PageFinders
+      # @!parse include ::Enumerable
 
+      # Initializes a new object
+      #
+      # @param request [Tankard::Request]
+      # @param options [Hash]
+      # @return [Tankard::Api::Beers]
       def initialize(request, options={})
         @request = request
         @options = Hashie::Mash.new(options)
       end
 
-      def each(&block)
-        if options_have_page_set
-          find_on_single_page(block)
-        else
-          find_on_all_pages(block)
-        end
-      end
+      # @!method each(&block)
+      #   Calls the given block once for each beer
+      #
+      #   @yieldparam [Hash] hash containing individual beer information
+      #   @raise [Tankard::Error::ApiKeyUnauthorized] when an api key is not valid
+      #   @raise [Tankard::Error::InvalidResponse] when no data is returned fron the api
+      #   @raise [Tankard::Error::HttpError] when a status other than 200 or 401 is returned
+      #   @raise [Tankard::Error::LoadError] when multi json is unable to decode json
 
+      # Beer name to query with
+      #
+      # @param beer_name [String]
+      # @return [self] returns itself
       def name(beer_name)
         @options[:name] = beer_name
         self
       end
 
+      # Page number to request
+      #
+      # @param number [Integer]
+      # @return [self] returns itself
       def page(number)
         @options[:p] = number
         self
       end
 
+      # Additional parameters to send with the request
+      #
+      # @param options [Hash]
+      # @return [self] returns itself
+      def params(options={})
+        options.each_pair do |key,value|
+          @options[key] = value
+        end
+        self
+      end
+
       private
 
-        def options_have_page_set
-          @options.has_key?(:p)
+        def http_request_uri
+          "beers"
         end
 
-        def find_on_all_pages(block)
-          page = 0
-          options = @options.clone
-          begin
-            page += 1
-            options[:p] = page
-            response = get_request(@request, "beers", options)
-            total_pages = response["numberOfPages"].to_i
-            data = response["data"]
-            raise Tankard::Error::InvalidResponse unless data
-            data.each { |beer| block.call(beer) }
-          end while page < total_pages
+        def http_client
+          @request
         end
 
-        def find_on_single_page(block)
-          data = request_data(@request, "beers", @options)
-          raise Tankard::Error::InvalidResponse unless data
-          
-          if data.is_a?(Hash)
-            block.call(data)
-          else
-            data.each { |beer| block.call(beer) }
-          end
+        def http_request_parameters
+          @options
         end
     end
   end

data/lib/tankard/api/search.rb

@@ -0,0 +1,132 @@
+require 'hashie'
+require 'tankard/api/utils/page_finders'
+
+module Tankard
+  module Api
+    # Access for the /search route on brewerydb
+    #
+    # @see http://www.brewerydb.com/developers/docs-endpoint/search_index
+    # @author Matthew Shafer
+    class Search
+      include ::Enumerable
+      include Tankard::Api::Utils::PageFinders
+      # @!parse include ::Enumerable
+
+      # Initializes a new object
+      #
+      # @param request [Tankard::Request]
+      # @param options [Hash]
+      # @return [Tankard::Api::Search]
+      def initialize(request, options={})
+        @request = request
+        @options = Hashie::Mash.new(options)
+      end
+
+      # Calls the given block once for each result
+      #
+      # @yieldparam [Hash] hash containing individual beer information
+      # @raise [Tankard::Error::MissingParameter] when the id is not set
+      # @raise [Tankard::Error::ApiKeyUnauthorized] when an api key is not valid
+      # @raise [Tankard::Error::InvalidResponse] when no data is returned fron the api
+      # @raise [Tankard::Error::HttpError] when a status other than 200 or 401 is returned
+      # @raise [Tankard::Error::LoadError] when multi json is unable to decode json
+      def each(&block)
+        raise_if_required_options_not_set
+        super(&block)
+      end
+
+      # Query to search for
+      #
+      # @param search_query [String]
+      # @return [self] returns itself
+      def query(search_query)
+        @options.q = search_query
+        self
+      end
+
+      # Page number to request
+      #
+      # @param number [Integer]
+      # @return [self] returns itself
+      def page(number)
+        @options.p = number
+        self
+      end
+
+      # Additional parameters to send with the request
+      #
+      # @param options [Hash]
+      # @return [self] returns itself
+      def params(options={})
+        options.each_pair do |key,value|
+          @options[key] = value
+        end
+        self
+      end
+
+      # Type of search to perform
+      #
+      # @param search_type [String]
+      # @return [self] returns itself
+      def type(search_type)
+        @options.type = search_type
+        self
+      end
+
+      # search for a specific upc.
+      # sets the endpoint to upc and passes upc_code as a parameter
+      #
+      # @param upc_code [Integer]
+      # @return [self] returns itself
+      def upc(upc_code)
+        @options.code = upc_code
+        @options.endpoint = "upc"
+        self
+      end
+
+      # search for berweries around a specific point.
+      # sets the endpoint to geo/point and passes lat/lng as parameters
+      #
+      # @param latitude [Float]
+      # @param longitude [Float]
+      # @return [self] returns itself
+      def geo_point(latitude, longitude)
+        @options.lat = latitude
+        @options.lng = longitude
+        @options.endpoint = "geo/point"
+        self
+      end
+
+      private
+
+        def http_request_uri
+          endpoint = "search"
+
+          if @options.endpoint?
+            endpoint += "/#{@options.delete(:endpoint)}"
+          end
+
+          endpoint
+        end
+
+        def http_client
+          @request
+        end
+
+        def http_request_parameters
+          @options
+        end
+
+        def raise_if_required_options_not_set
+          case @options.endpoint
+          when nil
+            raise Tankard::Error::MissingParameter, "No search query set" unless @options.q?
+          when "upc"
+            raise Tankard::Error::MissingParameter, "missing parameter: code" unless @options.code?
+          when "geo/point"
+            raise Tankard::Error::MissingParameter, "missing Parameters: lat, lng" unless @options.lat? && @options.lng?
+          end
+        end
+    end
+  end
+end

data/lib/tankard/api/style.rb

@@ -0,0 +1,80 @@
+require 'hashie'
+require 'tankard/api/request/get'
+require 'tankard/api/utils/page_finders'
+require 'tankard/api/utils/find'
+
+module Tankard
+  module Api
+    # Access for the /style route on brewerydb
+    #
+    # @see http://www.brewerydb.com/developers/docs-endpoint/style_index
+    # @author Matthew Shafer
+    class Style
+      include Tankard::Api::Request::Get
+      include Tankard::Api::Utils::PageFinders
+      include Tankard::Api::Utils::Find
+      # @!parse include ::Enumerable
+
+      # Initializes a new object
+      #
+      # @param request [Tankard::Request]
+      # @param options [Hash]
+      # @return [Tankard::Api::Style]
+      def initialize(request, options={})
+        @request = request
+        @options = Hashie::Mash.new(options)
+      end
+
+      # @!method find(id_or_array, options={})
+      #   Find a single or multiple styles by their id
+      #
+      #   @param id_or_array [String, Array]
+      #   @param options [Hash]
+      #   @return [Hash, Array] if a string with a style id is passed to find then the hash of the style is returned.
+      #     if an array is passed to find an array containing hashes with each style is returned.
+      #     if a style is not found nothing for that style is returned.
+
+      # @!method each(&block)
+      #   Calls the given block once for each style
+      #
+      #   @yieldparam [Hash] hash containing individual style information
+      #   @raise [Tankard::Error::MissingParameter] when the id is not set
+      #   @raise [Tankard::Error::ApiKeyUnauthorized] when an api key is not valid
+      #   @raise [Tankard::Error::InvalidResponse] when no data is returned fron the api
+      #   @raise [Tankard::Error::HttpError] when a status other than 200 or 401 is returned
+      #   @raise [Tankard::Error::LoadError] when multi json is unable to decode json
+
+      # Style id to query
+      #
+      # @param style_id [String]
+      # @return [self] returns itself
+      def id(style_id)
+        @options.id = style_id
+        self
+      end
+
+      private
+
+        def raise_if_no_id_in_options
+          raise Tankard::Error::MissingParameter, "No style id set" unless @options.id?
+          @options.delete(:id)
+        end
+
+        def route
+          "style"
+        end
+
+        def http_request_uri
+          "#{route}/#{raise_if_no_id_in_options}"
+        end
+
+        def http_client
+          @request
+        end
+
+        def http_request_parameters
+          @options
+        end
+    end
+  end
+end

data/lib/tankard/api/styles.rb

@@ -0,0 +1,48 @@
+require 'hashie'
+require 'tankard/api/request/get'
+require 'tankard/api/utils/page_finders'
+
+module Tankard
+  module Api
+    # Access for the /styles route on brewerydb
+    #
+    # @see http://www.brewerydb.com/developers/docs-endpoint/style_index
+    # @author Matthew Shafer
+    class Styles
+      include Tankard::Api::Request::Get
+      include Tankard::Api::Utils::PageFinders
+      # @!parse include ::Enumerable
+
+      # @!method each(&block)
+      #   Calls the given block once for each style
+      #
+      #   @yieldparam [Hash] hash containing individual style information
+      #   @raise [Tankard::Error::ApiKeyUnauthorized] when an api key is not valid
+      #   @raise [Tankard::Error::InvalidResponse] when no data is returned fron the api
+      #   @raise [Tankard::Error::HttpError] when a status other than 200 or 401 is returned
+      #   @raise [Tankard::Error::LoadError] when multi json is unable to decode json
+
+      # Initializes a new object
+      #
+      # @param request [Tankard::Request]
+      # @return [Tankard::Api::Styles]
+      def initialize(request)
+        @request = request
+      end
+
+      private
+
+        def http_request_uri
+          "styles"
+        end
+
+        def http_client
+          @request
+        end
+
+        def http_request_parameters
+          {}
+        end
+    end
+  end
+end

data/lib/tankard/api/utils/find.rb

@@ -0,0 +1,35 @@
+require 'tankard/api/request/get'
+
+module Tankard
+  module Api
+    module Utils
+      module Find
+        include Tankard::Api::Request::Get
+
+        def find(id_or_array, options={})
+          options = http_request_parameters.merge!(options)
+
+          if id_or_array.is_a?(Array)
+            id_or_array.map { |id| request_data_with_nil_on_http_error(http_client, "#{route}/#{id}", options) }.compact
+          else
+            request_data_with_nil_on_http_error(http_client, "#{route}/#{id_or_array}", options)
+          end
+        end
+
+        private
+
+          def route
+            raise NoMethodError.new("Must implement and return the base route")
+          end
+
+          def http_client
+            raise NoMethodError.new("Must return the http object to make requests with")
+          end
+
+          def http_request_parameters
+            raise NoMethodError.new("Must return a hash like structure with request parameters")
+          end
+      end
+    end
+  end
+end