pandorified 0.7.1 → 0.8.0

data/Rakefile

@@ -1 +1,6 @@
 require 'bundler/gem_tasks'
+
+desc 'Open an irb session preloaded with this library'
+task :console do
+	  sh "irb -rubygems -I lib -r pandorified.rb"
+end

data/lib/pandorified/result.rb

@@ -9,28 +9,53 @@ module Pandorified
 			@xml = Nokogiri::XML(RestClient.post(API_URL, params))
 		end
 
+		# Check the status of this result. See {#success?} and {#error?}.
+		#
+		# @return [Number] A status number as returned by Pandorabots.
 		def status
 			@status ||= @xml.xpath('/result/@status').first.value.to_i
 		end
 
+		# @return [String] The botid of the bot this result is for.
 		def botid
 			@botid ||= @xml.xpath('/result/@botid').first.value
 		end
 
+		# @return [String] The custid for this session.
 		def custid
 			@custid ||= @xml.xpath('/result/@custid').first.value
 		end
 
+		# @return [String] The orginal input that triggered this response.
 		def input
 			@input ||= @xml.xpath('/result/input').first.text
 		end
 
+		# @return [String] The bot's response to the input.
 		def that
 			@that ||= @xml.xpath('/result/that').first.text
 		end
 
+		# @return [String] The error message as returned by Pandorabots, if an error occured.
 		def message
 			@message ||= @xml.xpath('/result/message').first.text
 		end
+
+		# @return `true` if this result was successful (no error was returned by Pandorabots), `false` otherwise.
+		def success?
+			self.status.zero?
+		end
+
+		alias_method :ok?, :success?
+		alias_method :successful?, :success?
+
+		# @note After checking if there is an error, you can read the error message with {#message}.
+		#
+		# @return `true` if Pandorabots returned an error.
+		def error?
+			!self.success?
+		end
+
+		alias_method :to_s, :that
 	end
 end

data/lib/pandorified/session.rb

@@ -1,7 +1,9 @@
 require 'pandorified/result'
-require 'pandorified/exceptions'
 
 module Pandorified
+	# Raised when Pandorabots returns an API result with a non-zero status.
+	class PandorabotsError < StandardError; end
+
 	class Session
 		# A new session for conversing with a bot.
 		#
@@ -15,19 +17,29 @@ module Pandorified
 		end
 
 		# Send a message to this session's bot and receive a response.
-		# If Pandorabots responds with an error, {Pandorified::Exceptions::PandorabotsError} is raised.
+		#
+		# @note See {Pandorified::Result} for ways to handle the response, or use {#talk!} which raises an exception on errors.
 		#
 		# @param [String] input Text to say to the bot.
 		#
 		# @return [String] The bot's response text.
 		def talk(input)
 			result = Pandorified::Result.new(botid: @botid, custid: @custid, input: input)
-			if result.status.zero?
-				@custid ||= result.custid
-				result.that
-			else
-				raise Pandorified::Exceptions::PandorabotsError, "Pandorabots returned status #{result.status}: #{result.message}"
-			end
+			@custid ||= result.custid if result.success?
+			result
+		end
+
+		# Send a message to this session's bot and receive a response (if successful).
+		# If Pandorabots responds with an error, {Pandorified::Exceptions::PandorabotsError} is raised.
+		#
+		# @note See {#talk} if you want to check the {Pandorabots::Result} object for success instead of an exception being raised on error.
+		#
+		# @param [String] input Text to say to the bot.
+		#
+		# @return [String] The bot's response text.
+		def talk!(input)
+			result = self.talk(input)
+			raise Pandorified::PandorabotsError, "Pandorabots returned status #{result.status}: #{result.message}" if result.error?
 		end
 	end
 end

data/lib/pandorified/version.rb

@@ -1,3 +1,3 @@
 module Pandorified
-	VERSION = '0.7.1'
+	VERSION = '0.8.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pandorified
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -56,7 +56,6 @@ files:
 - README.md
 - Rakefile
 - lib/pandorified.rb
-- lib/pandorified/exceptions.rb
 - lib/pandorified/result.rb
 - lib/pandorified/session.rb
 - lib/pandorified/version.rb

data/lib/pandorified/exceptions.rb

@@ -1,7 +0,0 @@
-module Pandorified
-	module Exceptions
-		# Raised when Pandorabots returns an API result with a non-zero status.
-		class PandorabotsError < StandardError
-		end
-	end
-end