Fixed the documentation so rdoc generates a useful site.

Bumped the version to 2.0.0 for the Historics and Push release.

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 sftp-config.json
 .idea/
+rdoc/

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 MediaSift Ltd
+Copyright (c) 2011-2012 MediaSift Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,7 +2,7 @@ DataSift
 ========
 
 The official Ruby library for accessing the DataSift API. See
-http://datasift.net for full details and to sign up for an account.
+http://datasift.com/ for full details and to sign up for an account.
 
 The examples use the username and API key in config.yml unless otherwise noted.
 
@@ -19,7 +19,7 @@ If you're using the source you'll need to install the dependencies.
 sudo gem install yajl-ruby rest-client
 
 The library will use SSL connections by default. While we recommend using SSL
-you may disable it if required by passing false as the third parameter when
+you may disable it if r§equired by passing false as the third parameter when
 creating a user, or by calling user.enableSSL(false) on the user object.
 
 Simple example
@@ -56,7 +56,9 @@ more details.
 Changelog
 ---------
 
-* v.1.5.0 Added getBalance to the User class [joncooper] (2012-05-24)
+* v.2.0.0 Added support for Historics queries and Push delivery (2012-08-31)
+
+* v.1.5.0 Added getBalance to the User class [joncooper](https://github.com/joncooper) (2012-05-24)
 
 * v.1.4.1 Fixed a minor bug in the SSL support (2012-05-15)
 

VERSION

@@ -1 +1 @@
-1.5.0
+2.0.0

datasift.gemspec

@@ -2,17 +2,17 @@
 $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
-	s.name			= 'datasift'
-	s.version		= File.open('VERSION').first
+	s.name    = 'datasift'
+	s.version = File.open('VERSION').first
 
-	s.authors		= ['DataSift']
-	s.email			= ['support@datasift.net']
-	s.description	= %q{The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.}
-	s.summary		= %q{DataSift is a simple wrapper for the DataSift API.}
-	s.homepage		= 'http://github.com/datasift/datasift-ruby'
+	s.authors     = ['DataSift']
+	s.email       = ['support@datasift.net']
+	s.description = %q{The official Ruby library for accessing the DataSift API. See http://datasift.com/ for full details and to sign up for an account.}
+	s.summary     = %q{DataSift is a simple wrapper for the DataSift API.}
+	s.homepage    = 'http://github.com/datasift/datasift-ruby'
 
-	s.platform					= Gem::Platform::RUBY
-	s.rubygems_version			= %q{1.3.6}
+	s.platform                  = Gem::Platform::RUBY
+	s.rubygems_version          = %q{1.3.6}
 	s.required_rubygems_version	= Gem::Requirement.new(">= 1.3.6") if s.respond_to? :required_rubygems_version=
 
 	s.add_runtime_dependency('rest-client', '~> 1.6.3')
@@ -21,7 +21,7 @@ Gem::Specification.new do |s|
 	s.add_development_dependency('shoulda', '~> 2.11.3')
 	s.add_development_dependency('rspec', '~> 2.6.0')
 
-	s.files			= `git ls-files`.split("\n")
-	s.test_files	= `git ls-files -- {test,spec,features}/*`.split("\n")
+	s.files         = `git ls-files`.split("\n")
+	s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
 	s.require_paths = ["lib"]
 end

lib/DataSift/apiclient.rb

@@ -1,32 +1,22 @@
-#
-# apiclient.rb - This file contains the ApiClient class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The ApiClient class wraps the functionality that makes calls to the
-# DataSift API.
-
 require 'rest_client'
 require 'yajl'
 
 module DataSift
-	# ApiCLient class.
-	#
-	# == Introduction
-	#
-	# The ApiClient class wraps the functionality that makes calls to the
-	# DataSift API.
-	#
+	#The ApiClient class wraps the functionality that makes calls to the
+	#DataSift API.
 	class ApiClient
-		# Make a call to a DataSift API endpoint.
-		# === Parameters
-		#
-		# * +endpoint+ - The endpoint of the API call.
-		# * +params+ - The parameters to be passed along with the request.
-		# * +username+ - The username for the Auth header
-		# * +api_key+ - The API key for the Auth header
+		#Make a call to a DataSift API endpoint.
+		#=== Parameters
+		#* +endpoint+ - The endpoint of the API call.
+		#* +params+ - The parameters to be passed along with the request.
+		#* +username+ - The username for the Auth header
+		#* +api_key+ - The API key for the Auth header
+		#=== Returns
+		#A Hash contatining...
+		#* +response_code+ - The HTTP response code.
+		#* +data+ - A Hash containing the response data.
+		#* +rate_limit+ - The total API credits you get per hour.
+		#* +rate_limit_remaining+ - The number of API credits you have remaining for this hour.
 		def call(username, api_key, endpoint, params = {}, user_agent = 'DataSiftPHP/0.0')
 			# Build the full endpoint URL
 			url = 'http://' + User::API_BASE_URL + endpoint
@@ -64,11 +54,16 @@ def call(username, api_key, endpoint, params = {}, user_agent = 'DataSiftPHP/0.0
 				retval['data'] = Yajl::Parser.parse(err.response)
 			end
 
-			retval
+			return retval
 		end
 
 	private
 
+		#Convert a Hash to an HTTP query string.
+		#=== Parameters
+		#* +hash+ - The Hash to convert.
+		#=== Returns
+		#A string containing the equivalent query string.
 		def hashToQuerystring(hash)
 			hash.keys.inject('') do |query_string, key|
 				query_string << '&' unless key == hash.keys.first

lib/DataSift/definition.rb

@@ -1,50 +1,34 @@
-#
-# definition.rb - This file contains the Definition class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The User class represents a user of the API. Applications should start their
-# API interactions by creating an instance of this class. Once initialised it
-# provides factory methods for all of the functionality in the API.
-
 require 'date'
 
 module DataSift
-
-	# Definition class.
-	#
-	# == Introduction
-	#
-	# The Definition class represents a stream definition.
-	#
+	#The Definition class represents a stream definition.
 	class Definition
-		attr_reader :csdl, :total_dpu, :created_at
-
-		# Constructor. A User object is required, and you can optionally supply a
-		# default CSDL string.
-		# === Parameters
-		#
-		# * +user+ - The DataSift::User object.
-		# * +csdl+ - Optional default CSDL string.
-		# * +hash+ - Optional default hash string.
-		#
+		#The CSDL for this Definition.
+		attr_reader :csdl
+
+		#Constructor. A User object is required, and you can optionally supply a
+		#default CSDL string.
+		#=== Parameters
+		#* +user+ - The DataSift::User object.
+		#* +csdl+ - Optional default CSDL string.
+		#* +hash+ - Optional default hash string.
 		def initialize(user, csdl = '', hash = false)
 			raise InvalidDataError, 'Please supply a valid User object when creating a Definition object.' unless user.is_a? DataSift::User
 			@user = user
 			clearHash()
 			@hash = hash
 			self.csdl = csdl
+			@total_dpu = false
+			@created_at = false
 		end
 
-		# CSDL getter
+		#CSDL getter
 		def csdl
 			raise InvalidDataError, 'The CSDL is not available' unless !@csdl.nil?
-			@csdl
+			return @csdl
 		end
 
-		# CSDL setter. Strips the incoming string and resets the hash if it's changed.
+		#CSDL setter. Strips the incoming string and resets the hash if it's changed.
 		def csdl=(csdl)
 			if csdl.nil?
 				@csdl = nil
@@ -56,27 +40,39 @@ def csdl=(csdl)
 			end
 		end
 
-		# Hash getter. If the hash has not yet been obtained the CSDL will be
-		# compiled first.
+		#Total DPU getter.
+		def total_dpu
+			compile() unless @total_dpu
+			return @total_dpu
+		end
+
+		#Created at getter.
+		def created_at
+			compile() unless @created_at
+			return @created_at
+		end
+
+		#Hash getter. If the hash has not yet been obtained the CSDL will be
+		#compiled first.
 		def hash
 			if @hash == false
 				compile()
 			end
 
-			@hash
+			return @hash
 		end
 
-		# Reset the hash to false. The effect of this is to mark the definition as
-		# requiring compilation.
+		#Reset the hash to false. The effect of this is to mark the definition as
+		#requiring compilation.
 		def clearHash()
 			@csdl = '' unless !@csdl.nil?
 			@hash = false
 			@total_dpu = false
 			@created_at = false
 		end
 
-		# Call the DataSift API to compile this definition. On success it will
-		# store the returned hash.
+		#Call the DataSift API to compile this definition. On success it will
+		#store the returned hash.
 		def compile()
 			raise InvalidDataError, 'Cannot compile an empty definition.' unless @csdl.length > 0
 
@@ -112,23 +108,54 @@ def compile()
 			end
 		end
 
-		# Call the DataSift API to get the DPU for this definition. Returns an
-		# array containing...
-		#   detail => The breakdown of running the rule
-		#   dpu => The total DPU of the rule
-		#
+		#Call the DataSift API to validate this definition. On success it will
+		#store the details in the response.
+		def validate()
+			raise InvalidDataError, 'Cannot validate an empty definition.' unless @csdl.length > 0
+
+			begin
+				res = @user.callAPI('validate', { 'csdl' => @csdl })
+
+				if res.has_key?('dpu')
+					@total_dpu = Float(res['dpu'])
+				else
+					raise CompileFailedError, 'Validated successfully but no DPU in the response'
+				end
+
+				if res.has_key?('created_at')
+					@created_at = Date.parse(res['created_at'])
+				else
+					raise CompileFailedError, 'Validated successfully but no created_at in the response'
+				end
+			rescue APIError => err
+				clearHash()
+
+				case err.http_code
+				when 400
+					raise CompileFailedError, err
+				else
+					raise APIError('Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']', err.http_code)
+				end
+			end
+		end
+
+		#Call the DataSift API to get the DPU for this definition. Returns
+		#=== Returns
+		#A Hash containing...
+		#* +detail+ - The breakdown of running the rule
+		#* +dpu+ - The total DPU of the rule
 		def getDPUBreakdown()
 			raise InvalidDataError, "Cannot get the DPU for an empty definition." unless @csdl.length > 0
 
 			@user.callAPI('dpu', { 'hash' => self.hash })
 		end
 
-		# Call the DataSift API to get buffered interactions.
-		# === Parameters
-		#
-		# * +count+ - Optional number of interactions to return (max 200).
-		# * +from_id+ - Optional start ID.
-		#
+		#Call the DataSift API to get buffered interactions.
+		#=== Parameters
+		#* +count+ - Optional number of interactions to return (max 200).
+		#* +from_id+ - Optional start ID.
+		#=== Returns
+		#An array of Hashes where each Hash is an interaction.
 		def getBuffered(count = false, from_id = false)
 			raise InvalidDataError, "Cannot get buffered interactions for an empty definition." unless @csdl.length > 0
 
@@ -146,28 +173,28 @@ def getBuffered(count = false, from_id = false)
 
 			raise APIError, 'No data in the response' unless retval.has_key?('stream')
 
-			retval['stream']
+			return retval['stream']
 		end
 
-		# Create a Historics query based on this Definition.
-		# === Parameters
-		#
-		# * +start_date+ - The start date for a new Historics query.
-		# * +end_date+ - The end date for a new Historics query.
-		# * +sources+ - An array of sources for a new Historics query.
-		# * +name+ - The name for a new Historics query.
-		# * +sample+ - The sample rate for the new Historics query.
-		#
+		#Create a Historics query based on this Definition.
+		#=== Parameters
+		#* +start_date+ - The start date for a new Historics query.
+		#* +end_date+ - The end date for a new Historics query.
+		#* +sources+ - An array of sources for a new Historics query.
+		#* +name+ - The name for a new Historics query.
+		#* +sample+ - The sample rate for the new Historics query.
+		#=== Returns
+		#A Historic object.
 		def createHistoric(start_date, end_date, sources, sample, name)
 			return Historic.new(@user, hash, start_date, end_date, sources, sample, name)
 		end
 
-		# Returns a StreamConsumer-derived object for this definition, for the
-		# given type.
-		# === Parameters
-		#
-		# * +type+ - The consumer type for which to construct a consumer.
-		#
+		#Returns a StreamConsumer-derived object for this definition, for the
+		#given type.
+		#=== Parameters
+		#* +type+ - The consumer type for which to construct a consumer.
+		#=== Returns
+		#A StreamConsumer-derived object.
 		def getConsumer(type = nil, on_interaction = nil, on_stopped = nil)
 			StreamConsumer.factory(@user, type, self)
 		end