adzap-voice_form 0.1.1

data/History.txt

@@ -0,0 +1,14 @@
+== 0.1.1 2008-11-12
+* refactored to auto include voice_form method in components, no more 'include VoiceForm'
+
+== 0.1.0 2008-11-11
+* Gemified using newgem
+
+== 2008-11-11
+* Added form field confirm callback to enable confirmation of input
+
+== 2008-11-04
+* Changed form.exit_form to form.exit
+
+== 2008-11-03
+* First commit

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Adam Meehan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,150 @@
+#VoiceForm
+
+A plugin for Adhearsion to add form functionality and flow, similar to VoiceXML style forms.
+
+By Adam Meehan (adam.meehan@gmail.com, [http://duckpunching.com/](http://duckpunching.com/))
+
+Released under the MIT license.
+
+##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
+are simply prompt, input, validate and, reprompt or go the next field. This flow has been nicely 
+distilled into the VXML form element and its child elements. The problem with VXML is that you are 
+using XML in a programmatic way, yuck! Also you are not using Ruby, so you miss out on its awesomeness.
+
+The plugin attempts to emulate some of the VXML form flow for use in your Adhearsion components.
+
+
+##Install
+
+    sudo gem install adzap-voice_form --source=http://gems.github.com/
+    
+At the bottom your projects startup.rb file put
+
+    require 'voice_form'
+
+##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**
+command to play your sound files.
+
+    class MyComponent
+      include VoiceForm
+      add_call_context :as => :call_context
+
+      voice_form do      
+      
+        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
+          end
+          
+          timeout do
+            call_context.speak "You did not enter anything. Try again."
+          end
+                  
+          validate do
+            @age.to_i <= @max_age
+          end
+          
+          invalid do
+            call_context.speak "Your age must be less than #{@max_age}. Try again."
+          end
+          
+          success do
+            call_context.speak "You are #{@age} years old."
+          end
+          
+          failure do
+            call_context.speak "You could not enter your age. Thats a bad sign."
+          end      
+        end
+       
+      end
+    end
+
+In your dialplan:
+
+    general {
+      my_component = new_my_component
+      my_component.start_voice_form
+    }
+
+That covers most of the functionality, and hopefully it makes sense pretty much straight 
+away.
+
+You don't have to start the form from the dialplan, but it makes it simple. You could start it from 
+within a component method.
+
+All blocks (setup, validate, do_block etc.) are evaluated in the component scope so you can use 
+component methods and instance variables in them and they will work.
+
+For a more complete example see the examples folder.
+
+### voice_form
+
+The flow of the form works like a stack. So each field and do_block are executed in order until the 
+end of the form is reached. You can jump around the stack by using `form.goto :field_name` which
+will move the *stack pointer* to the field after the current field is completed and move forward
+through the form stack from that point, regardless whether a field has already been completed.
+
+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
+
+This defines the field the with name given to collect on the form. The field method can be used
+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'
+
+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
+the field callbacks and in other fields on a form.
+
+The `prompt` and `reprompt` methods are a wrapper around the input command. And as such is always 
+interruptable or you can _bargein_ when you want to starting keying numbers. You pass in a 
+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
+- :repeats - number of attempts to use this prompt until the next one is used
+
+The length expected for the input is taken from the options passed to the `field` method.
+
+You can only use one of :play or :speak.
+
+There can only be one `prompt` but you can have multiple `reprompt`s. When you add a reprompt it changes
+what the prompt is if there is input the first time or the input is invalid.
+
+
+TODO: Add specific info for callback and option.
+
+
+TODO: More docs
+
+
+##Credits
+
+Adam Meehan (adam.meehan@gmail.com, [http://duckpunching.com/](http://duckpunching.com/))
+
+Also thanks to Jay Phillips for his brilliant work on Adhearsion ([http://adhearsion.com](http://adhearsion.com)).

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'date'
+require 'spec/rake/spectask'
+
+GEM = "voice_form"
+GEM_VERSION = "0.1.0"
+AUTHOR = "Adam Meehan"
+EMAIL = "adam.meehan@gmail.com"
+HOMEPAGE = "http://github.com/adzap/voice_form"
+SUMMARY = "A DSL for Adhearsion to create forms in the style of the VoiceXML form element."
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = false
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.extra_rdoc_files = ["History.txt"]
+  # Uncomment this to add a dependency
+  # s.add_dependency "foo"
+  
+  s.require_path = 'lib'
+  s.autorequire = GEM
+  s.files = %w(MIT-LICENSE README.markdown Rakefile) + Dir.glob("{lib,spec,examples}/**/*")
+end
+
+task :default => :spec
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = %w(-fs --color)
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the gem locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end

data/examples/my_component.rb

@@ -0,0 +1,57 @@
+class MyComponent
+  include VoiceForm
+  add_call_context :as => :call_context
+
+  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 }
+      
+      invalid do
+        call_context.speak "Your age must be less than #{@max_age}. Try again."
+      end
+      
+      success do
+        call_context.speak "You are #{@age} years old."
+      end
+      
+      failure do
+        call_context.speak "You could not enter your age. Thats a bad sign."
+      end
+    end
+    
+    do_block do
+      call_context.speak "Get ready for the next question."
+    end
+    
+    field(:postcode, :length => 4, :attempts => 5) do
+      prompt :speak => "Please enter your 4 digit post code", :timeout => 3
+      
+      validate { @postcode[0..0] != '0' }
+      
+      invalid do
+        if @postcode.size < 4
+          call_context.speak "Your postcode must 4 digits."
+        else
+          call_context.speak "Your postcode cannot start with a 0."
+        end
+      end
+      
+      success do
+        call_context.speak "Your postcode is #{@postcode.scan(/\d/).join(', ')}."
+      end
+      
+      failure do
+        if @age.empty?
+          call_context.speak "Lets start over shall we."
+          form.restart
+        end
+      end
+    end
+    
+  end
+end

data/lib/voice_form.rb

@@ -0,0 +1,11 @@
+require 'voice_form/form_methods'
+require 'voice_form/form'
+require 'voice_form/form_field'
+
+Adhearsion::Components::Behavior.module_eval do
+  include VoiceForm::FormMethods
+end
+
+Adhearsion::Components::Behavior::ClassMethods.module_eval do
+  include VoiceForm::MacroMethods
+end

data/lib/voice_form/form.rb

@@ -0,0 +1,106 @@
+module VoiceForm
+
+  class Form
+    include VoiceForm::FormMethods
+
+    attr_accessor :form_stack
+    attr_reader :current_field
+    
+    def initialize(options={})
+      @options = options
+      
+      @form_stack = []
+      @stack_index = 0
+    end
+    
+    def run(component)
+      @component = component
+      
+      alias_call_context
+      
+      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 = nil
+      form_stack.each_with_index {|slot, i| 
+        index = i and break if form_field?(slot) && slot.name == 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_form = true
+    end
+    
+    private 
+    
+    def run_setup
+      @component.instance_eval(&@setup) if @setup
+    end
+    
+    def run_form_stack
+      while @stack_index < form_stack.size 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
+        
+        break if @exit_form
+      end
+      @stack_index = 0
+      @current_field = nil
+    end
+    
+    def add_field_accessors
+      return if @accessors_added
+      
+      form_stack.each do |field|
+        next unless form_field?(field)
+        @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 alias_call_context
+      # hack to avoid setting the call_context in each field for different context name
+      if context_name = @options[:call_context] && !@component.respond_to?(:call_context)
+        @component.class_eval do
+          alias_method :call_context, context_name
+        end
+      end
+    end
+    
+  end
+  
+end

data/lib/voice_form/form_field.rb

@@ -0,0 +1,184 @@
+module VoiceForm
+
+  class FormField
+    attr_reader :name
+    attr_accessor :prompts
+
+    def initialize(name, options, component)
+      @name, @options, @component = name, options, component
+      @options.reverse_merge!(:attempts => 5, :call_context => 'call_context')
+      @callbacks = {}
+      @prompts = []
+    end
+
+    def prompt(options)
+      add_prompts(options.reverse_merge(:timeout => 5))
+    end
+
+    def reprompt(options)
+      raise 'A reprompt can only be used after a prompt' if @prompts.empty?
+      add_prompts(options.reverse_merge(:timeout => 5))
+    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!(
+        :attempts => 3,
+        :accept   => 1,
+        :reject   => 2,
+        :timeout  => 3
+      )
+      @confirmation_options = options.merge(:block => 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?
+          run_callback(:timeout)
+          next
+        end
+
+        set_component_value @value
+
+        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
+    end
+
+    private
+
+    def prompt_for_attempt(attempt)
+      prompt = if attempt == 1 || @prompts.size == 1 then
+        @prompts.first
+      else
+        @prompts[attempt-1] || @prompts.last
+      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)
+    end
+
+    def input_valid?
+      @value.size >= minimum_length &&
+        @value.size <= maximum_length &&
+        run_callback(:validate)
+    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
+          return true
+        when options[:reject].to_s
+          return false
+        else
+          next
+        end
+      end
+      false
+    end
+
+    def run_callback(callback)
+      if block = @callbacks[callback]
+        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_context
+      @call_context ||= @component.send(@options[:call_context])
+    end
+
+    def add_prompts(options)
+      repeats = options[:repeats] || 1
+      @prompts += ([options] * repeats)
+    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)
+    end
+  end
+
+end

data/lib/voice_form/form_methods.rb

@@ -0,0 +1,63 @@
+module VoiceForm
+ 
+  def self.included(base)
+    base.extend MacroMethods
+    base.class_eval do
+      include FormMethods
+    end
+  end
+  
+  module MacroMethods
+    
+    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
+      end
+
+      self.voice_form_options = [options, block]
+    end
+    
+  end
+
+  module InstanceMethods
+  
+    def start_voice_form
+      raise "No voice form defined" unless self.voice_form_options
+      self.form = VoiceForm::Form.new(self.class.voice_form_options[0])
+      self.form.instance_eval(&self.class.voice_form_options[1])
+      self.form.run(self)
+    end
+
+  end
+
+  module FormMethods
+    
+    # Can be used in a form or stand-alone in a component method
+    def field(field_name, options={}, &block)
+      raise 'Field require a block' unless block_given?
+      
+      form_field = VoiceForm::FormField.new(field_name, options, self)
+      
+      form_field.instance_eval(&block)
+      raise 'At least one prompt is required' if form_field.prompts.empty?
+      
+      if self.class == 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,275 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe VoiceForm::FormField do
+  include VoiceForm::FormMethods
+
+  attr_accessor :call_context, :my_field
+
+  before do
+    @call_context = mock('CallContext', :play => nil, :speak => nil)
+    @call_context.stub!(:input).with(any_args).and_return('')
+  end
+
+  it "should define accessor for field in component" do
+    field(:my_field) do
+      prompt :speak => 'test'
+    end
+    self.methods.include?(:my_field)
+  end
+
+  it "should raise error if no prompts defined" do
+    item = form_field(:my_field) do
+    end
+    lambda { item.run }.should raise_error
+  end
+
+  it "should raise error if reprompt defined before prompt" do
+    lambda {
+      form_field(:my_field) do
+        reprompt :speak => 'and 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 :speak => "first"
+    end
+    item.send(:prompt_for_attempt, 1)[:speak].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:speak].should == 'first'
+  end
+
+  it "should return reprompt for subsequent prompts" do
+    item = form_field(:my_field) do
+      prompt :speak => "first"
+      reprompt :speak => 'next'
+    end
+    item.send(:prompt_for_attempt, 1)[:speak].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:speak].should == 'next'
+    item.send(:prompt_for_attempt, 3)[:speak].should == 'next'
+  end
+
+  it "should return prompt for given number of repeats before subsequent prompts" do
+    item = form_field(:my_field) do
+      prompt :speak => "first", :repeats => 2
+      reprompt :speak => 'next'
+    end
+    item.send(:prompt_for_attempt, 1)[:speak].should == 'first'
+    item.send(:prompt_for_attempt, 2)[:speak].should == 'first'
+    item.send(:prompt_for_attempt, 3)[:speak].should == 'next'
+  end
+
+  it "should set input value in component" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :speak => "first"
+    end
+    call_context.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 :speak => "first"
+      setup { call_me.call }
+    end
+    call_context.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 :speak => "first"
+      timeout { call_me.call }
+    end
+    call_context.should_receive(:input).and_return('')
+
+    item.run
+  end
+
+  it "should make all attempts to get valid input" do
+    item = form_field(:my_field) do
+      prompt :speak => "first"
+    end
+    call_context.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 :speak => "first"
+    end
+    item.stub!(:input_valid?).and_return(true)
+    call_context.should_receive(:input).once
+
+    item.run
+  end
+
+  it "should check if input_valid?" do
+    item = form_field(:my_field, :length => 3) do
+      prompt :speak => "first"
+    end
+    call_context.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 :speak => "first"
+      validate { call_me.call }
+    end
+    call_context.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 :speak => "first"
+      confirm { call_me.call; [] }
+    end
+    call_context.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 :speak => "first"
+        validate { false }
+        confirm { dont_call_me.call }
+      end
+      call_context.stub!(:input).and_return('123')
+
+      item.run
+    end
+
+    it "should be run the number of attempts if no valid response" do
+      call_context.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :speak => "first"
+
+        confirm(:attempts => 3) { [] }
+      end
+      call_context.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_context.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :speak => "first"
+
+        success { call_me.call }
+        confirm(:accept => '1', :reject => '2') { [] }
+      end
+      call_context.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_context.should_receive(:input).with(3, anything).and_return('123')
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :speak => "first"
+
+        failure { call_me.call }
+        confirm(:accept => '1', :reject => '2') { [] }
+      end
+      call_context.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_context.should_receive(:input).with(3, anything).and_return('123')
+
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :speak => "first"
+
+        success { call_me.call }
+        confirm(:timeout => 3) { [] }
+      end
+      call_context.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_context.should_receive(:input).with(3, anything).and_return('123')
+
+      item = form_field(:my_field, :length => 3, :attempts => 1) do
+        prompt :speak => "first"
+
+        success { call_me.call }
+        confirm(:timeout => 3) { '' }
+      end
+      call_context.should_receive(:input).with(1, {:speak => '', :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 :speak => "first"
+      failure { call_me.call }
+    end
+    call_context.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 :speak => "first"
+      success { call_me.call }
+    end
+    call_context.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 :speak => "first"
+      validate do
+        validate_me.call
+        my_field.to_i > 100
+      end
+      success { call_me.call }
+    end
+    call_context.should_receive(:input).and_return('123')
+
+    item.run
+  end
+
+  def form_field(field, options={}, &block)
+    self.class.class_eval { attr_accessor field }
+    item = VoiceForm::FormField.new(field, {:attempts => 3}.merge(options), self )
+
+    item.instance_eval(&block)
+    item
+  end
+end

data/spec/form_spec.rb

@@ -0,0 +1,213 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe VoiceForm::Form do
+  include VoiceForm
+
+  attr_accessor :call_context
+  
+  before do
+    new_voice_form
+    @call_context = mock('CallContext', :play => nil, :speak => nil)
+    @call_context.stub!(:input).with(any_args).and_return('')
+  end
+
+  it "should define form and run it" do
+    call_me = i_should_be_called
+   
+    self.class.voice_form &call_me
+   
+    start_voice_form
+  end
+
+  it "should call setup block" do
+    form.setup &i_should_be_called
+    
+    run_form
+  end
+  
+  it "should run single form field" do
+    call_me = i_should_be_called
+    
+    form.field(:my_field) do
+      prompt :speak => 'enter value'
+      setup { call_me.call }
+    end
+    
+    run_form
+  end
+  
+  it "should run all form fields" do
+    first_call_me = i_should_be_called
+    second_call_me = i_should_be_called
+    
+    form.field(:first_field) do
+      prompt :speak => 'enter value'
+      setup { first_call_me.call }
+    end
+    form.field(:second_field) do
+      prompt :speak => 'enter value'
+      setup { second_call_me.call }
+    end
+    
+    run_form
+  end
+  
+  it "should run do_blocks" do
+    do_block_call_me = i_should_be_called
+
+    form.do_block { do_block_call_me.call }
+    
+    run_form
+  end
+  
+  it "should run all fields and do_blocks" do
+    field_call_me = i_should_be_called
+    do_block_call_me = i_should_be_called
+    
+    form.field(:first_field) do
+      prompt :speak => 'enter value'
+      setup { field_call_me.call }
+    end
+    form.do_block { do_block_call_me.call }
+    
+    run_form
+  end
+  
+  it "should jump forward in form stack to field in goto" do
+    first_call_me    = i_should_be_called
+    do_block_call_me = i_should_not_be_called
+    second_call_me   = i_should_be_called
+    
+    form.field(:first_field, :attempts => 1) do
+      prompt :speak => 'enter value'
+      setup { first_call_me.call }
+      failure { form.goto :second_field }
+    end
+    
+    form.do_block { do_block_call_me.call }
+
+    form.field(:second_field) do
+      prompt :speak => 'enter value'
+      setup { second_call_me.call }
+    end
+    
+    run_form
+  end
+  
+  it "should jump back in form stack to goto field and repeat form stack items" do
+    first_call_me    = i_should_be_called(2)
+    do_block_call_me = i_should_be_called(2)
+    second_call_me   = i_should_be_called(2)
+    
+    form.field(:first_field, :attempts => 1) do
+      prompt :speak => 'enter value'
+      setup { first_call_me.call }
+    end
+    
+    form.do_block { do_block_call_me.call }
+
+    form.field(:second_field) do
+      prompt :speak => 'enter value'
+      setup { second_call_me.call }
+      failure { 
+        unless @once
+          @once = true
+          form.goto :first_field 
+        end
+      }
+    end
+    
+    run_form
+  end
+
+  it "should restart form and repeat all form stack items" do
+    first_call_me    = i_should_be_called(2)
+    do_block_call_me = i_should_be_called(2)
+    second_call_me   = i_should_be_called(2)
+    
+    form.field(:first_field, :attempts => 1) do
+      prompt :speak => 'enter value'
+      setup { first_call_me.call }
+    end
+    
+    form.do_block { do_block_call_me.call }
+
+    form.field(:second_field) do
+      prompt :speak => 'enter value'
+      setup { second_call_me.call }
+      failure { 
+        unless @once
+          @once = true
+          form.restart
+        end
+      }
+    end
+    
+    run_form
+  end
+  
+  it "should exit form and not run subsequent fields" do
+    first_call_me    = i_should_be_called
+    do_block_call_me = i_should_not_be_called
+    second_call_me   = i_should_not_be_called
+    
+    form.field(:first_field, :attempts => 1) do
+      prompt :speak => 'enter value'
+      setup   { first_call_me.call }
+      failure { form.exit }
+    end
+    
+    form.do_block { do_block_call_me.call }
+
+    form.field(:second_field) do
+      prompt :speak => 'enter value'
+      setup { second_call_me.call }
+    end
+    
+    run_form
+  end
+  
+  describe "current_field" do
+    before do
+      @field = nil
+    end
+    
+    it "should be name of current field being run" do
+      form.field(:my_field) do
+        prompt :speak => 'enter value'
+        setup { @field = form.current_field }
+      end
+      run_form
+      
+      @field.should == :my_field
+    end
+    
+    it "should be nil in do_block" do
+      form.do_block do
+        @field = form.current_field
+      end
+      run_form
+      
+      @field.should be_nil
+    end
+    
+    it "should be nil after form is run" do
+      form.field(:my_field) do
+        prompt :speak => 'enter value'
+      end
+      run_form
+      
+      form.current_field.should be_nil
+    end
+  end
+
+  def new_voice_form
+    self.class.voice_form { }
+    self.form = VoiceForm::Form.new(self.class.voice_form_options[0])
+    self.form.instance_eval(&self.class.voice_form_options[1])
+  end
+  
+  def run_form
+    form.run(self)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+$: << File.dirname(__FILE__) + '/../lib'
+$: << File.dirname(__FILE__)
+
+require 'rubygems'
+require 'spec'
+require 'active_support'
+
+require 'voice_form/form_methods'
+require 'voice_form/form'
+require 'voice_form/form_field'
+
+module SpecHelpers
+  def i_should_be_called(times=1, &block)
+    proc = mock('Proc should be called')
+    proc.should_receive(:call).exactly(times).times.instance_eval(&(block || Proc.new {}))
+    Proc.new { |*args| proc.call(*args) }
+  end
+  
+  def i_should_not_be_called(&block)
+    proc = mock('Proc should be called')
+    proc.should_not_receive(:call).instance_eval(&(block || Proc.new {}))
+    Proc.new { |*args| proc.call(*args) }
+  end
+end
+
+Spec::Runner.configure do |config|
+  config.include SpecHelpers
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: adzap-voice_form
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Adam Meehan
+autorequire: voice_form
+bindir: bin
+cert_chain: []
+
+date: 2008-11-11 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: A DSL for Adhearsion to create forms in the style of the VoiceXML form element.
+email: adam.meehan@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+files: 
+- MIT-LICENSE
+- README.markdown
+- Rakefile
+- lib/voice_form.rb
+- lib/voice_form
+- lib/voice_form/form.rb
+- lib/voice_form/form_field.rb
+- lib/voice_form/form_methods.rb
+- spec/form_field_spec.rb
+- spec/spec_helper.rb
+- spec/form_spec.rb
+- examples/my_component.rb
+- History.txt
+has_rdoc: false
+homepage: http://github.com/adzap/voice_form
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A DSL for Adhearsion to create forms in the style of the VoiceXML form element.
+test_files: []
+