yelp 1.0.0 → 2.0.0

data/README.md

@@ -0,0 +1,152 @@
+# yelp-ruby
+
+This is a Ruby Gem for the Yelp API. It'll simplifies the process of consuming data from the Yelp API for developers using Ruby. The library encompasses both Search and Business API functions.
+
+Please remember to read and follow the [Terms of Use](http://www.yelp.com/developers/getting_started/api_terms) and [display requirements](http://www.yelp.com/developers/getting_started/display_requirements) before creating your applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'yelp', require: 'yelp'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yelp
+
+## Usage
+
+### Basic usage
+
+The gem uses a client model to query against the API. You create and configure a client with your API keys and make requests through that.
+
+```
+require 'yelp'
+
+client = Yelp::Client.new({ consumer_key: YOUR_CONSUMER_KEY,
+                            consumer_secret: YOUR_CONSUMER_SECRET,
+                            token: YOUR_TOKEN,
+                            token_secret: YOUR_TOKEN_SECRET
+                          })
+```
+
+Alternatively, you can also globally configure the client using a configure
+block, and access a client singleton using `Yelp.client`.  If you intend to
+use the gem with Rails, the client should be configured in an initializer.
+
+```
+require 'yelp'
+
+Yelp.client.configure do |config|
+  config.consumer_key = YOUR_CONSUMER_KEY
+  config.consumer_secret = YOUR_CONSUMER_SECRET
+  config.token = YOUR_TOKEN
+  config.token_secret = YOUR_TOKEN_SECRET
+end
+
+Yelp.client.search('San Francisco', { term: 'food' })
+```
+
+After creating the client you're able to make requests to either the Search API or Business API. Note: all four keys are required for making requests against the Yelp API. If you need any keys sign up and get access from [http://www.yelp.com/developers](http://www.yelp.com/developers).
+
+### [Search API](http://www.yelp.com/developers/documentation/v2/search_api)
+
+Once you have a client you can use ``#search`` to make a request to the Search API.
+
+```
+client.search('San Francisco')
+```
+
+You can also pass in general params and locale options to the method as hashes
+
+```
+params = { term: 'food',
+           limit: 3,
+           category_filter: 'discgolf'
+         }
+
+locale = { lang: 'fr' }
+
+client.search('San Francisco', params, locale)
+```
+
+Key names and options for params and locale match the documented names on the [Yelp Search API](http://www.yelp.com/developers/documentation/v2/search_api)
+
+Additionally there are two more search methods for searching by a [bounding box](http://www.yelp.com/developers/documentation/v2/search_api#searchGBB) or for [geographical coordinates](http://www.yelp.com/developers/documentation/v2/search_api#searchGC):
+
+```
+# bounding box
+bounding_box = { sw_latitude: 37.7577, sw_longitude: -122.4376, ne_latitude: 37.785381, ne_longitude: -122.391681 }
+client.search_by_bounding_box(bounding_box, params, locale)
+
+# coordinates
+coordinates = { latitude: 37.7577, longitude: -122.4376 }
+client.search_by_coordinates(coordinates, params, locale)
+```
+
+### [Business API](http://www.yelp.com/developers/documentation/v2/business)
+
+To use the Business API after you have a client you just need to call ``#business`` with a business id
+
+```
+client.business('yelp-san-francisco')
+```
+
+You can pass in locale information as well
+
+```
+locale = { lang: 'fr' }
+
+client.business('yelp-san-francisco', locale)
+```
+
+## Responses
+
+Responses from the API are all parsed and converted into Ruby objects. You're able to access information using dot-notation
+
+```
+## search
+response = client.search('San Francisco')
+
+response.businesses
+# [<Business 1>, <Business 2>, ...]
+
+response.businesses[0].name
+# "Kim Makoi, DC"
+
+response.businesses[0].rating
+# 5.0
+
+
+## business
+response = client.business('yelp-san-francisco')
+
+response.name
+# Yelp
+
+response.categories
+# [["Local Flavor", "localflavor"], ["Mass Media", "massmedia"]]
+```
+
+For specific response values check out the docs for the [search api](http://www.yelp.com/developers/documentation/v2/search_api#rValue) and the [business api](http://www.yelp.com/developers/documentation/v2/business#rValue)
+
+## Contributing
+
+1. Fork it ( http://github.com/yelp/yelp-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### Git Workflow
+
+We are using the [git flow](http://nvie.com/posts/a-successful-git-branching-model/)
+workflow. Atlassian has a [solid overview](https://www.atlassian.com/git/workflows#!workflow-gitflow).
+Essentially, new development is merged into the develop branch from feature
+branches, then merged from develop to a release branch, then to master from
+the release branch. Master should always contain the most recently released
+version of the gem.

data/Rakefile

@@ -1,25 +1,5 @@
-require 'rubygems'
-require 'hoe'
-$:.unshift(File.dirname(__FILE__) + "/lib")
-require 'yelp'
+require "bundler/gem_tasks"
 
-Hoe.spec('yelp') do |p|
-  self.version = Yelp::VERSION
-  self.rubyforge_name = 'yelp'
-  self.author = 'Walter Korman'
-  self.email = 'shaper@fatgoose.com'
-  self.extra_deps << [ 'json', '>= 1.1.1' ]
-  self.summary = 'An object-oriented interface to the Yelp Developer API.'
-  self.description = <<EDOC
-The yelp rubygem provides a Ruby object-oriented interface to the Yelp 
-REST API described in detail at:
-
-http://www.yelp.com/developers/getting_started
-EDOC
-  self.url = 'http://rubyforge.org/projects/yelp'
-  self.changes = p.paragraphs_of('CHANGELOG.rdoc', 0..1).join("\n\n")
-  self.remote_rdoc_dir = '' # Release to root
-  self.readme_file = 'README.rdoc'
-  self.history_file = 'CHANGELOG.rdoc'
-  self.extra_rdoc_files = [ 'CHANGELOG.rdoc', 'README.rdoc' ]
-end
+Dir["tasks/**/*.rake"].each do |file|
+  load(file)
+end

data/lib/yelp.rb

@@ -1,16 +1,21 @@
+require 'yelp/version'
 require 'yelp/client'
-require 'yelp/record'
-require 'yelp/request'
-require 'yelp/response_format'
-require 'yelp/neighborhood/request/base'
-require 'yelp/neighborhood/request/geo_point'
-require 'yelp/neighborhood/request/location'
-require 'yelp/phone/request/number'
-require 'yelp/review/request/base'
-require 'yelp/review/request/bounding_box'
-require 'yelp/review/request/geo_point'
-require 'yelp/review/request/location'
 
-class Yelp
-  VERSION = '1.0.0'
+module Yelp
+  # Returns an initially-unconfigured instance of the client.
+  # @return [Client] an instance of the client
+  #
+  # @example Configuring and using the client
+  #   Yelp.client.configure do |config|
+  #     config.consumer_key = 'abc'
+  #     config.consumer_secret = 'def'
+  #     config.token = 'ghi'
+  #     config.token_secret = 'jkl'
+  #   end
+  #
+  #   Yelp.client.search('San Francisco', { term: 'food' })
+  #
+  def self.client
+    @client ||= Yelp::Client.new
+  end
 end

data/lib/yelp/burst_struct.rb

@@ -0,0 +1,51 @@
+module BurstStruct
+  class Burst
+    def initialize(hash = {})
+      @hash = hash
+    end
+
+    def method_missing(method_name, *arguments, &block)
+      key = find_key(method_name)
+
+      if key
+        return_or_build_struct(key)
+      else
+        super
+      end
+    end
+
+    def respond_to?(method_name, include_private = false)
+      @hash.keys.include?(method_name) || super
+    end
+
+    def self.convert_array(array)
+      array.map do |item|
+        case item
+        when Hash
+          Burst.new(item)
+        when Array
+          Burst.convert_array(item)
+        else
+          item
+        end
+      end
+    end
+
+    def to_json(options = {})
+      JSON.generate(@hash)
+    end
+
+    private
+
+    def return_or_build_struct(method_name)
+      return Burst.new(@hash[method_name])           if @hash[method_name].is_a?(Hash)
+      return Burst.convert_array(@hash[method_name]) if @hash[method_name].is_a?(Array)
+      @hash[method_name]
+    end
+
+    def find_key(method_name)
+      return method_name.to_sym if @hash.keys.include? method_name.to_sym
+      return method_name.to_s   if @hash.keys.include? method_name.to_s
+    end
+  end
+end

data/lib/yelp/client.rb

@@ -1,105 +1,105 @@
-require 'cgi'
-require 'logger'
-require 'open-uri'
-require 'rubygems'
-require 'json'
-require 'yaml'
-require 'zlib'
+require 'faraday'
+require 'faraday_middleware'
 
-class Yelp
-  # Provides access to the Yelp search facilities as documented at:
-  #
-  # http://www.yelp.com/developers/documentation
-  #
-  # Example usage:
-  #
-  #    client = Yelp::Client.new
-  #    request = Yelp::Review::Request::Location.new(
-  #                 :address => '650 Mission St',
-  #                 :city => 'San Francisco',
-  #                 :state => 'CA',
-  #                 :radius => 2,
-  #                 :term => 'cream puffs',
-  #                 :yws_id => 'YOUR_YWSID_HERE')
-  #    response = client.search(request)
-  #
-  # By default, response content is formatted as a Ruby hash converted from
-  # Yelp's source JSON response content.  Alternate response formats can be
-  # specified on request record construction via the Yelp::Request
-  # +response_format+ parameter, available in all request record types.
-  #
+require 'yelp/burst_struct'
+require 'yelp/configuration'
+require 'yelp/error'
+require 'yelp/endpoint/business'
+require 'yelp/endpoint/search'
+
+module Yelp
   class Client
-    # allows specifying the user agent string to submit with search requests
-    attr_accessor :agent
-    
-    # whether debug mode is enabled for logging purposes, defaulting to false
-    attr_accessor :debug
-    
-    # the Logger compatible object with which log messages are outputted,
-    # defaulting to output to STDOUT
-    attr_accessor :logger
+    API_HOST  = 'http://api.yelp.com'
+    REQUEST_CLASSES = [ Yelp::Endpoint::Search,
+                        Yelp::Endpoint::Business ]
+
+    attr_reader :configuration
+
+    # Creates an instance of the Yelp client
+    # @param options [Hash, nil] a hash of the consumer key, consumer
+    #   secret, token, and token secret
+    # @return [Client] a new client initialized with the keys
+    def initialize(options = nil)
+      @configuration = nil
+      define_request_methods
+
+      unless options.nil?
+        @configuration = Configuration.new(options)
+        check_api_keys
+      end
+    end
 
-    # the default user agent submitted with search requests
-    DEFAULT_AGENT = 'yelp for Ruby (http://www.rubyforge.org/projects/yelp/)'
+    # Configure the API client
+    # @yield [Configuration] a configuration object
+    # @raise [MissingAPIKeys] if the configuration is invalid
+    # @example Simple configuration
+    #   Yelp.client.configure do |config|
+    #     config.consumer_key = 'abc'
+    #     config.consumer_secret = 'def'
+    #     config.token = 'ghi'
+    #     config.token_secret = 'jkl'
+    #   end
+    def configure
+      raise AlreadyConfigured unless @configuration.nil?
 
-    # Constructs a new client that uses the supplied YWSID for submitting
-    # search requests.
-    #
-    def initialize
-      @agent = DEFAULT_AGENT
-      @debug = false
-      @logger = nil
+      @configuration = Configuration.new
+      yield(@configuration)
+      check_api_keys
     end
-    
-    # Submits the supplied search request to Yelp and returns the response in
-    # the format specified by the request.
-    #
-    def search (request)
-      # build the full set of hash params with which the url is constructed
-      params = request.to_yelp_params
 
-      # construct the url with which we obtain results
-      url = build_url(request.base_url, params)
-      debug_msg "submitting search [url=#{url}, request=#{request.to_yaml}]."
+    # Checks that all the keys needed were given
+    def check_api_keys
+      if configuration.nil? || !configuration.valid?
+        @configuration = nil
+        raise MissingAPIKeys
+      else
+        # Freeze the configuration so it cannot be modified once the gem is
+        # configured.  This prevents the configuration changing while the gem
+        # is operating, which would necessitate invalidating various caches.
+        @configuration.freeze
+      end
+    end
 
-      # submit the http request for the results
-      http_params = { 'User-Agent' => @agent }
-      http_params['Accept-Encoding'] = 'gzip,deflate' if request.compress_response?
-      source = open(url, http_params)
+    # API connection
+    def connection
+      return @connection if instance_variable_defined?(:@connection)
 
-      # read the response content
-      content = (request.compress_response?) ? Zlib::GzipReader.new(source).read : source.read
-      debug_msg((request.response_format.serialized?) ? "received response [content_length=#{content.length}]." : "received response [content_length=#{content.length}, content=#{content}].")
+      check_api_keys
+      @connection = Faraday.new(API_HOST) do |conn|
+        # Use the Faraday OAuth middleware for OAuth 1.0 requests
+        conn.request :oauth, @configuration.auth_keys
 
-      # format the output as specified in the request
-      format_content(request.response_format, content)
+        # Using default http library, had to specify to get working
+        conn.adapter :net_http
+      end
     end
 
-    protected
+    private
 
-      def format_content (response_format, content)
-        (response_format == Yelp::ResponseFormat::JSON_TO_RUBY) ? JSON.parse(content) : content
+    # This goes through each endpoint class and creates singletone methods
+    # on the client that query those classes. We do this to avoid possible
+    # namespace collisions in the future when adding new classes
+    def define_request_methods
+      REQUEST_CLASSES.each do |request_class|
+        endpoint_instance = request_class.new(self)
+        create_methods_from_instance(endpoint_instance)
       end
+    end
 
-      def debug_msg (message)
-        return if !@debug
-        @logger = Logger.new(STDOUT) if (!@logger)
-        @logger.debug message
+    # Loop through all of the endpoint instances' public singleton methods to
+    # add the method to client
+    def create_methods_from_instance(instance)
+      instance.public_methods(false).each do |method_name|
+        add_method(instance, method_name)
       end
+    end
 
-      def build_url (base_url, params)
-        url = base_url.clone
-        url << '?'
-        param_count = 0
-        params.each do |key, value|
-          next if value.nil?
-          url << '&' if (param_count > 0)
-          key_str = (params[key].kind_of?(Array)) ? 
-            params[key].map { |k| CGI.escape(k.to_s) }.join("+") : CGI.escape(params[key].to_s)
-          url << "#{CGI.escape(key.to_s)}=#{key_str}"
-          param_count += 1
-        end
-        url
+    # Define the method on the client and send it to the endpoint instance
+    # with the args passed in
+    def add_method(instance, method_name)
+      define_singleton_method(method_name) do |*args|
+        instance.public_send(method_name, *args)
       end
+    end
   end
 end