voice_form 0.3.0

data/History.txt

@@ -0,0 +1,24 @@
+== 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.
+
+== 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,251 @@
+# 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
+
+The plugin adds form features to Adhearsion components to quickly and semantically setup data
+input for your voice application. You define a form and form fields in which to collect data and
+setup callbacks to instruct the caller, give feedback, confirm input and validate input.
+
+
+## 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
+
+Here is the Adhearsion example Simon game redone using voice_form:
+
+    class SimonGame
+      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
+
+That covers most of the functionality, and hopefully it makes sense pretty much straight 
+away.
+
+To start the form, in your dialplan:
+
+For Adhearsion 0.7.999
+
+    general {
+      simon_game = new_simon_game
+      simon_game.start_voice_form(self)
+    }
+
+For Adhearsion 0.8.x
+
+    general {
+      SimonGame.start_voice_form(self)
+    }
+
+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 callback blocks (setup, validate, timeout etc.) are evaluated in the component scope so you can use 
+component methods and instance variables in them and they will work. You don't have to define any 
+callbacks if the field is straight forward and only depends on its length.
+
+For a more complete example see the examples folder.
+
+## Commands
+
+### 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`.
+
+
+### field
+
+This defines the field with the 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       - the method name for the call context if other than 'call'. Used for standalone fields not in 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
+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. 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.
+
+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.
+
+
+### Callbacks 
+
+The available callbacks that can be defined for a field are as follows
+
+- setup
+- timeout
+- validate
+- invalid
+- confirm
+- success
+- failure
+
+Each of them takes a block which is executed as a specific point in the process of getting form input.
+All of them are optional. The block for a callback is evaluated in the scope of the component so any
+instance variables and component methods are available to use including the call context.
+
+The details of each callback are as follows
+
+#### setup
+
+This is run once only for a field if defined before any prompts
+
+#### timeout
+
+This is run if no input is received or input is not of a valid length as defined by length or min_length
+field options.
+
+#### 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
+
+The invalid callback is called if validate block returns false.
+
+#### 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,
+you want to play as the prompt for confirming the value entered. The confirm block also takes a few options:
+
+- :accept   - the number to press to accept the field value entered. Default is 1. 
+- :reject   - the number to press the reject the field value entered and try again. Default is 2.
+- :attempts - the number of attempts to try to get a confirmation response. Default is 3
+- :timeout  - the number of seconds to wait for input after the confirmation response. Default is 3.
+
+The value returned from the block should form the complete list of audio files or TTS text to prompt the user
+including the values to accept of reject the value.
+
+For example, in a field called my_field:
+
+    confirm(:accept => 1, :reject => 2, :attempts => 3) do
+      ['you-entered', as_digits(@my_field), 'is-this-correct', 'press-1-accept-2-try-again'].flatten
+    end
+
+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."
+    end
+
+The above will `speak` the string as the prompt for 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
+
+To exit the form after the current field is complete just execute `form.exit`. The application will then be 
+returned to where the form was started, be it a dialplan or another form.
+
+
+## Credits
+
+Adam Meehan (adam.meehan@gmail.com, [http://duckpunching.com/](http://duckpunching.com/))
+
+Also thanks to Jay Phillips et al. for the 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.3.0"
+AUTHOR = "Adam Meehan"
+EMAIL = "adam.meehan@gmail.com"
+HOMEPAGE = "http://github.com/adzap/voice_form"
+SUMMARY = "A plugin 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,62 @@
+class MyComponent
+  include VoiceForm
+
+  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
+
+      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 "You cannot be that old. Try again."
+      end
+      
+      success do
+        speak "You are #{@age} years old."
+      end
+      
+      failure do
+        speak "You could not enter your age. Thats a bad sign."
+      end
+    end
+    
+    do_block do
+      speak "Get ready for the next question."
+    end
+    
+    field(:postcode, :length => 4, :attempts => 5) do
+      prompt :speak => "Please enter your 4 digit postcode", :timeout => 3
+      
+      validate { @postcode[0..0] != '0' }
+      
+      invalid do
+        if @postcode.size < 4
+          speak "Your postcode must 4 digits."
+        else
+          speak "Your postcode cannot start with a 0."
+        end
+      end
+      
+      success do
+        speak "Your postcode is #{@postcode.scan(/\d/).join(', ')}."
+      end
+      
+      failure do
+        if @age.empty?
+          speak "Lets start over shall we."
+          form.restart
+        end
+      end
+    end
+    
+  end
+end

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