questionnaire.rb

This file contains the MUES::Questionnaire class, a derivative of MUES::IOEventFilter. Instances of this class are dynamically-configurable question and answer session objects which are inserted into a MUES::User‘s MUES::IOEventStream to gather useful information about a subject or task. It does this by iterative over one or more steps, prompting the user with a question specified by each one, and gathering and validating input sent in reply.

When an Questionnaire is created, it is given a procedure for gathering the needed information in the form of an Array of one or more "steps", and an optional block to be called when all of the necessary questions are answered.

A "step" can be any object which responds to the element reference (#[]) and the key? methods. Both methods will be called with Symbol arguments like :name and :question, and are expected to behave like a Hash when responding to them. This makes a Hash a particularly good choice for specifying steps. Each step should describe (via responses to said methods) the question to be answered and what constitutes acceptable input for each step. It may also specify other optional keys to further control the way the step is presented or processed. The steps are executed one at a time in the order they are in the steps array at the moment input arrives.

The mandatory keys for a step are:

:name

Specifies an identifier for the question. Validated answers will then be stored in the answers hash with the symbolified (via name.intern) version of this name.

The optional keys for a step are:

:question

A String or MUES::OutputEvent object containing the prompt to be sent to the user upon entering or re-entering this step. If no question is specified, a capitalized version of the :name value is used.

:validator

An object which provides validation for input data. It can be one of several different kinds of objects:

a Proc or Method object

The Proc or Method will be called with two arguments: the Questionnaire object doing the validation, and the answer as a String. If the validator returns nil or false, the input data is discarded and the question is re-asked. If the validator returns true, the input data is used directly for the answer. Returning anything else causes whatever is returned to be used as the answer.

a Regexp object

The validator pattern will be matched against the incoming data, and if no match is found, returns nil. If a match is found, and the Regexp contains paren groups (eg., /(\w+) (\w+)/), the matches from the parent group are used. If the match contains no paren groups, the whole of the match will be used.

an Array

The Array contains a list of valid data; validation succeeds when the answer matches one of the values. The unchanged data is returned.

a Hash

Validation succeeds when the input data or the Symbol-ified input data matches one of the keys of the Hash. The corresponding value for that key is used as the answer.

If no validator is specified, any input except empty input is accepted as-is. On empty input, the default will be used if specified (see below), or it will cause the Questionnaire to abort if no default exists.

:default

The default value of the question, should no answer be given. If there is no :default key in the step, entering a blank line aborts the whole Questionnaire.

:errorMsg

The text of the error message to use for simple validators. If an :errorMsg is not supplied, an appropriate message for the type of validator being used will be generated if validation fails.

:hidden

If this key exists in the step and is set to true, the prompt sent will be a HiddenInputPromptEvent, which should cause the input for the response to be obscured. Defaults to false.

If a block is given at construction, or set later in the object‘s lifecycle via the finalizer= method, it will be called once all the steps are completed, passing the Questionnaire object as an argument.

Synopsis

  require 'mues/filters/questionnaire'

  steps = [
      {
          :name       => 'height',
          :question   => "Height: ",
          :validator  => /\d+/,
          :errorMsg   => "Height must be a number.",
      },

      {
          :name       => 'color',
          :question   => "What color [red,green,blue]?",
          :validator  => %w{red green blue},
      }
  ]

  questionnaire = MUES::Questionnaire::new( 'Configure your new Thingie', steps ) {|questionnaire|
      thingie = Thingie::new

      thingie.height = questionnaire.answers[:height]
      thingie.color  = questionnaire.answers[:color]
      thingie.save
  }

Subversion ID

$Id: questionnaire.rb 1218 2004-06-14 06:07:54Z deveiant $

Authors

• Michael Granger <ged@FaerieMUD.org>

Copyright

Copyright (c) 2000-2003 The FaerieMUD Consortium. All rights reserved.

This module is free software. You may use, modify, and/or redistribute this software under the terms of the Perl Artistic License. (See language.perl.com/misc/Artistic.html)

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Required files