voice_form 0.3.0

data/lib/voice_form.rb

@@ -0,0 +1,3 @@
+require 'voice_form/form_methods'
+require 'voice_form/form'
+require 'voice_form/form_field'

data/lib/voice_form/form.rb

@@ -0,0 +1,101 @@
+module VoiceForm
+
+  class Form
+    include VoiceForm::FormMethods
+
+    attr_accessor :form_stack
+    attr_reader :current_field
+    
+    def initialize(options={}, &block)
+      @options = options
+      @form_stack = []
+      @stack_index = 0
+
+      instance_eval(&block)
+      raise 'A form requires at least one field defined' if fields.empty?
+    end
+    
+    def run(component)
+      @component = component
+      
+      add_field_accessors
+      run_setup
+      run_form_stack
+    end
+    
+    def setup(&block)
+      @setup = block
+    end
+    
+    def do_block(&block)
+      form_stack << block
+    end
+    
+    def goto(name)
+      index = field_index(name)
+      raise "goto failed: No form field found with name '#{name}'." unless index
+      @stack_index = index
+    end
+    
+    def restart
+      @stack_index = 0
+    end
+    
+    def exit
+      @exit = true
+    end
+    
+    private 
+    
+    def run_setup
+      @component.instance_eval(&@setup) if @setup
+    end
+    
+    def run_form_stack
+      while @stack_index < form_stack.size && !@exit do
+        slot = form_stack[@stack_index]
+        @stack_index += 1
+        
+        if form_field?(slot)
+          @current_field = slot.name
+          slot.run(@component)
+        else
+          @current_field = nil
+          @component.instance_eval(&slot)
+        end
+      end
+      @stack_index = 0
+      @current_field = nil
+    end
+    
+    def add_field_accessors
+      return if @accessors_added
+
+      fields.keys.each do |field_name|
+        @component.class.class_eval do
+          attr_accessor field_name
+        end
+      end
+      
+      @accessors_added = true
+    end
+    
+    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

@@ -0,0 +1,209 @@
+module VoiceForm
+
+  class FormField
+    cattr_accessor :default_prompt_options
+    attr_reader :name
+
+    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 => 'call')
+      @callbacks = {}
+      @prompt_queue = []
+
+      instance_eval(&block)
+      raise 'A field requires a prompt to be defined' if @prompt_queue.empty?
+    end
+
+    def prompt(options)
+      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 @prompt_queue.empty?
+      add_prompt(options.reverse_merge(self.class.default_prompt_options))
+    end
+
+    def setup(&block)
+      @callbacks[:setup] = block
+    end
+
+    def validate(&block)
+      @callbacks[:validate] = block
+    end
+
+    def invalid(&block)
+      @callbacks[:invalid] = block
+    end
+
+    def timeout(&block)
+      @callbacks[:timeout] = block
+    end
+
+    def success(&block)
+      @callbacks[:success] = block
+    end
+
+    def failure(&block)
+      @callbacks[:failure] = block
+    end
+
+    def confirm(options={}, &block)
+      options.reverse_merge!(
+        self.class.default_prompt_options.merge(
+          :attempts => 3,
+          :accept   => 1,
+          :reject   => 2
+        )
+      )
+      @confirmation_options = options.merge(:message => block)
+    end
+
+    def run(component=nil)
+      @component = component if component
+
+      run_callback(:setup)
+
+      result = 1.upto(@options[:attempts]) do |attempt|
+        @value = get_input(prompt_for_attempt(attempt))
+
+        unless valid_length?
+          run_callback(:timeout)
+          next
+        end
+
+        if input_valid?
+          if value_confirmed?
+            break 0
+          else
+            next
+          end
+        else
+          run_callback(:invalid)
+        end
+      end
+      if result == 0
+        run_callback(:success)
+      else
+        run_callback(:failure)
+      end
+      set_component_value @value
+    end
+
+    private
+
+    def get_input(prompt)
+      method  = prompt[:method]
+      message = prompt[:message]
+
+      if prompt[:bargein]
+        prompt[method] = message
+      else
+        call.send(method, message)
+      end
+
+      args = [ prompt.slice(method, :timeout, :accept_key) ]
+      args.unshift(prompt[:length]) if prompt[:length]
+      call.input(*args)
+    end
+
+    def input_valid?
+      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
+
+      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 prompt[:reject].to_s
+          return false
+        else
+          next
+        end
+      end
+      false
+    end
+
+    def run_callback(callback)
+      if block = @callbacks[callback]
+        set_component_value @value
+        result = @component.instance_eval(&block)
+        @value = get_component_value
+        result
+      else
+        true
+      end
+    end
+
+    def set_component_value(value)
+      @component.send("#{@name}=", @value)
+    end
+
+    def get_component_value
+      @component.send(@name)
+    end
+
+    def minimum_length
+      @options[:min_length] || @options[:length] || 1
+    end
+
+    def maximum_length
+      @options[:max_length] || @options[:length] || @value.size
+    end
+
+    def call
+      @call ||= @component.send(@options[:call])
+    end
+
+    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
+      @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)
+      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
+
+end

data/lib/voice_form/form_methods.rb

@@ -0,0 +1,69 @@
+module VoiceForm
+ 
+  def self.included(base)
+    base.extend ClassMethods
+    base.class_eval do
+      include FormMethods
+    end
+  end
+  
+  module ClassMethods
+    
+    def voice_form(options={}, &block)
+      raise "Voice form requires block" unless block_given?
+
+      self.class_eval do
+        include InstanceMethods
+    
+        cattr_accessor :voice_form_options
+        attr_accessor :form, :call
+      end
+
+      self.voice_form_options = [options, block]
+    end
+
+    def start_voice_form(call)
+      raise "No voice form defined" unless voice_form_options
+      self.new.start_voice_form(call)
+    end
+    
+  end
+
+  module InstanceMethods
+
+    def start_voice_form(call)
+      raise "No voice form defined" unless self.class.voice_form_options
+      options, block = *self.class.voice_form_options
+      @call = call
+      self.form = VoiceForm::Form.new(options, &block)
+      self.form.run(self)
+    end
+
+    def as_digits(string)
+      string.scan(/\d/).map {|v| v.to_i }
+    end
+  end
+
+  module FormMethods
+    
+    # Can be used in a form or stand-alone in a component method
+    def field(field_name, options={}, &block)
+      raise "A field requires a block" unless block_given?
+      
+      form_field = VoiceForm::FormField.new(field_name, options, self, &block)
+      
+      if self.is_a?(VoiceForm::Form)
+        self.form_stack << form_field
+      else
+        unless self.respond_to?(field_name)
+          self.class.class_eval do
+            attr_accessor field_name
+          end
+        end
+        form_field.run
+      end
+    end
+    
+  end
+
+end

data/spec/form_field_spec.rb

@@ -0,0 +1,303 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe VoiceForm::FormField do
+  include VoiceForm::FormMethods
+
+  attr_accessor :call, :my_field
+
+  before do
+    @call = mock('Call', :play => nil, :speak => nil)
+    @call.stub!(:input).with(any_args).and_return('')
+  end
+
+  it "should define accessor for field in component" do
+    field(:my_field) do
+      prompt :play => 'test'
+    end
+    self.methods.include?(:my_field)
+  end
+
+  it "should raise error if no prompts defined" do
+    lambda {
+      form_field(:my_field) {}
+    }.should raise_error
+  end
+
+  it "should raise error if reprompt defined before prompt" do
+    lambda {
+      form_field(:my_field) do
+        reprompt :play => 'again'
+      end
+     }.should raise_error
+  end
+
+  it "should return same prompt for for all attempts if single prompt" do
+    item = form_field(:my_field) do
+      prompt :play => "first"
+    end
+    item.send(:prompt_for_attempt, 1)[:message].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:message].should == 'first'
+  end
+
+  it "should return reprompt for subsequent prompts" do
+    item = form_field(:my_field) do
+      prompt :play => "first"
+      reprompt :play => 'next'
+    end
+    item.send(:prompt_for_attempt, 1)[:message].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:message].should == 'next'
+    item.send(:prompt_for_attempt, 3)[:message].should == 'next'
+  end
+
+  it "should return prompt for given number of repeats before subsequent prompts" do
+    item = form_field(:my_field) do
+      prompt :play => "first", :repeats => 2
+      reprompt :play => 'next'
+    end
+    item.send(:prompt_for_attempt, 1)[:message].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:message].should == 'first'
+    item.send(:prompt_for_attempt, 3)[:message].should == 'next'
+  end
+
+  it "should set input value in component" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first"
+    end
+    call.stub!(:input).and_return('123')
+    item.run
+
+    my_field.should == '123'
+  end
+
+  it "should run setup callback once" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :attempts => 3) do
+      prompt :play => "first"
+      setup { call_me.call }
+    end
+    call.should_receive(:input).and_return('')
+
+    item.run
+  end
+
+  it "should run timeout callback if no input" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :attempts => 1) do
+      prompt :play => "first"
+      timeout { call_me.call }
+    end
+    call.should_receive(:input).and_return('')
+
+    item.run
+  end
+
+  it "should run timeout callback if input not valid length" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :attempts => 1, :length => 3) do
+      prompt :play => "first"
+      timeout { call_me.call }
+    end
+    call.should_receive(:input).and_return('12')
+
+    item.run
+  end
+
+  it "should make all attempts to get valid input" do
+    item = form_field(:my_field) do
+      prompt :play => "first"
+    end
+    call.should_receive(:input).exactly(3).times
+
+    item.run
+  end
+
+  it "should make one attempt if input is valid" do
+    item = form_field(:my_field) do
+      prompt :play => "first"
+    end
+    item.stub!(:input_valid?).and_return(true)
+    call.should_receive(:input).once
+
+    item.run
+  end
+
+  it "should check if input_valid?" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first"
+    end
+    call.should_receive(:input).and_return('123')
+    item.should_receive(:input_valid?)
+
+    item.run
+  end
+
+  it "should run validation callback if defined" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :length => 3, :attempts => 1) do
+      prompt :play => "first"
+      validate { call_me.call }
+    end
+    call.stub!(:input).and_return('123')
+
+    item.run
+  end
+
+  it "should run confirm callback if defined" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :length => 3, :attempts => 1) do
+      prompt :play => "first"
+      confirm { call_me.call; [] }
+    end
+    call.stub!(:input).and_return('123')
+
+    item.run
+  end
+
+  describe "confirm callback" do
+
+    it "should not run if not valid input" do
+      dont_call_me = i_should_not_be_called
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+        validate { false }
+        confirm { dont_call_me.call }
+      end
+      call.stub!(:input).and_return('123')
+
+      item.run
+    end
+
+    it "should be run the number of attempts if no valid response" do
+      call.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+
+        confirm(:attempts => 3) { [] }
+      end
+      call.should_receive(:input).with(1, anything).exactly(3).times.and_return('')
+
+      item.run
+    end
+
+    it "should run success callback if accept value entered" do
+      call_me = i_should_be_called
+      call.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+
+        success { call_me.call }
+        confirm(:accept => '1', :reject => '2') { [] }
+      end
+      call.should_receive(:input).with(1, anything).and_return('1')
+
+      item.run
+    end
+
+    it "should run failure callback if reject value entered" do
+      call_me = i_should_be_called
+      call.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+
+        failure { call_me.call }
+        confirm(:accept => '1', :reject => '2') { [] }
+      end
+      call.should_receive(:input).with(1, anything).and_return('2')
+
+      item.run
+    end
+
+    it "should play confirmation input prompt if confirm block return value is array" do
+      call_me = i_should_be_called
+      call.should_receive(:input).with(3, anything).and_return('123')
+
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+
+        success { call_me.call }
+        confirm(:timeout => 3) { [] }
+      end
+      call.should_receive(:input).with(1, {:play => [], :timeout => 3}).and_return('1')
+
+      item.run
+    end
+
+    it "should speak confirmation input prompt if confirm block return value is string" do
+      call_me = i_should_be_called
+      call.should_receive(:input).with(3, anything).and_return('123')
+
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :play => "first"
+
+        success { call_me.call }
+        confirm(:timeout => 3) { 'speak me' }
+      end
+      call.should_receive(:input).with(1, {:speak => 'speak me', :timeout => 3}).and_return('1')
+
+      item.run
+    end
+  end
+
+  it "should run failure callback if no input" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first"
+      failure { call_me.call }
+    end
+    call.should_receive(:input).and_return('')
+
+    item.run
+  end
+
+  it "should run success callback if input valid length" do
+    call_me = i_should_be_called
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first"
+      success { call_me.call }
+    end
+    call.should_receive(:input).and_return('123')
+
+    item.run
+  end
+
+  it "should run success callback if input valid length and valid input" do
+    validate_me = i_should_be_called
+    call_me = i_should_be_called
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first"
+      validate do
+        validate_me.call
+        my_field.to_i > 100
+      end
+      success { call_me.call }
+    end
+    call.should_receive(:input).and_return('123')
+
+    item.run
+  end
+
+  it "should execute input with message when bargein is true" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first", :bargein => true
+    end
+    call.should_not_receive(:play)
+    call.should_receive(:input).with(3, :play => "first", :timeout => 5)
+
+    item.run
+  end
+
+  it "should execute playback method with message and input without message when bargein is false" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :play => "first", :bargein => false
+    end
+    call.should_receive(:play).with('first')
+    call.should_receive(:input).with(3, :timeout => 5)
+
+    item.run
+  end
+
+  def form_field(field, options={}, &block)
+    self.class.class_eval { attr_accessor field }
+    VoiceForm::FormField.new(field, {:attempts => 3}.merge(options), self, &block)
+  end
+end