adhearsion 2.0.0.rc5 → 2.0.0

data/lib/adhearsion/call_controller/dial.rb

@@ -4,38 +4,44 @@ module Adhearsion
   class CallController
     module Dial
       #
-      # Dial a third party and join to this call
+      # Dial one or more third parties and join one to this call
       #
-      # @param [String|Array<String>|Hash] number represents the extension or "number" that asterisk should dial.
-      # Be careful to not just specify a number like 5001, 9095551001
-      # You must specify a properly formatted string as Asterisk would expect to use in order to understand
-      # whether the call should be dialed using SIP, IAX, or some other means.
-      # You can also specify an array of destinations: each will be called with the same options simultaneously.
-      # The first call answered is joined, the others are hung up.
-      # A hash argument has the dial target as each key, and an hash of options as the value, in the form:
-      # dial({'SIP/100' => {:timeout => 3000}, 'SIP/200' => {:timeout => 4000} })
-      # The option hash for each target is merged into the global options, overriding them for the single dial.
-      # Destinations are dialed simultaneously as with an array.
+      # @overload dial(to[String], options = {})
+      #   @param [String] to The target URI to dial.
+      #     You must specify a properly formatted string that your VoIP platform understands.
+      #     eg. sip:foo@bar.com, tel:+14044754840, or SIP/foo/1234
+      #   @param [Hash] options see below
       #
-      # @param [Hash] options
+      # @overload dial(to[Array], options = {})
+      #   @param [Array<String>] to Target URIs to dial.
+      #     Each will be called with the same options simultaneously.
+      #     The first call answered is joined, the others are hung up.
+      #   @param [Hash] options see below
       #
-      # +:from+ - the caller id to be used when the call is placed. It is advised you properly adhere to the
-      # policy of VoIP termination providers with respect to caller id values.
+      # @overload dial(to[Hash], options = {})
+      #   @param [Hash<String => Hash>] to Target URIs to dial, mapped to their per-target options overrides.
+      #     Each will be called with the same options simultaneously.
+      #     The first call answered is joined, the others are hung up.
+      #     Each calls options are deep-merged with the global options hash.
+      #   @param [Hash] options see below
       #
-      # +:for+ - this option can be thought of best as a timeout.  i.e. timeout after :for if no one answers the call
-      # For example, dial(%w{SIP/jay-desk-650 SIP/jay-desk-601 SIP/jay-desk-601-2}, :for => 15.seconds, :from => callerid)
-      # this call will timeout after 15 seconds if 1 of the 3 extensions being dialed do not pick prior to the 15 second time limit
+      # @option options [String] :from the caller id to be used when the call is placed. It is advised you properly adhere to the
+      #   policy of VoIP termination providers with respect to caller id values.
+      #
+      # @option options [Numeric] :for this option can be thought of best as a timeout.
+      #   i.e. timeout after :for if no one answers the call
       #
       # @example Make a call to the PSTN using my SIP provider for VoIP termination
       #   dial "SIP/19095551001@my.sip.voip.terminator.us"
       #
-      # @example Make 3 Simulataneous calls to the SIP extensions, try for 15 seconds and use the callerid
-      # for this call specified by the variable my_callerid
+      # @example Make 3 simulataneous calls to the SIP extensions, try for 15 seconds and use the callerid for this call specified by the variable my_callerid
       #   dial %w{SIP/jay-desk-650 SIP/jay-desk-601 SIP/jay-desk-601-2}, :for => 15.seconds, :from => my_callerid
       #
       # @example Make a call using the IAX provider to the PSTN
       #   dial "IAX2/my.id@voipjet/19095551234", :from => "John Doe <9095551234>"
       #
+      # @return [DialStatus] the status of the dial operation
+      #
       def dial(to, options = {}, latch = nil)
         targets = to.respond_to?(:has_key?) ? to : Array(to)
 
@@ -111,29 +117,38 @@ module Adhearsion
       end
 
       class DialStatus
+        # The collection of calls created during the dial operation
         attr_accessor :calls
 
+        # @private
         def initialize
           @result = nil
         end
 
+        #
+        # The result of the dial operation.
+        #
+        # @return [Symbol] :no_answer, :answer, :timeout, :error
         def result
           @result || :no_answer
         end
 
+        # @private
         def answer!
           @result = :answer
         end
 
+        # @private
         def timeout!
           @result ||= :timeout
         end
 
+        # @private
         def error!
           @result ||= :error
         end
       end
 
-    end#module Dial
+    end
   end
 end

data/lib/adhearsion/call_controller/input.rb

@@ -10,6 +10,7 @@ module Adhearsion
         end
       end
 
+      #
       # Prompts for input via DTMF, handling playback of prompts,
       # timeouts, digit limits and terminator digits.
       #
@@ -23,7 +24,7 @@ module Adhearsion
       # :timeout, :terminator and :limit options may then be specified.
       # A block may be passed which is invoked on each digit being collected. If it returns true, the collection is terminated.
       #
-      # @param [Object] A list of outputs to play, as accepted by #play
+      # @param [Object, Array<Object>] args A list of outputs to play, as accepted by #play
       # @param [Hash] options Options to use for the menu
       # @option options [Boolean] :interruptible If the prompt should be interruptible or not. Defaults to true
       # @option options [Integer] :limit Digit limit (causes collection to cease after a specified number of digits have been collected)
@@ -32,8 +33,8 @@ module Adhearsion
       #
       # @return [Result] a result object from which the #response and #status may be established
       #
-      # @see play
-      # @see pass
+      # @see Output#play
+      # @see CallController#pass
       #
       def ask(*args, &block)
         options = args.last.kind_of?(Hash) ? args.pop : {}
@@ -51,8 +52,8 @@ module Adhearsion
           if result_of_menu.is_a?(MenuDSL::Menu::MenuGetAnotherDigit)
             next_digit = play_sound_files_for_menu menu_instance, sound_files
             menu_instance << next_digit if next_digit
-          end # case
-        end # while
+          end
+        end
 
         Result.new.tap do |result|
           result.response = menu_instance.result
@@ -103,7 +104,7 @@ module Adhearsion
       # Execution of the current context resumes after #ask finishes. If you wish to jump to an entirely different controller, use #pass.
       # Menu will return :failed if failure was reached, or :done if a match was executed.
       #
-      # @param [Object] A list of outputs to play, as accepted by #play
+      # @param [Object] args A list of outputs to play, as accepted by #play
       # @param [Hash] options Options to use for the menu
       # @option options [Integer] :tries Number of tries allowed before failure
       # @option options [Integer] :timeout Timeout in seconds before the first and between each input digit
@@ -111,8 +112,8 @@ module Adhearsion
       #
       # @return [Result] a result object from which the #response and #status may be established
       #
-      # @see play
-      # @see pass
+      # @see Output#play
+      # @see CallController#pass
       #
       def menu(*args, &block)
         options = args.last.kind_of?(Hash) ? args.pop : {}
@@ -158,8 +159,8 @@ module Adhearsion
               logger.debug "Menu received valid input (#{result_of_menu.new_extension}). Calling the matching hook."
               jump_to result_of_menu.match_object, :extension => result_of_menu.new_extension
               throw :finish
-            end # case
-          end # while
+            end
+          end
         end
 
         Result.new.tap do |result|
@@ -169,7 +170,8 @@ module Adhearsion
         end
       end
 
-      def play_sound_files_for_menu(menu_instance, sound_files) # :nodoc:
+      # @private
+      def play_sound_files_for_menu(menu_instance, sound_files)
         digit = nil
         if sound_files.any? && menu_instance.digit_buffer_empty?
           if menu_instance.interruptible
@@ -185,9 +187,11 @@ module Adhearsion
       # Waits for a single digit and returns it, or returns nil if nothing was pressed
       #
       # @param [Integer] the timeout to wait before returning, in seconds. nil or -1 mean no timeout.
-      # @return [String|nil] the pressed key, or nil if timeout was reached.
+      # @return [String, nil] the pressed key, or nil if timeout was reached.
+      #
+      # @private
       #
-      def wait_for_digit(timeout = 1) # :nodoc:
+      def wait_for_digit(timeout = 1)
         timeout = nil if timeout == -1
         timeout *= 1_000 if timeout
         input_component = execute_component_and_await_completion ::Punchblock::Component::Input.new :mode => :dtmf,
@@ -202,7 +206,8 @@ module Adhearsion
         parse_single_dtmf result
       end
 
-      def jump_to(match_object, overrides = nil) # :nodoc:
+      # @private
+      def jump_to(match_object, overrides = nil)
         if match_object.block
           instance_exec overrides[:extension], &match_object.block
         else
@@ -210,6 +215,6 @@ module Adhearsion
         end
       end
 
-    end # module
+    end
   end
 end

data/lib/adhearsion/call_controller/menu_dsl.rb

@@ -2,6 +2,7 @@
 
 module Adhearsion
   class CallController
+    # @private
     module MenuDSL
       extend ActiveSupport::Autoload
 

data/lib/adhearsion/call_controller/output.rb

@@ -5,8 +5,14 @@ module Adhearsion
     module Output
       PlaybackError = Class.new Adhearsion::Error # Represents failure to play audio, such as when the sound file cannot be found
 
+      #
+      # Speak output using text-to-speech (TTS)
+      #
+      # @param [String, #to_s] text The text to be rendered
+      # @param [Hash] options A set of options for output
+      #
       def say(text, options = {})
-        play_ssml(text, options) || output(:text, text.to_s, options)
+        play_ssml(text, options) || output(ssml_for_text(text.to_s), options)
       end
       alias :speak :say
 
@@ -54,6 +60,8 @@ module Adhearsion
       # Plays the specified input arguments, raising an exception if any can't be played.
       # @see play
       #
+      # @private
+      #
       def play!(*arguments)
         play(*arguments) or raise PlaybackError, "One of the passed outputs is invalid"
       end
@@ -62,25 +70,22 @@ module Adhearsion
       # Plays the given Date, Time, or Integer (seconds since epoch)
       # using the given timezone and format.
       #
-      # @param [Date|Time|DateTime] Time to be said.
-      # @param [Hash] Additional options to specify how exactly to say time specified.
-      #
-      # +:format+   - This format is used only to disambiguate times that could be interpreted in different ways.
+      # @param [Date, Time, DateTime] time Time to be said.
+      # @param [Hash] options Additional options to specify how exactly to say time specified.
+      # @option options [String] :format This format is used only to disambiguate times that could be interpreted in different ways.
       #   For example, 01/06/2011 could mean either the 1st of June or the 6th of January.
       #   Please refer to the SSML specification.
       # @see http://www.w3.org/TR/ssml-sayas/#S3.1
-      # +:strftime+ - This format is what defines the string that is sent to the Speech Synthesis Engine.
+      # @option options [String] :strftime This format is what defines the string that is sent to the Speech Synthesis Engine.
       #   It uses Time::strftime symbols.
       #
       # @return [Boolean] true if successful, false if the given argument could not be played.
       #
-      def play_time(*args)
-        argument, options = args.flatten
-        return false unless [Date, Time, DateTime].include? argument.class
+      def play_time(time, options = {})
+        return false unless [Date, Time, DateTime].include? time.class
 
-        options ||= {}
         return false unless options.is_a? Hash
-        play_ssml ssml_for_time(argument, options)
+        play_ssml ssml_for_time(time, options)
       end
 
       #
@@ -88,14 +93,13 @@ module Adhearsion
       # When playing numbers, Adhearsion assumes you're saying the number, not the digits. For example, play("100")
       # is pronounced as "one hundred" instead of "one zero zero".
       #
-      # @param [Numeric|String] Numeric or String containing a valid Numeric, like "321".
+      # @param [Numeric, String] Numeric or String containing a valid Numeric, like "321".
       #
       # @return [Boolean] true if successful, false if the given argument could not be played.
       #
-      def play_numeric(*args)
-        argument, options = args.flatten
-        if argument.kind_of?(Numeric) || argument =~ /^\d+$/
-          play_ssml ssml_for_numeric(argument, options)
+      def play_numeric(number, options = nil)
+        if number.kind_of?(Numeric) || number =~ /^\d+$/
+          play_ssml ssml_for_numeric(number, options)
         end
       end
 
@@ -104,30 +108,26 @@ module Adhearsion
       # SSML supports http:// paths and full disk paths.
       # The Punchblock backend will have to handle cases like Asterisk where there is a fixed sounds directory.
       #
-      # @param [String] http:// URL or full disk path to the sound file
-      # @param [Hash] Additional options to specify how exactly to say time specified.
-      # +:fallback+ - The text to play if the file is not available
+      # @param [String] file http:// URL or full disk path to the sound file
+      # @param [Hash] options Additional options to specify how exactly to say time specified.
+      # @option options [String] :fallback The text to play if the file is not available
       #
       # @return [Boolean] true on correct play of the file, false on file missing or not playable
       #
-      def play_audio(*args)
-        argument, options = args.flatten
-        play_ssml ssml_for_audio(argument, options)
+      def play_audio(file, options = nil)
+        play_ssml ssml_for_audio(file, options)
       end
 
-      def play_ssml(ssml, options = {}) # :nodoc:
+      # @private
+      def play_ssml(ssml, options = {})
         if [RubySpeech::SSML::Speak, Nokogiri::XML::Document].include? ssml.class
-          output :ssml, ssml.to_s, options
+          output ssml.to_s, options
         end
       end
 
-      def output(type, content, options = {}) # :nodoc:
-        options.merge! type => content
-        execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
-      end
-
-      def output!(type, content, options = {}) # :nodoc:
-        options.merge! type => content
+      # @private
+      def output(content, options = {})
+        options.merge! :ssml => content
         execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
       end
 
@@ -135,6 +135,8 @@ module Adhearsion
       # Same as interruptible_play, but throws an error if unable to play the output
       # @see interruptible_play
       #
+      # @private
+      #
       def interruptible_play!(*outputs)
         result = nil
         outputs.each do |output|
@@ -155,10 +157,10 @@ module Adhearsion
       #   input = interruptible_play ssml
       #   play input unless input.nil?
       #
-      # @param [String|Numeric|Date|Time|RubySpeech::SSML::Speak|Array|Hash] The argument to play to the user, or an array of arguments.
+      # @param [String, Numeric, Date, Time, RubySpeech::SSML::Speak, Array, Hash] The argument to play to the user, or an array of arguments.
       # @param [Hash] Additional options.
       #
-      # @return [String|Nil] The single DTMF character entered by the user, or nil if nothing was entered
+      # @return [String, nil] The single DTMF character entered by the user, or nil if nothing was entered
       #
       def interruptible_play(*outputs)
         result = nil
@@ -175,7 +177,8 @@ module Adhearsion
         result
       end
 
-      def detect_type(output) # :nodoc:
+      # @private
+      def detect_type(output)
         result = nil
         result = :time if [Date, Time, DateTime].include? output.class
         result = :numeric if output.kind_of?(Numeric) || output =~ /^\d+$/
@@ -183,7 +186,8 @@ module Adhearsion
         result ||= :text
       end
 
-      def play_ssml_for(*args) # :nodoc:
+      # @private
+      def play_ssml_for(*args)
         play_ssml ssml_for(args)
       end
 
@@ -191,10 +195,12 @@ module Adhearsion
       # Generates SSML for the argument and options passed, using automatic detection
       # Directly returns the argument if it is already an SSML document
       #
-      # @param [String|Hash|RubySpeech::SSML::Speak] the argument with options as accepted by the play_ methods, or an SSML document
+      # @param [String, Hash, RubySpeech::SSML::Speak] the argument with options as accepted by the play_ methods, or an SSML document
       # @return [RubySpeech::SSML::Speak] an SSML document
       #
-      def ssml_for(*args) # :nodoc:
+      # @private
+      #
+      def ssml_for(*args)
         return args[0] if args.size == 1 && args[0].is_a?(RubySpeech::SSML::Speak)
         argument, options = args.flatten
         options ||= {}
@@ -202,11 +208,13 @@ module Adhearsion
         send "ssml_for_#{type}", argument, options
       end
 
-      def ssml_for_text(argument, options = {}) # :nodoc:
+      # @private
+      def ssml_for_text(argument, options = {})
         RubySpeech::SSML.draw { argument }
       end
 
-      def ssml_for_time(argument, options = {}) # :nodoc:
+      # @private
+      def ssml_for_time(argument, options = {})
         interpretation = case argument
         when Date then 'date'
         when Time then 'time'
@@ -222,13 +230,15 @@ module Adhearsion
         end
       end
 
-      def ssml_for_numeric(argument, options = {}) # :nodoc:
+      # @private
+      def ssml_for_numeric(argument, options = {})
         RubySpeech::SSML.draw do
           say_as(:interpret_as => 'cardinal') { argument.to_s }
         end
       end
 
-      def ssml_for_audio(argument, options = {}) # :nodoc:
+      # @private
+      def ssml_for_audio(argument, options = {})
         fallback = (options || {}).delete :fallback
         RubySpeech::SSML.draw do
           audio(:src => argument) { fallback }
@@ -241,7 +251,8 @@ module Adhearsion
       #
       # @param [Object] String or Hash specifying output and options
       # @param [String] String with the digits that are allowed to interrupt output
-      # @return [String|nil] The pressed digit, or nil if nothing was pressed
+      #
+      # @return [String, nil] The pressed digit, or nil if nothing was pressed
       #
       def stream_file(argument, digits = '0123456789#*')
         result = nil

data/lib/adhearsion/call_controller/record.rb

@@ -9,7 +9,7 @@ module Adhearsion
       # Start a recording
       #
       # @param [Hash] options
-      # @param [Block] &block to process result of the record method
+      # @param [Block] block to process result of the record method
       # @option options [Boolean, Optional] :async Execute asynchronously. Defaults to false
       # @option options [Boolean, Optional] :start_beep Indicates whether subsequent record will be preceded with a beep. Default is true.
       # @option options [Boolean, Optional] :start_paused Whether subsequent record will start in PAUSE mode. Default is false.
@@ -19,8 +19,8 @@ module Adhearsion
       # @option options [String, Optional] :initial_timeout Controls how long (milliseconds) the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event.
       # @option options [String, Optional] :final_timeout Controls the length (milliseconds) of a period of silence after callers have spoken to conclude they finished.
       #
-      # @return recording object
-
+      # @return Punchblock::Component::Record::Recording
+      #
       def record(options = {})
         async = options.delete :async