webficient-twilio 2.1.0 → 2.2.0

data/README.rdoc

@@ -1,23 +1,41 @@
-= twilio
+= Twilio Gem
 
-This wrapper defines each of the interfaces currently supported by Twilio REST API.
+The Twilio gem provides two major pieces of functionality: (1) a Ruby wrapper for the Twilio REST API and (2) response handlers based on the Twilio Markup XML (TwiML).
 
-Sample Usage:
+See http://www.twilio.com/docs/index for Twilio's API documentation.
+
+For an overview of the Twilio Gem and a sample use case, check out http://www.webficient.com/2009/06/22/hello-this-is-your-rails-app-calling-you.
+
+== Calling the Twilio REST API
 
 First create a connection object:
 
   c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')
   
 Now instantiate other objects by passing in the connection:
-
-  a = Twilio::Account.new(c)
-  a.update_name('sparky')
   
   call = Twilio::Call.new(c)
   call.make('1234567890', '9876543210', 'http://mysite.com/connected_call')
   
   recording = Twilio::Recording.new(c)
   recording.list
+  
+== Responding to Twilio
+
+When Twilio calls your application URL, your response must use the Twilio Markup XML (http://www.twilio.com/docs/api_reference/TwiML/). The Twilio gem makes this very easy 
+by providing a Twilio Verb class. 
+
+For example, in a Ruby on Rails application, you could do the following inside a controller class:
+
+  Twilio::Verb.dial('415-123-4567')
+  
+and you can nest multiple verbs inside a block:
+
+  verb = Twilio::Verb.new { |v|
+    v.say("The time is #{Time.now}")
+    v.hangup
+  }
+  verb.response
 
 == Copyright
 

data/VERSION.yml

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

data/lib/twilio/verb.rb

@@ -3,11 +3,11 @@ module Twilio
   # 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:
+  # If your response consists of a single verb, you can call a Verb class method:
   #
-  #   Twilio::Verb.new.say('The time is 9:35 PM.')
+  #   Twilio::Verb.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:
+  # But if you need to chain several verbs together, just wrap them in an instance block and call the 'response' attribute:
   #
   #   verb = Twilio::Verb.new { |v|
   #     v.dial('415-123-4567')
@@ -17,6 +17,13 @@ module Twilio
   class Verb
     
     attr_reader :response
+    
+    class << self
+      def method_missing(method_id, *args) #:nodoc:
+        v = Verb.new
+        v.send(method_id, *args)
+      end
+    end
         
     def initialize(&block)
       @xml = Builder::XmlMarkup.new
@@ -32,24 +39,24 @@ module Twilio
     # Say is useful for dynamic text that is difficult to prerecord. 
     #
     # Examples:
-    #   Twilio::Verb.new.say('The time is 9:35 PM.')
-    #   Twilio::Verb.new.say('The time is 9:35 PM.', :loop => 3)
+    #   Twilio::Verb.say('The time is 9:35 PM.')
+    #   Twilio::Verb.say('The time is 9:35 PM.', :loop => 3)
     #
     # With numbers, 12345 will be spoken as "twelve thousand three hundred forty five" while
     # 1 2 3 4 5 will be spoken as "one two three four five."
     #
-    #   Twilio::Verb.new.say('Your PIN is 1234', :loop => 4)
-    #   Twilio::Verb.new.say('Your PIN is 1 2 3 4', :loop => 4)
+    #   Twilio::Verb.say('Your PIN is 1234', :loop => 4)
+    #   Twilio::Verb.say('Your PIN is 1 2 3 4', :loop => 4)
     # 
     # 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)
+    #   Twilio::Verb.say('Your PIN is 1 2 3 4', :loop => 4, :pause => true)
     #
     # Options (see http://www.twilio.com/docs/api_reference/TwiML/say) are passed in as a hash:
     #
-    #   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'})
+    #   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)
       options = {:voice => 'man', :language => 'en', :loop => 1}
       args.each do |arg|
@@ -76,13 +83,13 @@ module Twilio
     
     # The Play verb plays an audio URL back to the caller. 
     # Examples:
-    #   Twilio::Verb.new.play('http://foo.com/cowbell.mp3')
-    #   Twilio::Verb.new.play('http://foo.com/cowbell.mp3', :loop => 3)
+    #   Twilio::Verb.play('http://foo.com/cowbell.mp3')
+    #   Twilio::Verb.play('http://foo.com/cowbell.mp3', :loop => 3)
     #
     # 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)
+    #   Twilio::Verb.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.
@@ -117,10 +124,10 @@ module Twilio
     # Options (see http://www.twilio.com/docs/api_reference/TwiML/gather) are passed in as a hash
     #
     # Examples:
-    #   Twilio::Verb.new.gather
-    #   Twilio::Verb.new.gather(:action => 'http://foobar.com')
-    #   Twilio::Verb.new.gather(:finishOnKey => '*') 
-    #   Twilio::Verb.new.gather(:action => 'http://foobar.com', :finishOnKey => '*') 
+    #   Twilio::Verb.gather
+    #   Twilio::Verb.gather(:action => 'http://foobar.com')
+    #   Twilio::Verb.gather(:finishOnKey => '*') 
+    #   Twilio::Verb.gather(:action => 'http://foobar.com', :finishOnKey => '*') 
     #
     # Gather also lets you nest the Play, Say, and Pause verbs:
     #
@@ -150,10 +157,10 @@ module Twilio
     # Options (see http://www.twilio.com/docs/api_reference/TwiML/record) are passed in as a hash
     #
     # Examples:
-    #   Twilio::Verb.new.record
-    #   Twilio::Verb.new.record(:action => 'http://foobar.com')
-    #   Twilio::Verb.new.record(:finishOnKey => '*') 
-    #   Twilio::Verb.new.record(:transcribe => true, :transcribeCallback => '/handle_transcribe')
+    #   Twilio::Verb.record
+    #   Twilio::Verb.record(:action => 'http://foobar.com')
+    #   Twilio::Verb.record(:finishOnKey => '*') 
+    #   Twilio::Verb.record(:transcribe => true, :transcribeCallback => '/handle_transcribe')
     def record(*args)
       options = args.shift
       output { @xml.Record(options) }
@@ -172,9 +179,9 @@ module Twilio
     # Options (see http://www.twilio.com/docs/api_reference/TwiML/dial) are passed in as a hash
     #
     # Examples:
-    #   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::Verb.dial('415-123-4567')
+    #   Twilio::Verb.dial('415-123-4567', :action => 'http://foobar.com')
+    #   Twilio::Verb.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:
     #
@@ -259,7 +266,7 @@ module Twilio
     # Examples:
     #   If your response is only a hangup:
     #
-    #   Twilio::Verb.new.hangup
+    #   Twilio::Verb.hangup
     #
     #   If your response is chained:
     #

data/test/fixtures/yml/verb_responses.yml

@@ -104,7 +104,7 @@ 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 timeout="10" callerId="858-987-6543">415-123-4567</Dial></Response>
+  response: <?xml version="1.0" encoding="UTF-8"?><Response><Dial callerId="858-987-6543" timeout="10">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>

data/test/twilio/verb_test.rb

@@ -3,23 +3,23 @@ require File.dirname(__FILE__) + '/../test_helper'
 class VerbTest < Test::Unit::TestCase #:nodoc: all
   context "A Twilio Verb" do
     should "say 'hi'" do
-      assert_equal verb_response(:say_hi), Twilio::Verb.new.say('hi')
+      assert_equal verb_response(:say_hi), Twilio::Verb.say('hi')
     end
 
     should "say 'hi' with female voice" do
-      assert_equal verb_response(:say_hi_with_female_voice), Twilio::Verb.new.say('hi', :voice => 'woman')
+      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.new.say('hola', {:voice => 'woman', :language => 'es'})
+      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
-      assert_equal verb_response(:say_hi_three_times), Twilio::Verb.new.say('hi', :loop => 3)
+      assert_equal verb_response(:say_hi_three_times), Twilio::Verb.say('hi', :loop => 3)
     end
     
     should "say 'hi' three times with pause" do
-      assert_equal verb_response(:say_hi_three_times_with_pause), Twilio::Verb.new.say('hi', :loop => 3, :pause => true)
+      assert_equal verb_response(:say_hi_three_times_with_pause), Twilio::Verb.say('hi', :loop => 3, :pause => true)
     end
     
     should "say 'hi' with pause and say 'bye'" do
@@ -41,43 +41,43 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
     end
     
     should "play mp3 response" do
-      assert_equal verb_response(:play_mp3), Twilio::Verb.new.play('http://foo.com/cowbell.mp3')
+      assert_equal verb_response(:play_mp3), Twilio::Verb.play('http://foo.com/cowbell.mp3')
     end
     
     should "play mp3 response two times" do
-      assert_equal verb_response(:play_mp3_two_times), Twilio::Verb.new.play('http://foo.com/cowbell.mp3', :loop => 2)
+      assert_equal verb_response(:play_mp3_two_times), Twilio::Verb.play('http://foo.com/cowbell.mp3', :loop => 2)
     end
    
     should "play mp3 response two times with pause" do
-      assert_equal verb_response(:play_mp3_two_times_with_pause), Twilio::Verb.new.play('http://foo.com/cowbell.mp3', :loop => 2, :pause => true)
+      assert_equal verb_response(:play_mp3_two_times_with_pause), Twilio::Verb.play('http://foo.com/cowbell.mp3', :loop => 2, :pause => true)
     end
      
     should "gather" do
-      assert_equal verb_response(:gather), Twilio::Verb.new.gather
+      assert_equal verb_response(:gather), Twilio::Verb.gather
     end
     
     should "gather with action" do
-      assert_equal verb_response(:gather_with_action), Twilio::Verb.new.gather(:action => 'http://foobar.com')
+      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.new.gather(:method => 'GET')
+      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.new.gather(:timeout => 10)
+      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.new.gather(:finishOnKey => '*')
+      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.new.gather(:numDigits => 5)
+      assert_equal verb_response(:gather_with_num_digits), Twilio::Verb.gather(:numDigits => 5)
     end
     
     should "gather with all options set" do
-      assert_equal verb_response(:gather_with_all_options_set), Twilio::Verb.new.gather(:action => 'http://foobar.com', :method => 'GET', :timeout => 10, :finishOnKey => '*', :numDigits => 5)
+      assert_equal verb_response(:gather_with_all_options_set), Twilio::Verb.gather(:action => 'http://foobar.com', :method => 'GET', :timeout => 10, :finishOnKey => '*', :numDigits => 5)
     end
     
     should "gather and say instructions" do
@@ -101,63 +101,63 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
     end
     
     should "record" do
-      assert_equal verb_response(:record), Twilio::Verb.new.record
+      assert_equal verb_response(:record), Twilio::Verb.record
     end
     
     should "record with action" do
-      assert_equal verb_response(:record_with_action), Twilio::Verb.new.record(:action => 'http://foobar.com')
+      assert_equal verb_response(:record_with_action), Twilio::Verb.record(:action => 'http://foobar.com')
     end
     
     should "record with GET method" do
-      assert_equal verb_response(:record_with_get_method), Twilio::Verb.new.record(:method => 'GET')
+      assert_equal verb_response(:record_with_get_method), Twilio::Verb.record(:method => 'GET')
     end
     
     should "record with timeout" do
-      assert_equal verb_response(:record_with_timeout), Twilio::Verb.new.record(:timeout => 10)
+      assert_equal verb_response(:record_with_timeout), Twilio::Verb.record(:timeout => 10)
     end
     
     should "record with finish key" do
-      assert_equal verb_response(:record_with_finish_key), Twilio::Verb.new.record(:finishOnKey => '*')
+      assert_equal verb_response(:record_with_finish_key), Twilio::Verb.record(:finishOnKey => '*')
     end
     
     should "record with max length" do
-      assert_equal verb_response(:record_with_max_length), Twilio::Verb.new.record(:maxLength => 1800)      
+      assert_equal verb_response(:record_with_max_length), Twilio::Verb.record(:maxLength => 1800)      
     end
     
     should "record with transcribe" do
-      assert_equal verb_response(:record_with_transcribe), Twilio::Verb.new.record(:transcribe => true, :transcribeCallback => '/handle_transcribe')            
+      assert_equal verb_response(:record_with_transcribe), Twilio::Verb.record(:transcribe => true, :transcribeCallback => '/handle_transcribe')            
     end
     
     should "dial" do
-      assert_equal verb_response(:dial), Twilio::Verb.new.dial('415-123-4567')
+      assert_equal verb_response(:dial), Twilio::Verb.dial('415-123-4567')
     end
     
     should "dial with action" do
-      assert_equal verb_response(:dial_with_action), Twilio::Verb.new.dial('415-123-4567', :action => 'http://foobar.com')
+      assert_equal verb_response(:dial_with_action), Twilio::Verb.dial('415-123-4567', :action => 'http://foobar.com')
     end
     
     should "dial with GET method" do
-      assert_equal verb_response(:dial_with_get_method), Twilio::Verb.new.dial('415-123-4567', :method => 'GET')
+      assert_equal verb_response(:dial_with_get_method), Twilio::Verb.dial('415-123-4567', :method => 'GET')
     end
     
     should "dial with timeout" do
-      assert_equal verb_response(:dial_with_timeout), Twilio::Verb.new.dial('415-123-4567', :timeout => 10)
+      assert_equal verb_response(:dial_with_timeout), Twilio::Verb.dial('415-123-4567', :timeout => 10)
     end
     
     should "dial with hangup on star" do
-      assert_equal verb_response(:dial_with_hangup_on_star), Twilio::Verb.new.dial('415-123-4567', :hangupOnStar => true)
+      assert_equal verb_response(:dial_with_hangup_on_star), Twilio::Verb.dial('415-123-4567', :hangupOnStar => true)
     end
     
     should "dial with time limit" do
-      assert_equal verb_response(:dial_with_time_limit), Twilio::Verb.new.dial('415-123-4567', :timeLimit => 3600)
+      assert_equal verb_response(:dial_with_time_limit), Twilio::Verb.dial('415-123-4567', :timeLimit => 3600)
     end
     
     should "dial with caller id" do
-      assert_equal verb_response(:dial_with_caller_id), Twilio::Verb.new.dial('415-123-4567', :callerId => '858-987-6543')
+      assert_equal verb_response(:dial_with_caller_id), Twilio::Verb.dial('415-123-4567', :callerId => '858-987-6543')
     end
     
     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'})
+      assert_equal verb_response(:dial_with_timeout_and_caller_id), Twilio::Verb.dial('415-123-4567', {:timeout => 10, :callerId => '858-987-6543'})
     end
     
     should "dial with redirect" do
@@ -189,7 +189,7 @@ class VerbTest < Test::Unit::TestCase #:nodoc: all
     end
     
     should "hangup" do
-      assert_equal verb_response(:hangup), Twilio::Verb.new.hangup
+      assert_equal verb_response(:hangup), Twilio::Verb.hangup
     end
     
     should "say hi and hangup" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: webficient-twilio
 version: !ruby/object:Gem::Version 
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors: 
 - Phil Misiowiec