webficient-twilio 1.2.0 → 1.3.0

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 2
 :patch: 0
 :major: 1
+:minor: 3

data/lib/twilio/account.rb

@@ -1,4 +1,5 @@
 module Twilio
+  # The Account resource represents your Twilio Account. 
   class Account < TwilioObject
     def get
       self.connection.class.get('')

data/lib/twilio/call.rb

@@ -1,5 +1,12 @@
 module Twilio
+    # A Call represenents a connection between a telephone and Twilio. This may be 
+    # inbound, when a person calls your application, or outbound when your application 
+    # initiates the call, either via the REST API, or during a call via the Dial Verb. 
   class Call < TwilioObject
+    #  Example:
+    #  c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')
+    #  call = Twilio::Call.new(c)
+    #  response = call.make(CALLER_ID, user_number, 'http://myapp.com/twilio_response_handler')
     def make(caller, called, url, optional = {})
       self.connection.class.post("/Calls", :body => {:Caller => caller, :Called => called, :Url => url}.merge(optional))
     end

data/lib/twilio/connection.rb

@@ -1,7 +1,7 @@
 module Twilio
-  #The Connection class caches the Twilio API base path and authentication credentials.
-  #It is passed into the constructor of other TwilioObject's, avoiding the need to 
-  #explicitly set credentials with each API call.
+  # The Connection class caches the Twilio API base path and authentication credentials.
+  # It is passed into the constructor of other TwilioObject's, avoiding the need to 
+  # explicitly set credentials with each API call.
   #
   #  Example:
   #  c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')

data/lib/twilio/incoming_phone_number.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # An IncomingPhoneNumber resource represents a phone number given to you by 
+  # Twilio to receive incoming phone calls. 
   class IncomingPhoneNumber < TwilioObject
     def list(optional = {})
       self.connection.class.get("/IncomingPhoneNumbers", :query => optional) 

data/lib/twilio/local_phone_number.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # This sub-resource represents only Local phone numbers, or in other words, not toll-free numbers. 
+  # Also allows you to request a new local phone number be added to your account. 
   class LocalPhoneNumber < TwilioObject
     def create(url, area_code = nil, method = 'POST', friendly_name = nil)
       self.connection.class.post("/IncomingPhoneNumbers/Local", :body => {

data/lib/twilio/notification.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # A Notification represenents a log entry made by Twilio in the course of handling 
+  # your calls or using the REST API.
   class Notification < TwilioObject
     def list(optional = {})
       self.connection.class.get('/Notifications', :query => optional)

data/lib/twilio/outgoing_caller_id.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # An OutgoingCallerId resource represents an outgoing Caller ID that you have 
+  # registered with Twilio for use when making an outgoing call or using the Dial Verb. 
   class OutgoingCallerId < TwilioObject
     def create(phone_number, friendly_name = phone_number, call_delay = 0)
       self.connection.class.post("/OutgoingCallerIds", :body => {

data/lib/twilio/recording.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # Recordings are generated when you use the Record Verb. Those recordings are 
+  # hosted on Twilio's REST API for you to access. 
   class Recording < TwilioObject    
     def list(optional = {})
       self.connection.class.get("/Recordings", :query => optional)  

data/lib/twilio/toll_free_phone_number.rb

@@ -1,4 +1,6 @@
 module Twilio
+  # This sub-resource represents only Toll Free phone numbers, or in other words, not local numbers. 
+  # Also allows you to request a new toll free phone number be added to your account. 
   class TollFreePhoneNumber < TwilioObject
     def create(url, area_code = nil, method = 'POST', friendly_name = nil)
       self.connection.class.post("/IncomingPhoneNumbers/TollFree", :body => {

data/lib/twilio/twilio_object.rb

@@ -1,5 +1,5 @@
 module Twilio
-  class TwilioObject
+  class TwilioObject  #:nodoc: all
     include HTTParty
     
     attr_reader :connection

data/lib/twilio/verb.rb

@@ -23,26 +23,32 @@ module Twilio
       #
       #   Twilio::Verb.say_4_times_with_pause('Your PIN is 1 2 3 4')
       #
-      # Optional params passed in as a hash (see http://www.twilio.com/docs/api_reference/TwiML/say):
-      #    voice: (woman) man
-      #    language: (en) es fr de
-      #    loop: >= 0 (1)
-      def say(text, options = {})
-        voice = options[:voice] || 'woman'
-        language = options[:language] || 'en'        
-        loop_count = Integer(options[:loop]  || 1)
-        pause = options[:pause]
+      # Optional params (see http://www.twilio.com/docs/api_reference/TwiML/say) are passed in as a hash:
+      #
+      #   Twilio::Verb.say('The time is 9:35 PM.', :voice => 'woman')
+      #   Twilio::Verb.say('The time is 9:35 PM.', {:voice => 'woman', :language => 'es'})
+      def say(*args, &block)
+        options = {:voice => 'man', :language => 'en', :loop => 1}
+        args.each do |arg|
+          case arg
+          when String
+            options[:text_to_speak] = arg
+          when Hash
+            options.merge!(arg)
+          else
+            raise ArgumentError, 'say expects String or Hash argument'
+          end
+        end
         
         xml = Builder::XmlMarkup.new
         xml.instruct!
         xml.Response {
-          if pause                                    
-            loop_count.times do |i|
-              xml.Say(text, :voice => voice, :language => language)
-              xml.Pause unless i == loop_count-1
+          if options[:pause]
+            loop_with_pause(options[:loop], xml) do
+              xml.Say(options[:text_to_speak], :voice => options[:voice], :language => options[:language])
             end
           else
-            xml.Say(text, :voice => voice, :language => language, :loop => loop_count)
+            xml.Say(options[:text_to_speak], :voice => options[:voice], :language => options[:language], :loop => options[:loop])
           end
         }
       end
@@ -56,29 +62,43 @@ module Twilio
       #
       #   Twilio::Verb.play_3_times_with_pause('http://foo.com/cowbell.mp3')
       #
-      # Optional params passed in as a hash (see http://www.twilio.com/docs/api_reference/TwiML/play):
-      #    loop: >= 0 (1)      
-      def play(audio_url, options = {})
-        loop_count = Integer(options[:loop]  || 1)
-        pause = options[:pause]
-        
+      # Optional params (see http://www.twilio.com/docs/api_reference/TwiML/play) are passed in as a hash,
+      # however, since the Play verb only supports 'loop' as the current option, you can instead use the
+      # above form to keep things concise. 
+      def play(*args, &block)
+        options = {:loop => 1}
+        args.each do |arg|
+          case arg
+          when String
+            options[:audio_url] = arg
+          when Hash
+            options.merge!(arg)
+          else
+            raise ArgumentError, 'play expects String or Hash argument'
+          end
+        end
+
         xml = Builder::XmlMarkup.new
         xml.instruct!
         xml.Response {
-          if pause                                    
-            loop_count.times do |i|
-              xml.Play(audio_url)
-              xml.Pause unless i == loop_count-1
+          if options[:pause]
+            loop_with_pause(options[:loop], xml) do
+              xml.Play(options[:audio_url])
             end
           else
-            xml.Play(audio_url, :loop => loop_count)
+            xml.Play(options[:audio_url], :loop => options[:loop])
           end          
         }
       end
-      
-      #Not yet implemented 
-      def gather(options = {})
-        raise NotImplementedError.new 'Not yet implemented - coming soon'
+            
+      def gather(*args, &block)
+        options = args.shift
+        
+        xml = Builder::XmlMarkup.new
+        xml.instruct!
+        xml.Response {
+          xml.Gather(options)       
+        }
       end
       
       #Not yet implemented 
@@ -90,15 +110,27 @@ module Twilio
       def dial(phone_number, options = {})
         raise NotImplementedError.new 'Not yet implemented - coming soon'
       end
-      
+
       def method_missing(method_id, *args) #:nodoc:
         if match = /(say|play|gather|record|dial)_(\d+)_times(_with_pause$*)/.match(method_id.to_s)
           verb = match.captures.first 
           how_many_times = match.captures[1]
           pause = match.captures[2] == '_with_pause'
-          self.send(verb, args.first, { :loop => how_many_times, :pause =>  pause})
+          self.send(verb, args.first, { :loop => Integer(how_many_times), :pause =>  pause})
+        else
+          raise NoMethodError.new("Method --- #{method_id} --- not found")
         end
       end
+            
+      private 
+      
+        def loop_with_pause(loop_count, xml, &verb_action)
+          last_iteration = loop_count-1                               
+          loop_count.times do |i|
+            yield verb_action
+            xml.Pause unless i == last_iteration
+          end
+        end
     end
   end
 end

data/test/fixtures/yml/verb_responses.yml

@@ -1,14 +1,17 @@
 say_hi:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="woman">hi</Say></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say></Response>
 
-say_hi_in_spanish_with_male_voice:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="es" voice="man">hola</Say></Response>
+say_hi_with_female_voice:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="woman">hi</Say></Response>
+    
+say_hi_in_spanish_with_female_voice:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="es" voice="woman">hola</Say></Response>
       
 say_hi_three_times:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="3" language="en" voice="woman">hi</Say></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="3" language="en" voice="man">hi</Say></Response>
   
 say_hi_three_times_with_pause:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say language="en" voice="woman">hi</Say><Pause/><Say language="en" voice="woman">hi</Say><Pause/><Say language="en" voice="woman">hi</Say></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say language="en" voice="man">hi</Say><Pause/><Say language="en" voice="man">hi</Say><Pause/><Say language="en" voice="man">hi</Say></Response>
   
 play_mp3:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Play loop="1">http://foo.com/cowbell.mp3</Play></Response>
@@ -17,4 +20,22 @@ play_mp3_two_times:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Play loop="2">http://foo.com/cowbell.mp3</Play></Response>
 
 play_mp3_two_times_with_pause:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Play>http://foo.com/cowbell.mp3</Play><Pause/><Play>http://foo.com/cowbell.mp3</Play></Response>   
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Play>http://foo.com/cowbell.mp3</Play><Pause/><Play>http://foo.com/cowbell.mp3</Play></Response>
+  
+gather:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather></Gather></Response>
+
+gather_with_action:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather action="http://foobar.com"/></Response>
+      
+gather_with_get_method:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather method="GET"/></Response>
+  
+gather_with_timeout:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather timeout="10"/></Response>
+  
+gather_with_finish_key:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather finishOnKey="*"/></Response>
+  
+gather_with_num_digits:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather numDigits="5"/></Response>

data/test/test_helper.rb

@@ -14,16 +14,16 @@ require 'twilio'
 class Test::Unit::TestCase #:nodoc: all
 end
 
-def fixture(filename)
+def fixture(filename) #:nodoc:
   path = File.join(File.dirname(__FILE__), "fixtures/xml/#{filename}.xml")
   File.read path
 end
 
-def twilio_url(url=nil)
+def twilio_url(url=nil) #:nodoc:
   "https://mysid:mytoken@api.twilio.com:443/2008-08-01/Accounts/mysid#{'/' + url if url}"
 end
 
-def verb_response(verb)
+def verb_response(verb) #:nodoc:
   path = File.join(File.dirname(__FILE__), "fixtures/yml/verb_responses.yml")
   YAML.load_file(path)[verb.to_s]['response']
 end

data/test/twilio/verb_test.rb

@@ -5,9 +5,13 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
     should "say 'hi'" do
       assert_equal verb_response(:say_hi), Twilio::Verb.say('hi')
     end
-    
-    should "say 'hola' in Spanish with male voice" do
-      assert_equal verb_response(:say_hi_in_spanish_with_male_voice), Twilio::Verb.say('hola', {:voice => 'man', :language => 'es'})
+
+    should "say 'hi' with female voice" do
+      assert_equal verb_response(:say_hi_with_female_voice), Twilio::Verb.say('hi', :voice => 'woman')
+    end
+        
+    should "say 'hola' in Spanish with female voice" do
+      assert_equal verb_response(:say_hi_in_spanish_with_female_voice), Twilio::Verb.say('hola', {:voice => 'woman', :language => 'es'})
     end
     
     should "say 'hi' three times" do
@@ -30,8 +34,28 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
       assert_equal verb_response(:play_mp3_two_times_with_pause), Twilio::Verb.play_2_times_with_pause('http://foo.com/cowbell.mp3')
     end
      
-    should "raise not implemented error with gather" do
-      assert_raise(NotImplementedError) { Twilio::Verb.gather('something') }
+    should "gather" do
+      assert_equal verb_response(:gather), Twilio::Verb.gather
+    end
+    
+    should "gather with action" do
+      assert_equal verb_response(:gather_with_action), Twilio::Verb.gather(:action => 'http://foobar.com')
+    end
+    
+    should "gather with GET method" do
+      assert_equal verb_response(:gather_with_get_method), Twilio::Verb.gather(:method => 'GET')
+    end
+    
+    should "gather with timeout" do
+      assert_equal verb_response(:gather_with_timeout), Twilio::Verb.gather(:timeout => 10)
+    end
+    
+    should "gather with finish key" do
+      assert_equal verb_response(:gather_with_finish_key), Twilio::Verb.gather(:finishOnKey => '*')
+    end
+    
+    should "gather with num digits" do
+      assert_equal verb_response(:gather_with_num_digits), Twilio::Verb.gather(:numDigits => 5)
     end
     
     should "raise not implemented error with record" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: webficient-twilio
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors: 
 - Phil Misiowiec
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-04 00:00:00 -07:00
+date: 2009-06-21 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency