adhearsion 1.2.6 → 2.0.0.alpha1

data/lib/adhearsion/call_controller/menu.rb

@@ -0,0 +1,124 @@
+module Adhearsion
+  class CallController
+    module Menu
+
+      # Creates and manages a multiple choice menu driven by DTMF, handling playback of prompts,
+      # invalid input, retries and timeouts, and final failures.
+      #
+      # @example A complete example of the method is as follows:
+      #   menu "Welcome, ", "/opt/sounds/menu-prompt.mp3", :tries => 2, :timeout => 10 do
+      #     match 1, OperatorController
+      #
+      #     match 10..19 do
+      #       pass DirectController
+      #     end
+      #
+      #     match 5, 6, 9 do |exten|
+      #      play "The #{exten} extension is currently not active"
+      #     end
+      #
+      #     match '7', OfficeController
+      #
+      #     invalid { play "Please choose a valid extension" }
+      #     timeout { play "Input timed out, try again." }
+      #     failure { pass OperatorController }
+      #   end
+      #
+      # The first arguments to #menu will be a list of sounds to play, as accepted by #play, including strings for TTS, Date and Time objects, and file paths.
+      # :tries and :timeout options respectively specify the number of tries before going into failure, and the timeout in seconds allowed on each digit input.
+      # The most important part is the following block, which specifies how the menu will be constructed and handled.
+      #
+      # #match handles connecting an input pattern to a payload.
+      # The pattern can be one or more of: an integer, a Range, a string, an Array of the possible single types.
+      # Input is matched against patterns, and the first exact match has it's payload executed.
+      # Matched input is passed in to the associated block, or to the controller through #options.
+      #
+      # Allowed payloads are the name of a controller class, in which case it is executed through its #run method, or a block.
+      #
+      # #invalid has its associated block executed when the input does not possibly match any pattern.
+      # #timeout's block is run when time expires before or between input digits.
+      # #failure runs its block when the maximum number of tries is reached without an input match.
+      #
+      # Execution of the current context resumes after #menu 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 [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
+      #
+      # @return [Symbol] :failure on failure, :done if a match is reached and executed. Will only return if control is not passed.
+      #
+      # @raise [ArgumentError] Raised if no block is passed in
+      #
+      # @see play
+      # @see pass
+      #
+      def menu(*args, &block)
+        raise ArgumentError, "You must provide a block to the #menu method." unless block_given?
+
+        options = args.last.kind_of?(Hash) ? args.pop : {}
+        sound_files = args.flatten
+
+        menu_instance = MenuDSL::Menu.new options, &block
+        result_of_menu = nil
+
+        until MenuDSL::Menu::MenuResultDone === result_of_menu
+          if menu_instance.should_continue?
+            result_of_menu = menu_instance.continue
+          else
+            logger.debug "Menu failed to get valid input. Executing failure hook."
+            menu_instance.execute_failure_hook
+            return :failed
+          end
+
+          case result_of_menu
+          when MenuDSL::Menu::MenuResultInvalid
+            logger.debug "Menu get invalid input. Executing invalid hook and restarting."
+            menu_instance.execute_invalid_hook
+            menu_instance.restart!
+            result_of_menu = nil
+          when MenuDSL::Menu::MenuGetAnotherDigit
+            next_digit = play_sound_files_for_menu menu_instance, sound_files
+            if next_digit
+              menu_instance << next_digit
+            else
+              case result_of_menu
+              when MenuDSL::Menu::MenuGetAnotherDigitOrFinish
+                jump_to result_of_menu.match_object, :extension => result_of_menu.new_extension
+                return true
+              when MenuDSL::Menu::MenuGetAnotherDigitOrTimeout
+                logger.debug "Menu timed out. Executing timeout hook and restarting."
+                menu_instance.execute_timeout_hook
+                menu_instance.restart!
+                result_of_menu = nil
+              end
+            end
+          when MenuDSL::Menu::MenuResultFound
+            logger.debug "Menu got a valid input (#{result_of_menu.new_extension}). Executing the match."
+            jump_to result_of_menu.match_object, :extension => result_of_menu.new_extension
+            return true
+          end # case
+        end # while
+        return :done
+      end
+
+      def play_sound_files_for_menu(menu_instance, sound_files)
+        digit = nil
+        if sound_files.any? && menu_instance.digit_buffer_empty?
+          digit = interruptible_play *sound_files
+        end
+        digit || wait_for_digit(menu_instance.timeout)
+      end
+
+      def jump_to(match_object, overrides = nil)
+        if match_object.block
+          instance_exec overrides[:extension], &match_object.block
+        else
+          invoke match_object.match_payload, overrides
+        end
+      end
+
+    end # module
+  end
+end

data/lib/adhearsion/call_controller/output.rb

@@ -0,0 +1,267 @@
+module Adhearsion
+  class CallController
+    module Output
+      def speak(text, options = {})
+        play_ssml(text, options) || output(:text, text, options)
+      end
+
+      #
+      # Plays the specified sound file names. This method will handle Time/DateTime objects (e.g. Time.now),
+      # Fixnums (e.g. 1000), Strings which are valid Fixnums (e.g "123"), and direct sound files. To specify how the Date/Time objects are said
+      # pass in as an array with the first parameter as the Date/Time/DateTime object along with a hash with the
+      # additional options. See play_time for more information.
+      #
+      # @example Play file hello-world
+      #   play 'http://www.example.com/hello-world.mp3'
+      #   play '/path/on/disk/hello-world.wav'
+      # @example Speak current time
+      #   play Time.now
+      # @example Speak today's date
+      #   play Date.today
+      # @example Speak today's date in a specific format
+      #   play Date.today, :strftime => "%d/%m/%Y", :format => "dmy"
+      # @example Play sound file, speak number, play two more sound files
+      #   play %w"http://www.example.com/a-connect-charge-of.wav 22 /path/to/cents-per-minute.wav /path/to/will-apply.mp3"
+      # @example Play two sound files
+      #   play "/path/to/you-sound-cute.mp3", "/path/to/what-are-you-wearing.wav"
+      #
+      # @return [Boolean] true is returned if everything was successful. Otherwise, false indicates that
+      #   some sound file(s) could not be played.
+      #
+      # @see play_time
+      # @see play_numeric
+      # @see play_audio
+      #
+      def play(*arguments)
+        arguments.inject(true) do |value, argument|
+          value = case argument
+          when Hash
+            play_ssml_for argument.delete(:value), argument
+          when RubySpeech::SSML::Speak
+            play_ssml argument
+          else
+            play_ssml_for argument
+          end
+        end
+      end
+
+      #
+      # Plays the specified input arguments, raising an exception if any can't be played.
+      # @see play
+      #
+      def play!(*arguments)
+        play *arguments or raise Adhearsion::PlaybackError, "One of the passed outputs is invalid"
+      end
+
+      #
+      # 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.
+      #   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.
+      #   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
+
+        options ||= {}
+        return false unless options.is_a? Hash
+        play_ssml ssml_for_time(argument, options)
+      end
+
+      #
+      # Plays the given Numeric argument or string representing a decimal number.
+      # 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".
+      #
+      # @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)
+        end
+      end
+
+      #
+      # Plays the given audio file.
+      # 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
+      #
+      # @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)
+      end
+
+      def play_ssml(ssml, options = {})
+        if [RubySpeech::SSML::Speak, Nokogiri::XML::Document].include? ssml.class
+          output :ssml, ssml.to_s, options
+        end
+      end
+
+      def output(type, content, options = {})
+        options.merge! type => content
+        execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
+      end
+
+      def output!(type, content, options = {})
+        options.merge! type => content
+        execute_component_and_await_completion ::Punchblock::Component::Output.new(options)
+      end
+
+      #
+      # Same as interruptible_play, but throws an error if unable to play the output
+      # @see interruptible_play
+      #
+      def interruptible_play!(*outputs)
+        result = nil
+        outputs.each do |output|
+          result = stream_file output
+          break unless result.nil?
+        end
+        result
+      end
+
+      #
+      # Plays the given output, allowing for DTMF input of a single digit from the user
+      # At the end of the played file it returns nil
+      #
+      # @example Ask the user for a number, then play it back
+      #   ssml = RubySpeech::SSML.draw do
+      #     "Please press a button"
+      #   end
+      #   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 [Hash] Additional options.
+      #
+      # @return [String|Nil] The single DTMF character entered by the user, or nil if nothing was entered
+      #
+      def interruptible_play(*outputs)
+        result = nil
+        outputs.each do |output|
+          begin
+            result = interruptible_play! output
+          rescue PlaybackError => e
+            # Ignore this exception and play the next output
+            logger.warn e.message
+          ensure
+            break if result
+          end
+        end
+        result
+      end
+
+      def detect_type(output)
+        result = nil
+        result = :time if [Date, Time, DateTime].include? output.class
+        result = :numeric if output.kind_of?(Numeric) || output =~ /^\d+$/
+        result = :audio if !result && (/\//.match(output.to_s) || URI::regexp(%w(http https)).match(output.to_s))
+        result ||= :text
+      end
+
+      def play_ssml_for(*args)
+        play_ssml ssml_for(args)
+      end
+
+      #
+      # 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
+      # @return [RubySpeech::SSML::Speak] an SSML document
+      #
+      def ssml_for(*args)
+        return args[0] if args.size == 1 && args[0].is_a?(RubySpeech::SSML::Speak)
+        argument, options = args.flatten
+        options ||= {}
+        type = detect_type argument
+        send "ssml_for_#{type}", argument, options
+      end
+
+      def ssml_for_text(argument, options = {})
+        RubySpeech::SSML.draw { argument }
+      end
+
+      def ssml_for_time(argument, options = {})
+        interpretation = case argument
+        when Date then 'date'
+        when Time then 'time'
+        end
+
+        format = options.delete :format
+        strftime = options.delete :strftime
+
+        time_to_say = strftime ? argument.strftime(strftime) : argument.to_s
+
+        RubySpeech::SSML.draw do
+          say_as(:interpret_as => interpretation, :format => format) { time_to_say }
+        end
+      end
+
+      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 = {})
+        fallback = (options || {}).delete :fallback
+        RubySpeech::SSML.draw do
+          audio(:src => argument) { fallback }
+        end
+      end
+
+      #
+      # Plays a single output, not only files, accepting interruption by one of the digits specified
+      # Currently still stops execution, will be fixed soon in Punchblock
+      #
+      # @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
+      #
+      def stream_file(argument, digits = '0123456789#*')
+        result = nil
+        ssml = ssml_for argument
+        output_component = ::Punchblock::Component::Output.new :ssml => ssml.to_s
+        input_stopper_component = ::Punchblock::Component::Input.new :mode => :dtmf,
+          :grammar => {
+            :value => grammar_accept(digits).to_s
+          }
+        input_stopper_component.register_event_handler ::Punchblock::Event::Complete do |event|
+          logger.warn "#stream_file Handling input complete event."
+          output_component.stop! unless output_component.complete?
+        end
+        write_and_await_response input_stopper_component
+        begin
+          execute_component_and_await_completion output_component
+        rescue StandardError => e
+          raise Adhearsion::PlaybackError, "Output failed for argument #{argument.inspect}"
+        end
+        input_stopper_component.stop! if input_stopper_component.executing?
+        reason = input_stopper_component.complete_event.reason
+        result = reason.interpretation if reason.respond_to? :interpretation
+        return parse_single_dtmf result unless result.nil?
+        result
+      end
+    end # Output
+  end # CallController
+end # Adhearsion

data/lib/adhearsion/call_controller/record.rb

@@ -0,0 +1,42 @@
+module Adhearsion
+  class CallController
+    module Record
+      #
+      # Start a recording
+      #
+      # @param [Hash] options
+      # @param [Block] &block to process result of the record method
+      # @option options [Boolean, Optional] :async Execute asynchronously. Defaults to false
+      # @option options [Proc, Optional] :on_complete Block to be executed on completion when this method is invoked asynchronously
+      # @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.
+      # @option options [String, Optional] :max_duration Indicates the maximum duration (milliseconds) for a recording.
+      # @option options [String, Optional] :format File format used during recording.
+      # @option options [String, Optional] :format File format used during recording.
+      # @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
+
+      def record(options = {}, &block)
+        async = options.delete(:async) ? true : false
+        on_complete = options.delete :on_complete
+
+        component = ::Punchblock::Component::Record.new options
+
+        if async
+          execute_component(component).tap do |result|
+            # FIXME: Setting the callback after we begin execution constitutes a race condition. We need to mock the component creation here, since the tests assume we're using whatever is returned by component exection, and that's what we pass the complete event to
+            result.register_event_handler Punchblock::Event::Complete do |event|
+              catching_standard_errors { on_complete.call event }
+            end
+          end
+        else
+          execute_component_and_await_completion(component).tap do |result|
+            yield result.complete_event if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/call_controller/utility.rb

@@ -0,0 +1,60 @@
+module Adhearsion
+  class CallController
+    module Utility
+
+      # Utility method for DTMF GRXML grammars
+      #
+      # @param [Integer] Number of digits to accept in the grammar.
+      # @return [RubySpeech::GRXML::Grammar] A grammar suitable for use in SSML prompts
+      #
+      def grammar_digits(digits = 1)
+        RubySpeech::GRXML.draw :mode => 'dtmf', :root => 'inputdigits' do
+          rule id: 'inputdigits', scope: 'public' do
+            item repeat: digits.to_s do
+              one_of do
+                0.upto(9) { |d| item { d.to_s } }
+              end
+            end
+          end
+        end
+      end # grammar_digits
+
+      # Utility method to create a single-digit grammar to accept only some digits
+      #
+      # @param [String] String representing the digits to accept
+      # @return [RubySpeech::GRXML::Grammar] A grammar suitable for use in SSML prompts
+      #
+      def grammar_accept(digits = '0123456789#*')
+        allowed_digits = '0123456789#*'
+        gram_digits = digits.chars.select { |x| allowed_digits.include? x }
+
+        RubySpeech::GRXML.draw :mode => 'dtmf', :root => 'inputdigits' do
+          rule id: 'inputdigits', scope: 'public' do
+            one_of do
+              gram_digits.each { |d| item { d.to_s } }
+            end
+          end
+        end
+      end
+
+      #
+      # Parses a single DTMF tone in the format dtmf-*
+      #
+      # @param [String] the tone string to be parsed
+      # @return [String] the digit in case input was 0-9, * or # if star or pound respectively
+      #
+      def parse_single_dtmf(result)
+        return if result.nil?
+        case tone = result.split('-')[1]
+        when 'star'
+          '*'
+        when 'pound'
+          '#'
+        else
+          tone
+        end
+      end
+
+    end#module
+  end
+end