webficient-twilio 2.0.0 → 2.1.0

data/VERSION.yml

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

data/lib/twilio/verb.rb

@@ -1,13 +1,31 @@
 module Twilio
   # Twilio Verbs enable your application to respond to Twilio requests (to your app) with XML responses.
   # There are 5 primary verbs (say, play, gather, record, dial) and 3 secondary (hangup, pause, redirect).
+  # Verbs can be chained and, in some cases, nested.
+  #
+  # If your response consists of a single verb, you can use the inline form of a new verb instance:
+  #
+  #   Twilio::Verb.new.say('The time is 9:35 PM.')
+  #
+  # But if you need to chain several verbs together, just wrap them in a block and call the 'response' attribute:
+  #
+  #   verb = Twilio::Verb.new { |v|
+  #     v.dial('415-123-4567')
+  #     v.redirect('http://www.foo.com/nextInstructions')
+  #   }
+  #   verb.response
   class Verb
+    
+    attr_reader :response
         
     def initialize(&block)
       @xml = Builder::XmlMarkup.new
       @xml.instruct!
       
-      block.call(self) if block_given?
+      if block_given?
+        @chain = true
+        @response = @xml.Response { block.call(self) }
+      end
     end
         
     # The Say verb converts text to speech that is read back to the caller. 
@@ -23,7 +41,8 @@ module Twilio
     #   Twilio::Verb.new.say('Your PIN is 1234', :loop => 4)
     #   Twilio::Verb.new.say('Your PIN is 1 2 3 4', :loop => 4)
     # 
-    # If you need a longer pause between each loop, set the pause option:
+    # If you need a longer pause between each loop, instead of explicitly calling the Pause
+    # verb within a block, you can set the convenient pause option:
     #
     #   Twilio::Verb.new.say('Your PIN is 1 2 3 4', :loop => 4, :pause => true)
     #
@@ -31,7 +50,7 @@ module Twilio
     #
     #   Twilio::Verb.new.say('The time is 9:35 PM.', :voice => 'woman')
     #   Twilio::Verb.new.say('The time is 9:35 PM.', {:voice => 'woman', :language => 'es'})
-    def say(*args, &block)
+    def say(*args)
       options = {:voice => 'man', :language => 'en', :loop => 1}
       args.each do |arg|
         case arg
@@ -44,7 +63,7 @@ module Twilio
         end
       end
       
-      response {
+      output {
         if options[:pause]
           loop_with_pause(options[:loop], @xml) do
             @xml.Say(options[:text_to_speak], :voice => options[:voice], :language => options[:language])
@@ -60,13 +79,14 @@ module Twilio
     #   Twilio::Verb.new.play('http://foo.com/cowbell.mp3')
     #   Twilio::Verb.new.play('http://foo.com/cowbell.mp3', :loop => 3)
     #
-    # If you need a longer pause between each loop, set the pause option:
+    # If you need a longer pause between each loop, instead of explicitly calling the Pause
+    # verb within a block, you can set the convenient pause option:
     #
     #   Twilio::Verb.new.play('http://foo.com/cowbell.mp3', :loop => 3, :pause => true)
     #
     # Options (see http://www.twilio.com/docs/api_reference/TwiML/play) are passed in as a hash,
     # but only 'loop' is currently supported.
-    def play(*args, &block)
+    def play(*args)
       options = {:loop => 1}
       args.each do |arg|
         case arg
@@ -79,7 +99,7 @@ module Twilio
         end
       end
 
-      response {
+      output {
         if options[:pause]
           loop_with_pause(options[:loop], @xml) do
             @xml.Play(options[:audio_url])
@@ -101,11 +121,29 @@ module Twilio
     #   Twilio::Verb.new.gather(:action => 'http://foobar.com')
     #   Twilio::Verb.new.gather(:finishOnKey => '*') 
     #   Twilio::Verb.new.gather(:action => 'http://foobar.com', :finishOnKey => '*') 
+    #
+    # Gather also lets you nest the Play, Say, and Pause verbs:
+    #
+    #   verb = Twilio::Verb.new { |v|
+    #     v.gather(:action => '/process_gather', :method => 'GET) {
+    #       v.say('Please enter your account number followed by the pound sign')
+    #     }
+    #     v.say("We didn't receive any input. Goodbye!")
+    #   }
+    #   verb.response # represents the final xml output
     def gather(*args, &block)
-      options = args.shift
-      response { @xml.Gather(options) }
+      options = args.shift || {}
+      output { 
+        if block_given?
+          @xml.Gather(options) { block.call }
+        else
+          @xml.Gather(options)          
+        end
+      }
     end
     
+    #play, say, pause
+    
     # The Record verb records the caller's voice and returns a URL that links to a file 
     # containing the audio recording.
     #
@@ -116,9 +154,9 @@ module Twilio
     #   Twilio::Verb.new.record(:action => 'http://foobar.com')
     #   Twilio::Verb.new.record(:finishOnKey => '*') 
     #   Twilio::Verb.new.record(:transcribe => true, :transcribeCallback => '/handle_transcribe')
-    def record(*args, &block)
+    def record(*args)
       options = args.shift
-      response { @xml.Record(options) }
+      output { @xml.Record(options) }
     end
     
     # The Dial verb connects the current caller to an another phone. If the called party picks up, 
@@ -137,6 +175,17 @@ module Twilio
     #   Twilio::Verb.new.dial('415-123-4567')
     #   Twilio::Verb.new.dial('415-123-4567', :action => 'http://foobar.com')
     #   Twilio::Verb.new.dial('415-123-4567', {:timeout => 10, :callerId => '858-987-6543'}) 
+    #
+    # Twilio also supports an alternate form in which a Number object is nested inside Dial:
+    #
+    #   verb = Twilio::Verb.new { |v|
+    #     v.dial {
+    #       v.number('415-123-4567')
+    #       v.number('415-123-4568')
+    #       v.number('415-123-4569')
+    #     }
+    #   }
+    #   verb.response # represents the final xml output
     def dial(*args, &block)
       number_to_dial = ''
       options = {}
@@ -151,13 +200,101 @@ module Twilio
         end
       end
       
-      response { @xml.Dial(number_to_dial, options) }
+      output { 
+        if block_given?
+          @xml.Dial(options) { block.call }
+        else
+          @xml.Dial(number_to_dial, options)           
+        end
+      }
+    end
+        
+    # The Pause (secondary) verb waits silently for a number of seconds. 
+    # It is normally chained with other verbs. 
+    #
+    # Options (see http://www.twilio.com/docs/api_reference/TwiML/pause) are passed in as a hash
+    #
+    # Examples:
+    #   verb = Twilio::Verb.new { |v|
+    #     v.say('greetings')
+    #     v.pause(:length => 2)
+    #     v.say('have a nice day')
+    #   }
+    #   verb.response
+    def pause(*args)
+      options = args.shift
+      output { @xml.Pause(options) }
+    end
+    
+    # The Redirect (secondary) verb transfers control to a different URL.
+    # It is normally chained with other verbs.
+    #
+    # Options (see http://www.twilio.com/docs/api_reference/TwiML/redirect) are passed in as a hash
+    #
+    # Examples:
+    #   verb = Twilio::Verb.new { |v|
+    #     v.dial('415-123-4567')
+    #     v.redirect('http://www.foo.com/nextInstructions')
+    #   }
+    #   verb.response
+    def redirect(*args)
+      redirect_to_url = ''
+      options = {}
+      args.each do |arg|
+        case arg
+        when String
+          redirect_to_url = arg
+        when Hash
+          options.merge!(arg)
+        else
+          raise ArgumentError, 'dial expects String or Hash argument'
+        end
+      end
+      
+      output { @xml.Redirect(redirect_to_url, options) }
+    end
+    
+    # The Hangup (secondary) verb ends the call. 
+    # 
+    # Examples:
+    #   If your response is only a hangup:
+    #
+    #   Twilio::Verb.new.hangup
+    #
+    #   If your response is chained:
+    #
+    #   verb = Twilio::Verb.new { |v|
+    #     v.say("The time is #{Time.now}")
+    #     v.hangup
+    #   }
+    #   verb.response
+    def hangup
+      output { @xml.Hangup }
+    end
+    
+    # The Number element specifies a phone number. The number element has two optional attributes: sendDigits and url.
+    # Number elements can only be nested in Dial verbs
+    def number(*args)
+      number_to_dial = ''
+      options = {}
+      args.each do |arg|
+        case arg
+        when String
+          number_to_dial = arg
+        when Hash
+          options.merge!(arg)
+        else
+          raise ArgumentError, 'dial expects String or Hash argument'
+        end
+      end
+      
+      output { @xml.Number(number_to_dial, options) }
     end
           
     private
     
-      def response
-        @xml.Response { yield }
+      def output
+        @chain ? yield : @xml.Response { yield }
       end 
     
       def loop_with_pause(loop_count, xml, &verb_action)

data/test/fixtures/yml/verb_responses.yml

@@ -17,8 +17,14 @@ say_hi_with_pause:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say><Pause/></Response>
 
 say_hi_with_pause_and_say_bye:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say><Pause/><Say loop="1" language="en" voice="man">bye</Say></Response>
-      
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say><Pause></Pause><Say loop="1" language="en" voice="man">bye</Say></Response>
+  
+say_hi_with_2_second_pause_and_say_bye:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say><Pause length="2"/><Say loop="1" language="en" voice="man">bye</Say></Response>
+  
+say_hi_and_hangup:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Say loop="1" language="en" voice="man">hi</Say><Hangup/></Response>  
+  
 play_mp3:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Play loop="1">http://foo.com/cowbell.mp3</Play></Response>
   
@@ -29,7 +35,7 @@ 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>
   
 gather:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather></Gather></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather/></Response>
 
 gather_with_action:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather action="http://foobar.com"/></Response>
@@ -47,8 +53,14 @@ gather_with_num_digits:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather numDigits="5"/></Response>
   
 gather_with_all_options_set:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather finishOnKey="*" method="GET" action="http://foobar.com" timeout="10" numDigits="5"/></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather action="http://foobar.com" numDigits="5" method="GET" timeout="10" finishOnKey="*"/></Response>
+  
+gather_and_say_instructions:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather><Say loop="1" language="en" voice="man">Please enter your account number followed by the pound sign</Say></Gather><Say loop="1" language="en" voice="man">We didn't receive any input. Goodbye!</Say></Response>
   
+gather_with_timeout_and_say_instructions:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Gather timeout="10"><Say loop="1" language="en" voice="man">Please enter your account number followed by the pound sign</Say></Gather><Say loop="1" language="en" voice="man">We didn't receive any input. Goodbye!</Say></Response>
+      
 record:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Record></Record></Response>
   
@@ -92,4 +104,16 @@ dial_with_caller_id:
   response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial callerId="858-987-6543">415-123-4567</Dial></Response>
   
 dial_with_timeout_and_caller_id:
-  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial callerId="858-987-6543" timeout="10">415-123-4567</Dial></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial timeout="10" callerId="858-987-6543">415-123-4567</Dial></Response>
+  
+dial_with_redirect:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial>415-123-4567</Dial><Redirect>http://www.foo.com/nextInstructions</Redirect></Response>
+
+dial_with_number_and_send_digits:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial><Number sendDigits="wwww1928">415-123-4567</Number></Dial></Response>  
+
+dial_multiple_numbers:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial><Number>415-123-4567</Number><Number>415-123-4568</Number><Number>415-123-4569</Number></Dial></Response> 
+      
+hangup:
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Hangup/></Response>  

data/test/twilio/verb_test.rb

@@ -22,13 +22,23 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
       assert_equal verb_response(:say_hi_three_times_with_pause), Twilio::Verb.new.say('hi', :loop => 3, :pause => true)
     end
     
-    #should "say 'hi' with pause and say 'bye'" do
-    #  verb = Twilio::Verb.new { |v|
-    #    v.say('TESTING')
-    #    puts v.say('BYE')
-    #  }
-    #  assert_equal verb_response(:say_hi_with_pause_and_say_bye), verb  
-    #end
+    should "say 'hi' with pause and say 'bye'" do
+      verb = Twilio::Verb.new { |v|
+        v.say('hi', :loop => 1)
+        v.pause
+        v.say('bye')
+      }
+      assert_equal verb_response(:say_hi_with_pause_and_say_bye), verb.response
+    end
+    
+    should "say 'hi' with 2 second pause and say 'bye'" do
+      verb = Twilio::Verb.new { |v|
+        v.say('hi')
+        v.pause(:length => 2)
+        v.say('bye')
+      }
+      assert_equal verb_response(:say_hi_with_2_second_pause_and_say_bye), verb.response
+    end
     
     should "play mp3 response" do
       assert_equal verb_response(:play_mp3), Twilio::Verb.new.play('http://foo.com/cowbell.mp3')
@@ -70,6 +80,26 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
       assert_equal verb_response(:gather_with_all_options_set), Twilio::Verb.new.gather(:action => 'http://foobar.com', :method => 'GET', :timeout => 10, :finishOnKey => '*', :numDigits => 5)
     end
     
+    should "gather and say instructions" do
+      verb = Twilio::Verb.new { |v|
+        v.gather {
+          v.say('Please enter your account number followed by the pound sign')
+        }
+        v.say("We didn't receive any input. Goodbye!")
+      }
+      assert_equal verb_response(:gather_and_say_instructions), verb.response
+    end
+    
+    should "gather with timeout and say instructions" do
+      verb = Twilio::Verb.new { |v|
+        v.gather(:timeout => 10) {
+          v.say('Please enter your account number followed by the pound sign')
+        }
+        v.say("We didn't receive any input. Goodbye!")
+      }
+      assert_equal verb_response(:gather_with_timeout_and_say_instructions), verb.response
+    end
+    
     should "record" do
       assert_equal verb_response(:record), Twilio::Verb.new.record
     end
@@ -129,6 +159,46 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
     should "dial with timeout and caller id" do
       assert_equal verb_response(:dial_with_timeout_and_caller_id), Twilio::Verb.new.dial('415-123-4567', {:timeout => 10, :callerId => '858-987-6543'})
     end
+    
+    should "dial with redirect" do
+      verb = Twilio::Verb.new { |v|
+        v.dial('415-123-4567')
+        v.redirect('http://www.foo.com/nextInstructions')
+      }
+      assert_equal verb_response(:dial_with_redirect), verb.response
+    end
+    
+    should "dial with number and send digits" do
+      verb = Twilio::Verb.new { |v|
+        v.dial {
+          v.number('415-123-4567', :sendDigits => 'wwww1928')
+        }
+      }
+      assert_equal verb_response(:dial_with_number_and_send_digits), verb.response
+    end
+    
+    should "dial multiple numbers" do
+      verb = Twilio::Verb.new { |v|
+        v.dial {
+          v.number('415-123-4567')
+          v.number('415-123-4568')
+          v.number('415-123-4569')
+        }
+      }
+      assert_equal verb_response(:dial_multiple_numbers), verb.response
+    end
+    
+    should "hangup" do
+      assert_equal verb_response(:hangup), Twilio::Verb.new.hangup
+    end
+    
+    should "say hi and hangup" do
+      verb = Twilio::Verb.new { |v|
+        v.say('hi')
+        v.hangup
+      }
+      assert_equal verb_response(:say_hi_and_hangup), verb.response
+    end
   end
   
 end

metadata

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