scoreoid 0.1.0 → 1.0.0

data/.yardopts

@@ -0,0 +1,4 @@
+-
+CHANGES.md
+LICENSE.txt
+README.md

data/CHANGES.md

@@ -1,6 +1,11 @@
 Scoreoid Ruby Change Log
 ========================
 
+2012-11-25 *v1.0.0*
+-------------------
+
+First stable release.
+
 2012-11-24 *v0.1.0*
 -------------------
 

data/README.md

@@ -19,13 +19,30 @@ Or install it yourself as:
 
     $ gem install scoreoid
 
+Usage
+-----
+
+To get started, configure Scoreoid Ruby with your API key and game ID:
+
+    require 'scoreoid'
+    
+    Scoreoid.configure(api_key: 'YOUR_API_KEY', game_id: 'YOUR_GAME_ID')
+
+Then you can start querying Scoreoid API methods:
+
+    new_players_count = Scoreoid::API.query('countPlayers', start_date: '2009-08-04')
+
+Any Scoreoid API method may be called in this mannor. See the [Scoreoid Wiki](http://wiki.scoreoid.net/category/api/) for information on available API methods.
+
+Future versions of Scoreoid Ruby will provide a more object-oriented mannor of querying data. See the `Scoreoid::Player` class for a basic example of this.
+
 Contributing
 ------------
 
 Contributions are most welcome!
 
 1. [Fork it on Bitbucket](https://bitbucket.org/xtagon/scoreoid-ruby-gem/fork)
-2. Create your feature branch (`git checkout -b my-new-feature`)
+2. Create your feature branch (`git checkout -b feature/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

data/lib/scoreoid/api.rb

@@ -0,0 +1,74 @@
+require 'date'
+
+require 'multi_json'
+require 'rest_client'
+
+module Scoreoid
+	# This exception is raised when the Scoreoid API returns an error response.
+	class APIError < StandardError; end
+
+	# A singleton class with methods for querying the Scoreoid API.
+	class API
+		class << self
+			# Query a given Scoreoid API method and return the repsonse as a string.
+			#
+			# @param [String] api_method The Scoreoid API method to query
+			# @param [Hash] params Parameters to include in the API request
+			#
+			# @return [String] The Scoreoid API response
+			#
+			# @see .query_and_parse
+			def query(api_method, params={})
+				params = self.prepare_params(params)
+				params.merge!(self.default_params ||= {})
+				RestClient.post("https://www.scoreoid.com/api/#{api_method}", params)
+			end
+
+			# Query a given Scoreoid API method and parse the JSON response.
+			#
+			# The response type is set to 'json' for you automatically.
+			#
+			# @param [String] api_method The Scoreoid API method to query
+			# @param [Hash] params Parameters to include in the API request.
+			#
+			# @raise [Scoreoid::APIError] if the Scoreoid API returns an error response.
+			#
+			# @return [Hash] The Scoreoid API response parsed into a Hash.
+			#
+			# @see .query
+			# @see .prepare_params
+			def query_and_parse(api_method, params={})
+				params = params.merge(response: 'json')
+
+				api_response = self.query(api_method, params)
+				parsed_result = MultiJson.load(api_response)
+
+				raise APIError, parsed_result['error'] if parsed_result.key? 'error'
+
+				parsed_result
+			end
+
+			# Attempt to coerce parameters into formats that the Scoreoid API expects.
+			#
+			# @param [Hash] params A hash of any parameters you wish to format.
+			#
+			# @option params [Date, Time, String] :start_date
+			# @option params [Date, Time, String] :end_date
+			#
+			# @return [Hash] The formatted parameters, ready to use in an API query.
+			def prepare_params(params)
+				params.each do |key, value|
+					if [:start_date, :end_date].include?(key) and value.respond_to?(:strftime)
+						params[key] = value.strftime '%Y-%m-%d'
+					end
+				end
+				params
+			end
+
+			# Default API request parameters used by {.query}
+			#
+			# This would normally be set with {Scoreoid.configure}
+			attr_accessor :default_params
+		end
+	end
+end

data/lib/scoreoid/player.rb

@@ -1,15 +1,22 @@
-require 'scoreoid/api_client'
-
 module Scoreoid
+	# Represents the game players.
 	class Player
-		# @return [Integer] The total number of players for the game.
-		#
-		# @example
-		#    Scoreoid.configure 'YOUR_API_KEY', 'YOUR_GAME_ID'
-		#    
-		#    puts "This game has #{Scoreoid::Player.count} players!"
-		def self.count
-			Scoreoid::APIClient.countPlayers['players']
+		# Get the number of players for the game.
+		#
+		# @example Count the total number of players
+		#    puts "This game has #{Scoreoid::Player.count} total players."
+		#
+		# @example Count new players
+		#    count = Scoreoid::Player.count(start_date: '2012-11-01')
+		#    puts "There are #{count} new players since 2012-11-01."
+		#
+		# @param [Hash] params Optional criteria for counting players.
+		# @option params [Date, Time, String] :start_date Start date ("YYYY-MM-DD" if passed as String)
+		# @option params [Date, Time, String] :end_date End date ("YYYY-MM-DD" if passed as String)
+		#
+		# @return [Integer] The number of players.
+		def self.count(params={})
+			Scoreoid::API.query_and_parse('countPlayers', params)['players']
 		end
 	end
 end

data/lib/scoreoid/version.rb

@@ -1,3 +1,4 @@
 module Scoreoid
-	VERSION = '0.1.0'
+	# The currently loaded Scoreoid Ruby version.
+	VERSION = '1.0.0'
 end

data/lib/scoreoid.rb

@@ -1,20 +1,28 @@
 require 'scoreoid/version'
-require 'scoreoid/api_client'
+require 'scoreoid/api'
 require 'scoreoid/player'
 
+# The main Scoreoid Ruby namespace.
+#
+# To get started, set your Scoreoid API key and game ID with {Scoreoid.configure}.
+# Then you can use {Scoreoid::API.query_and_parse} to query any Scoreoid API method.
+# See the {http://wiki.scoreoid.net/category/api/ Scoreoid Wiki} for information
+# on available API methods.
 module Scoreoid
-	# This exception is raised when Scoreoid Ruby is used without first being configured.
-	# To configure Scoreoid Ruby, see {Scoreoid.configure}.
-	class NotConfiguredError < RuntimeError; end
-
-	# Configure Scoreoid Ruby with your Scoreoid API key and game ID.
-	# This must be done once before calling any Scoreoid API methods.
+	# Configure Scoreoid Ruby by setting default API request parameters.
+	# You can set any parameters here, but it is only recommended to set
+	# :api_key and :game_id as they are common to all API methods.
+	#
+	# @example Setting your API key and game ID from environment variables:
+	#    Scoreoid.configure(api_key: ENV['SCOREOID_API_KEY'], game_id: ENV['SCOREOID_GAME_ID'])
+	#
+	# @param [Hash] params A hash of default parameters to set
 	#
-	# @example
-	#    Scoreoid.configure(ENV['SCOREOID_API_KEY'], ENV['SCOREOID_GAME_ID'])
+	# @option params [String] :api_key Your Scoreoid API key
+	# @option params [String] :game_id Your Scoreoid game ID
 	#
-	# @return [Hash] A hash of the parameters you just configured.
-	def self.configure(api_key, game_id)
-		Scoreoid::APIClient.default_params = {api_key: api_key, game_id: game_id}
+	# @return [Hash] The parameters you just set
+	def self.configure(params)
+		Scoreoid::API.default_params = params
 	end
 end

data/scoreoid.gemspec

@@ -9,6 +9,7 @@ Gem::Specification.new do |gem|
 	gem.author = 'Justin Workman'
 	gem.email = 'xtagon@gmail.com'
 	gem.summary = 'Scoreoid Ruby is a wrapper for the Scoreoid API.'
+	gem.license = 'MIT'
 
 	gem.required_ruby_version = '1.9.2'
 	gem.add_runtime_dependency 'multi_json', '~> 1.3'

data/spec/api_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe Scoreoid::API do
+	before :each do
+		# Tests should be run independantly, so I don't understand why this is neccessary :/
+		Scoreoid.configure({})
+	end
+
+	describe '.query' do
+		it 'should query a Scoreoid API method and return the response as a string' do
+			example_response = %q({"players": 7})
+			given_params = {response: 'json', api_key: 'API_KEY', game_id: 'GAME_ID'}
+
+			RestClient.stub(:post).and_return(example_response)
+			RestClient.should_receive(:post).with('https://www.scoreoid.com/api/playerCount', given_params)
+
+			api_response = Scoreoid::API.query('playerCount', given_params)
+			api_response.should be_instance_of String
+			api_response.should == example_response
+		end
+
+		it 'should use default params if they are set' do
+			example_response = %q({"players": 7})
+			default_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
+			given_params = {start_date: '2009-01-01'}
+			expected_params = default_params.merge(given_params)
+
+			RestClient.stub(:post).and_return(example_response)
+			RestClient.should_receive(:post).with('https://www.scoreoid.com/api/playerCount', expected_params)
+
+			Scoreoid.configure(default_params)
+			Scoreoid::API.query('playerCount', given_params)
+		end
+
+		it 'should format the parameters before sending' do
+			example_response = %q({"players": 7})
+			given_params = {start_date: Date.new(2010, 1, 1), end_date: Date.new(2012, 2, 3).to_time}
+			formatted_params = {start_date: '2010-01-01', end_date: '2012-02-03'}
+
+			RestClient.stub(:post).and_return(example_response)
+			RestClient.should_receive(:post).with('https://www.scoreoid.com/api/playerCount', formatted_params)
+
+			Scoreoid::API.query('playerCount', given_params)
+		end
+	end
+
+	describe '.query_and_parse' do
+		it 'should query a Scoreoid API method and parse the JSON response' do
+			given_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
+			params_plus_response_param = given_params.merge(response: 'json')
+
+			Scoreoid::API.stub(:query).and_return(%q({"players": 7}))
+			Scoreoid::API.should_receive(:query).with('playerCount', params_plus_response_param)
+
+			parsed_response = Scoreoid::API.query_and_parse('playerCount', given_params)
+			parsed_response.should be_instance_of Hash
+			parsed_response.should == {'players' => 7}
+		end
+
+		it 'should raise an error if the Scoreoid API returned one in the JSON' do
+			response_with_error = %q({"error": "The API key is broken or the game is not active"})
+
+			Scoreoid::API.stub(:query).and_return(response_with_error)
+			
+			expect do
+				Scoreoid::API.query_and_parse('getScores')
+			end.to raise_error(Scoreoid::APIError, 'The API key is broken or the game is not active')
+		end
+	end
+end

data/spec/player_spec.rb

@@ -1,10 +1,20 @@
 require 'spec_helper'
 
 describe Scoreoid::Player do
-	it 'should count players' do
-		Scoreoid::APIClient.should_receive(:countPlayers).and_return({'players' => 7})
-		how_many_players = Scoreoid::Player.count
-		how_many_players.should be_kind_of Integer
-		how_many_players.should >= 0
+	describe '.count' do
+		it 'should count players with no query parameters' do
+			Scoreoid::API.stub(:query_and_parse).and_return({'players' => 7})
+			Scoreoid::API.should_receive(:query_and_parse).with('countPlayers', {})
+			count = Scoreoid::Player.count
+			count.should == 7
+		end
+
+		it 'should count players with query parameters' do
+			params = {start_date: '2011-11-01', end_date: Time.now}
+			Scoreoid::API.stub(:query_and_parse).and_return({'players' => 7})
+			Scoreoid::API.should_receive(:query_and_parse).with('countPlayers', params)
+			count = Scoreoid::Player.count(params)
+			count.should == 7
+		end
 	end
 end

data/spec/scoreoid_spec.rb

@@ -1,14 +1,12 @@
 require 'spec_helper'
 
 describe Scoreoid do
-	describe 'self.configure' do
-		it 'should set Scoreoid API key and game ID parameters' do
-			Scoreoid.configure('API_KEY', 'GAME_ID')
-			default_params = Scoreoid::APIClient.class_variable_get(:@@default_params)
-			default_params.key?(:api_key).should be_true
-			default_params.key?(:game_id).should be_true
-			default_params[:api_key].should == 'API_KEY'
-			default_params[:game_id].should == 'GAME_ID'
+	describe '.configure' do
+		it 'should set default API parameters' do
+			default_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
+			Scoreoid::API.should_receive(:default_params=).and_return(default_params)
+			returned_default_params = Scoreoid.configure(default_params)
+			returned_default_params.should == default_params
 		end
 	end
 end

data/spec/spec_helper.rb

@@ -2,13 +2,13 @@ require 'scoreoid'
 
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
-  config.treat_symbols_as_metadata_keys_with_true_values = true
-  config.run_all_when_everything_filtered = true
-  config.filter_run :focus
+	config.treat_symbols_as_metadata_keys_with_true_values = true
+	config.run_all_when_everything_filtered = true
+	config.filter_run :focus
 
-  # Run specs in random order to surface order dependencies. If you find an
-  # order dependency and want to debug it, you can fix the order by providing
-  # the seed, which is printed after each run.
-  #     --seed 1234
-  #config.order = 'random'
+	# Run specs in random order to surface order dependencies. If you find an
+	# order dependency and want to debug it, you can fix the order by providing
+	# the seed, which is printed after each run.
+	#     --seed 1234
+	config.order = 'random'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scoreoid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -51,23 +51,25 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .yardopts
 - CHANGES.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/scoreoid.rb
-- lib/scoreoid/api_client.rb
+- lib/scoreoid/api.rb
 - lib/scoreoid/player.rb
 - lib/scoreoid/version.rb
 - scoreoid.gemspec
-- spec/api_client_spec.rb
+- spec/api_spec.rb
 - spec/player_spec.rb
 - spec/scoreoid_spec.rb
 - spec/spec_helper.rb
 - spec/version_spec.rb
 homepage: 
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -91,7 +93,7 @@ signing_key:
 specification_version: 3
 summary: Scoreoid Ruby is a wrapper for the Scoreoid API.
 test_files:
-- spec/api_client_spec.rb
+- spec/api_spec.rb
 - spec/player_spec.rb
 - spec/scoreoid_spec.rb
 - spec/spec_helper.rb

data/lib/scoreoid/api_client.rb

@@ -1,61 +0,0 @@
-require 'multi_json'
-require 'rest_client'
-
-module Scoreoid
-	# This exception is raised when the Scoreoid API returns an error response.
-	class APIError < StandardError; end
-
-	class APIClient
-		REQUIRED_PARAMETERS = [:api_key, :game_id]
-
-		@@default_params = Hash.new
-
-		# Set the default request parameters.
-		# Normally you would not call this directly, but instead use {Scoreoid.configure}.
-		#
-		# @param [Hash] params A hash of the default parameters to set.
-		#
-		# @return [Hash] Default request parameters.
-		def self.default_params= params
-			@@default_params = params
-		end
-
-		# Get the default request parameters.
-		#
-		# @raise [Scoreoid::NotConfiguredError] if required parameters are not set.
-		#
-		# @return Default request paremeters.
-		def self.default_params
-			REQUIRED_PARAMETERS.each do |param_key|
-				unless @@default_params.key?(param_key)
-					raise Scoreoid::NotConfiguredError, "Scoreoid Ruby has not been configured correctly. Please set the API key and game ID with Scoreoid.configure(api_key, game_id) before using this library."
-				end
-			end
-
-			@@default_params
-		end
-
-		# Query the Scoreoid API and return the un-parsed response.
-		# This is used internally and you should only call it if you really know what you're doing.
-		def self.api_call(api_method)
-			# Add :response => 'json' to the post parameters because the entire library
-			# epects JSON responses.
-			post_params = self.default_params.merge({response: 'json'})
-			RestClient.post("https://www.scoreoid.com/api/#{api_method}", post_params)
-		end
-
-		# Query the Scoreoid API method "countPlayers()" and parse the response.
-		#
-		# @see Scoreoid::Player.count
-		#
-		# @raise [Scoreoid::APIError] if the Scoreoid API returns an error response.
-		#
-		# @return [Hash] The Scoreoid API response parsed into a Hash.
-		def self.countPlayers
-			api_response = self.api_call('countPlayers')
-			json = MultiJson.load(api_response)
-			raise APIError, json['error'] if json.key? 'error'
-			json
-		end
-	end
-end

data/spec/api_client_spec.rb

@@ -1,80 +0,0 @@
-require 'spec_helper'
-
-describe Scoreoid::APIClient do
-	describe 'self.default_params' do
-		it 'should be set to empty hash by default' do
-			Scoreoid::APIClient.class_variable_get(:@@default_params).should be_instance_of Hash
-		end
-
-		context 'setting default parameters' do
-			it 'should set default parameters when required parameters are provided' do
-				example_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
-				Scoreoid::APIClient.default_params = example_params
-				Scoreoid::APIClient.class_variable_get(:@@default_params).should == example_params
-			end
-		end
-
-		context 'getting default parameters' do
-			it 'returns exactly the parameters which were set' do
-				example_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
-				Scoreoid::APIClient.default_params = example_params
-				Scoreoid::APIClient.default_params.should == example_params
-			end
-
-			it 'raises an error if required parameters are absent' do
-				Scoreoid::APIClient.default_params = {api_key: 'API_KEY'} # missing :game_id
-				expect do
-					Scoreoid::APIClient.default_params
-				end.to raise_error Scoreoid::NotConfiguredError
-
-				Scoreoid::APIClient.default_params = {game_key: 'GAME_ID'} # missing :api_key
-				expect do
-					Scoreoid::APIClient.default_params
-				end.to raise_error Scoreoid::NotConfiguredError
-			end
-		end
-	end
-
-	describe 'self.api_call' do
-		it 'should call Scoreoid API methods with default parameters' do
-			# We're testing that :response => 'json' is added to the parameters
-			# because the entire library expects JSON responses.
-
-			example_response = %q({"players": 7})
-			default_params = {api_key: 'API_KEY', game_id: 'GAME_ID'}
-			post_params = default_params.merge({response: 'json'})
-
-			Scoreoid::APIClient.stub(:default_params).and_return(default_params)
-			RestClient.stub(:post).and_return(example_response)
-			RestClient.should_receive(:post).with('https://www.scoreoid.com/api/playerCount', post_params)
-
-			api_response = Scoreoid::APIClient.api_call('playerCount')
-			api_response.should be_instance_of String
-			api_response.should == example_response
-		end
-	end
-
-	describe 'self.countPlayers' do
-		it 'should call the countPlayers() Scoreoid API method' do
-			Scoreoid::APIClient.stub(:api_call).and_return(%q({"players":7}))
-			Scoreoid::APIClient.should_receive(:api_call).with('countPlayers')
-			Scoreoid::APIClient.countPlayers
-		end
-
-		it 'should parse the JSON result into a Hash' do
-			Scoreoid::APIClient.stub(:api_call).and_return(%q({"players":7}))
-			result = Scoreoid::APIClient.countPlayers
-			result.should be_instance_of Hash
-			result.should == {'players' => 7}
-		end
-
-		it 'should raise an error if the Scoreoid API returns an error' do
-			example_response = %q({"error": "The API key is broken or the game is not active"})
-			Scoreoid::APIClient.stub(:api_call).and_return(example_response)
-			
-			expect do
-				Scoreoid::APIClient.countPlayers
-			end.to raise_error(Scoreoid::APIError, 'The API key is broken or the game is not active')
-		end
-	end
-end