adzap-voice_form 0.2.0 → 0.3.0

data/History.txt

@@ -1,3 +1,10 @@
+== 0.3.0 2009-03-22
+* Lots of refactoring for prompts. Prompts can now be a symbol for a component instance method.
+* Added prompt bargein option to set whether the caller can interrupt a prompt
+* Added Simon game example in the examples folder
+* Added as_digits helper
+* Added component start_voice_form class method to start the form without creating component instance first.
+
 == 0.2.0 2009-01-16
 * Updated to work with Adhearsion 0.8.0 release. Examples updated to match new usage.
 

data/README.markdown

@@ -1,4 +1,4 @@
-#VoiceForm
+# VoiceForm
 
 A plugin for Adhearsion to add form functionality and flow, similar to VoiceXML style forms.
 
@@ -6,7 +6,7 @@ By Adam Meehan (adam.meehan@gmail.com, [http://duckpunching.com/](http://duckpun
 
 Released under the MIT license.
 
-##Introduction
+## Introduction
 
 After developing VoiceXML (VXML) apps for quite a while and then trying Adhearsion, I found I missed 
 the VXML form element flow when writing components. Given that most interactions with an IVR system
@@ -17,7 +17,7 @@ using XML in a programmatic way, yuck! Also you are not using Ruby, so you miss
 The plugin attempts to emulate some of the VXML form flow for use in your Adhearsion components.
 
 
-##Install
+## Install
 
     sudo gem install adzap-voice_form --source=http://gems.github.com/
     
@@ -25,7 +25,7 @@ At the bottom your projects startup.rb file put
 
     require 'voice_form'
 
-##Example
+## Example
 
 I use the **speak** command in this example to give better context. The speak command is for TTS 
 and is currently disabled in Adhearsion. In your own application you can just use the **play**
@@ -34,22 +34,27 @@ command to play your sound files.
     class MyComponent
       include VoiceForm
 
+      MIN_AGE = 18
+
       voice_form do      
+        setup do
+          # Do stuff here before the form is run
+        end
       
         field(:age, :max_length => 3, :attempts => 3) do
           prompt :speak => "Please enter your age", :timeout => 2
           reprompt :speak => "Enter your age in years", :timeout => 2
           
           setup do
-            @max_age = 110
+            # Do stuff here before the field is run
           end
           
           timeout do
-            call_context.speak "You did not enter anything. Try again."
+            call.speak "You did not enter anything. Try again."
           end
                   
           validate do
-            @age.to_i <= @max_age
+            @age.to_i >= MIN_AGE
           end
           
           confirm(:accept => 1, :reject => 2, :timeout => 3, :attempts => 3) do
@@ -57,15 +62,15 @@ command to play your sound files.
           end
           
           invalid do
-            call_context.speak "Your age must be less than #{@max_age}. Try again."
+            call.speak "You must be at least #{MIN_AGE} to play. Try again."
           end
           
           success do
-            call_context.speak "You are #{@age} years old."
+            call.speak "You are #{@age} years old."
           end
           
           failure do
-            call_context.speak "You could not enter your age. Thats a bad sign."
+            call.speak "You could not enter your age. Thats a bad sign. You might be too old."
           end      
         end
        
@@ -74,6 +79,15 @@ command to play your sound files.
 
 In your dialplan:
 
+For Adhearsion 0.7.999
+
+    general {
+      my_component = new_my_component
+      my_component.start_voice_form(self)
+    }
+
+For Adhearsion 0.8.0
+
     general {
       MyComponent.new.start_voice_form(self)
     }
@@ -103,10 +117,6 @@ You can also use `form.restart` to start the form over from the beginning.
 
 The form setup block is only run once and is not executed again, even with a `form.restart`.
 
-The `voice_form` method takes only one option
-
-- :call_context - to nominate the call context method if other than call context
-                                  
 
 ### field
 
@@ -115,11 +125,11 @@ in a `voice_form` or on its own inside a component method.
 
 The options available are:
 
-- :length       - the number of digits to accept
-- :min_length   - minimum number of digits to accept
-- :max_length   - maximum number of digits to accept
-- :attempts     - number of tries to get a valid input
-- :call_context - the method name for the call context if other than 'call_context'
+- :length     - the number of digits to accept
+- :min_length - minimum number of digits to accept
+- :max_length - maximum number of digits to accept
+- :attempts   - number of tries to get a valid input
+- :call       - the method name for the call context if other than 'call'. Used for standalone fields not is a form.
 
 All fields defined get an accessor method defined of the same name in the component class.
 This means you can access its value using the instance variable or the accessor method inside any of
@@ -131,8 +141,9 @@ hash of options to control the prompt such as:
 
 - :play    - play one or more sound files
 - :speak   - play TTS text (needs my Adhearsion hack for speak in input command)
-- :timeout - number of seconds to wait for input
+- :timeout - number of seconds to wait for input. Default is 5.
 - :repeats - number of attempts to use this prompt until the next one is used
+- :bargein - whether to allow caller to interrupt prompt. Default is true.
 
 The length expected for the input is taken from the options passed to the `field` method.
 
@@ -160,26 +171,26 @@ instance variables and component methods are available to use including the call
 
 The details of each callback are as follows
 
-### setup
+#### setup
 
 This is run once only for a field if defined before any prompts
 
-### timeout
+#### timeout
 
-This is run if no input is received.
+This is run if no input is recevied or input is not of a valid length as defined by length or min_length
+field options.
 
-### validate
+#### validate
 
 This is run after input of a valid length. The validate block is where you put validation logic of the
 value just input by the user. The block should return `true` if the value is valid or `false` otherwise.
 If the validate callback returns false then the invalid callback will be called next.
 
-### invalid
+#### invalid
 
-The invalid callback is called if the input value is not of a valid length or the validate block returns
-false.
+The invalid callback is called if validate block returns false.
 
-### confirm
+#### confirm
 
 The confirm callback is called after the input has been validated. The confirm callback is a little different
 from the others. Idea is that you return either an array or string of the audio files or TTS text, respectively,
@@ -199,7 +210,7 @@ For example, in a field called my_field:
       ['you-entered', @my_field.scan(/\d/), 'is-this-correct', 'press-1-accept-2-try-again'].flatten
     end
 
-The above will `play` the array of audo files as the prompt for confirmation. 
+The above will `play` the array of audio files as the prompt for confirmation. 
    
     confirm(:accept => 1, :reject => 2, :attempts => 3) do
       "You entered #{@my_field}. Is this correct? Press 1 to accept or 2 try again."
@@ -207,12 +218,43 @@ The above will `play` the array of audo files as the prompt for confirmation.
 
 The above will `speak` the string as the prompt for confirmation. 
 
-If no valid input is entered for the confirmation 
+If no valid input is entered for the confirmation then another you will be reprompted to enter the field value. 
+
+
+### Form methods
+
+Inside a callback you have the `form` method available. The returns the instance of the current form. The form
+has some methods to allow you to perform form actions which manipulate the form stack. These actions are as follows:
+
+#### form.goto
+
+Inside any callback you can use the `goto` command to designate which field the form should run after the
+current field. Normally the form will progress through the fields in the order defined, but a goto with shift
+the current form position to the field name pass to it like so:
+
+    failure do
+      form.goto :other_field_name
+    end
+
+The form continues from the field in the goto run each subsequent field in order. If the goto field is above the
+current field then the current field will be executed again when it is reached in the stack. If the goto field
+is below the current field then form will continue there, skipping whatever fields may lie between the current
+and the goto field.
+
+
+#### form.restart
+
+The form may be restarted from the start at any point with `form.restart`. This will go back to the top of the
+form and proceed through each field again. The form setup will not be run again however.
+
+
+#### form.exit
 
-TODO: More docs
+To exit the form after the current field is complet just execute `form.exit`. The application will then be 
+returned to where the form was started, be it a dialplan or another form.
 
 
-##Credits
+## Credits
 
 Adam Meehan (adam.meehan@gmail.com, [http://duckpunching.com/](http://duckpunching.com/))
 

data/Rakefile

@@ -5,7 +5,7 @@ require 'date'
 require 'spec/rake/spectask'
 
 GEM = "voice_form"
-GEM_VERSION = "0.2.0"
+GEM_VERSION = "0.3.0"
 AUTHOR = "Adam Meehan"
 EMAIL = "adam.meehan@gmail.com"
 HOMEPAGE = "http://github.com/adzap/voice_form"

data/examples/my_component.rb

@@ -1,19 +1,23 @@
 class MyComponent
   include VoiceForm
 
-  delegate :play, :speak, :to => :call_context
+  MAX_AGE = 110
+
+  delegate :play, :speak, :to => :call
 
   voice_form do      
     field(:age, :max_length => 3, :attempts => 3) do
       prompt :speak => "Please enter your age", :timeout => 2, :repeats => 2
       reprompt :speak => "Enter your age in years", :timeout => 2
-      
-      setup { @max_age = 110 }
-              
-      validate { @age.to_i < @max_age }
-      
+
+      confirm do
+        "Are you sure you are #{@age} years old? Press 1 to confirm, or 2 to retry."
+      end
+
+      validate { @age.to_i < MAX_AGE }
+
       invalid do
-        speak "Your age must be less than #{@max_age}. Try again."
+        speak "You cannot be that old. Try again."
       end
       
       success do
@@ -30,7 +34,7 @@ class MyComponent
     end
     
     field(:postcode, :length => 4, :attempts => 5) do
-      prompt :speak => "Please enter your 4 digit post code", :timeout => 3
+      prompt :speak => "Please enter your 4 digit postcode", :timeout => 3
       
       validate { @postcode[0..0] != '0' }
       

data/examples/simon_game_voice_form.rb

@@ -0,0 +1,47 @@
+methods_for :dialplan do
+  def simon_game_voice_form
+    SimonGameVoiceForm.start_voice_form(self)
+  end
+end
+
+class SimonGameVoiceForm
+  include VoiceForm
+
+  voice_form do
+    setup do
+      @number = ''
+    end
+
+    field(:attempt, :attempts => 1) do
+      prompt :play => :current_number, :bargein => false, :timeout => 2
+
+      setup do
+        @number << random_number
+      end
+
+      validate do
+        @attempt == @number
+      end
+
+      success do
+        call.play 'good'
+        form.restart
+      end
+
+      failure do
+        call.play %W[#{@number.length-1} times wrong-try-again-smarty]
+        @number = ''
+        form.restart
+      end
+    end
+
+  end
+
+  def random_number
+    rand(10).to_s
+  end
+
+  def current_number
+    as_digits(@number)
+  end
+end

data/lib/voice_form/form.rb

@@ -10,7 +10,9 @@ module VoiceForm
       @options = options
       @form_stack = []
       @stack_index = 0
-      self.instance_eval(&block)
+
+      instance_eval(&block)
+      raise 'A form requires at least one field defined' if fields.empty?
     end
     
     def run(component)
@@ -30,10 +32,7 @@ module VoiceForm
     end
     
     def goto(name)
-      index = nil
-      form_stack.each_with_index {|slot, i| 
-        index = i and break if form_field?(slot) && slot.name == name
-      }
+      index = field_index(name)
       raise "goto failed: No form field found with name '#{name}'." unless index
       @stack_index = index
     end
@@ -43,7 +42,7 @@ module VoiceForm
     end
     
     def exit
-      @exit_form = true
+      @exit = true
     end
     
     private 
@@ -53,7 +52,7 @@ module VoiceForm
     end
     
     def run_form_stack
-      while @stack_index < form_stack.size do
+      while @stack_index < form_stack.size && !@exit do
         slot = form_stack[@stack_index]
         @stack_index += 1
         
@@ -64,8 +63,6 @@ module VoiceForm
           @current_field = nil
           @component.instance_eval(&slot)
         end
-        
-        break if @exit_form
       end
       @stack_index = 0
       @current_field = nil
@@ -73,11 +70,10 @@ module VoiceForm
     
     def add_field_accessors
       return if @accessors_added
-      
-      form_stack.each do |field|
-        next unless form_field?(field)
+
+      fields.keys.each do |field_name|
         @component.class.class_eval do
-          attr_accessor field.name
+          attr_accessor field_name
         end
       end
       
@@ -87,7 +83,19 @@ module VoiceForm
     def form_field?(slot)
       slot.is_a?(VoiceForm::FormField)
     end
-    
+
+    def fields
+      @fields ||= form_stack.inject({}) do |flds,s|
+        flds[s.name] = s if form_field?(s)
+        flds
+      end
+    end
+
+    def field_index(field)
+      form_stack.each_with_index {|slot, i|
+        return i if form_field?(slot) && slot.name == field.to_sym
+      }
+    end
   end
   
 end

data/lib/voice_form/form_field.rb

@@ -1,24 +1,28 @@
 module VoiceForm
 
   class FormField
+    cattr_accessor :default_prompt_options
     attr_reader :name
-    attr_accessor :prompts
+
+    self.default_prompt_options = { :bargein => true, :timeout => 5 }
 
     def initialize(name, options, component, &block)
       @name, @options, @component = name, options, component
-      @options.reverse_merge!(:attempts => 5, :call_context => 'call_context')
+      @options.reverse_merge!(:attempts => 5, :call => 'call')
       @callbacks = {}
-      @prompts = []
-      self.instance_eval(&block)
+      @prompt_queue = []
+
+      instance_eval(&block)
+      raise 'A field requires a prompt to be defined' if @prompt_queue.empty?
     end
 
     def prompt(options)
-      add_prompts(options.reverse_merge(:timeout => 5))
+      add_prompt(options.reverse_merge(self.class.default_prompt_options))
     end
 
     def reprompt(options)
-      raise 'A reprompt can only be used after a prompt' if @prompts.empty?
-      add_prompts(options.reverse_merge(:timeout => 5))
+      raise 'A reprompt can only be used after a prompt' if @prompt_queue.empty?
+      add_prompt(options.reverse_merge(self.class.default_prompt_options))
     end
 
     def setup(&block)
@@ -47,29 +51,30 @@ module VoiceForm
 
     def confirm(options={}, &block)
       options.reverse_merge!(
-        :attempts => 3,
-        :accept   => 1,
-        :reject   => 2,
-        :timeout  => 3
+        self.class.default_prompt_options.merge(
+          :attempts => 3,
+          :accept   => 1,
+          :reject   => 2
+        )
       )
-      @confirmation_options = options.merge(:block => block)
+      @confirmation_options = options.merge(:message => block)
     end
 
     def run(component=nil)
       @component = component if component
 
-      set_component_value('')
-
       run_callback(:setup)
 
       result = 1.upto(@options[:attempts]) do |attempt|
-        if get_input(attempt).empty?
+        prompt = prompt_for_attempt(attempt)
+
+        @value = get_input(prompt)
+
+        unless valid_length?
           run_callback(:timeout)
           next
         end
 
-        set_component_value @value
-
         if input_valid?
           if value_confirmed?
             break 0
@@ -89,48 +94,43 @@ module VoiceForm
 
     private
 
-    def prompt_for_attempt(attempt)
-      prompt = if attempt == 1 || @prompts.size == 1 then
-        @prompts.first
+    def get_input(prompt)
+      method  = prompt[:method]
+      message = prompt[:message]
+
+      if prompt[:bargein]
+        prompt[method] = message
       else
-        @prompts[attempt-1] || @prompts.last
+        call.send(method, message)
       end
-      evaluate_prompt(prompt)
-    end
 
-    def get_input(attempt)
-      input_options = @options.dup
-      input_options.merge!(prompt_for_attempt(attempt))
-      args = [ input_options ]
-      length = input_options.delete(:length) || input_options.delete(:max_length)
-      args.unshift(length) if length
-      @value = call_context.input(*args)
+      args = [ prompt.slice(method, :timeout, :accept_key) ]
+      args.unshift(prompt[:length]) if prompt[:length]
+      call.input(*args)
     end
 
     def input_valid?
-      @value.size >= minimum_length &&
-        @value.size <= maximum_length &&
-        run_callback(:validate)
+      run_callback(:validate)
+    end
+
+    def valid_length?
+      !@value.empty? &&
+        @value.size >= minimum_length &&
+        @value.size <= maximum_length
     end
 
     def value_confirmed?
       return true unless @confirmation_options
-      options = @confirmation_options.dup
 
-      if block = options.delete(:block)
-        message = @component.instance_eval(&block)
-        prompt = case message
-        when Array:  {:play  => message}
-        when String: {:speak => message}
-        end
-        prompt.merge!(options.slice(:timeout))
-      end
-      1.upto(options[:attempts]) do |attempt|
-        value = call_context.input(1, prompt)
-        case value
-        when options[:accept].to_s
+      prompt = evaluate_prompt(@confirmation_options)
+      prompt[:method] = prompt[:message].is_a?(Array) ? :play : :speak
+      prompt[:length] = [ prompt[:accept].to_s.size, prompt[:reject].to_s.size ].max
+
+      1.upto(prompt[:attempts]) do |attempt|
+        case get_input(prompt)
+        when prompt[:accept].to_s
           return true
-        when options[:reject].to_s
+        when prompt[:reject].to_s
           return false
         else
           next
@@ -140,6 +140,7 @@ module VoiceForm
     end
 
     def run_callback(callback)
+      set_component_value @value
       if block = @callbacks[callback]
         result = @component.instance_eval(&block)
         @value = get_component_value
@@ -154,7 +155,7 @@ module VoiceForm
     end
 
     def get_component_value
-      @component.send("#{@name}")
+      @component.send(@name)
     end
 
     def minimum_length
@@ -165,20 +166,44 @@ module VoiceForm
       @options[:max_length] || @options[:length] || @value.size
     end
 
-    def call_context
-      @call_context ||= @component.send(@options[:call_context])
+    def call
+      @call ||= @component.send(@options[:call])
     end
 
-    def add_prompts(options)
+    def add_prompt(options)
+      method  = options.has_key?(:play) ? :play : :speak
+      options[:message] = options.delete(method)
+      options[:method]  = method
+      options[:length]  = @options[:length] || @options[:max_length]
+
       repeats = options[:repeats] || 1
-      @prompts += ([options] * repeats)
+      @prompt_queue += ([options] * repeats)
+    end
+
+    def prompt_for_attempt(attempt)
+      prompt = if attempt == 1 || @prompt_queue.size == 1 then
+        @prompt_queue.first
+      else
+        @prompt_queue[attempt-1] || @prompt_queue.last
+      end
+      evaluate_prompt(prompt)
     end
 
     def evaluate_prompt(prompt)
-      key = prompt.has_key?(:play) ? :play : :speak
-      message = prompt[key]
-      message = @component.instance_eval(&message) if message.is_a?(Proc)
-      prompt.merge(key => message)
+      options = prompt.dup
+      message = options[:message]
+
+      message = case message
+      when String, Array
+        message
+      when Symbol
+        @component.send(message)
+      when Proc
+        @component.instance_eval(&message)
+      end
+     
+      options[:message] = message
+      options
     end
   end