.. $Id: question_bases.txt 4670da845e46 2010-03-05 mtnyogi $
.. 
.. Copyright © 2008 Bruce Frederiksen
.. 
.. 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.

restindex
    crumb: Question Bases
    page-description:
        Explanation of question bases and .kqb files.
    /description
    format: rest
    encoding: utf8
    output-encoding: utf8
    include: yes
    initialheaderlevel: 2
/restindex

uservalues
    filedate: $Id: question_bases.txt 4670da845e46 2010-03-05 mtnyogi $
/uservalues

=============================================
Question Bases
=============================================

Question bases contain questions for end users.  These questions can be of
various types (e.g., yes/no, multiple_choice).  The questions may be
parametrized, with the parameter values substituted into the question text
when the question is asked.  In this case, different parameter values are
treated as different question statements_.

The answers to all questions are automatically remembered so that if multiple
rules ask the same question, the end user only sees it once.  These answers
are erased when an `engine.reset`_ is done.

Finally, questions may have *reviews* attached to them to automatically
display different canned messages (with parameter substitution) depending on
the end user's answer.


KQB files
==========

Each question base is defined by a `.kqb file`_.  The name of each question
base is the filename of the .kqb file (with the ``.kqb`` suffix removed).
This must be a legal Python identifier.

These .kqb files are compiled and loaded automatically when you create your 
`knowledge_engine.engine`_ object.

The .kqb file contains all of the information about the question needed to
ask the question, validate the answer, and output the appropriate *review*
text.

The .kqb file also specifies which parameter contains the answer.  All
parameters, except this one, must be bound to values before testing the
question.


Example
=======

In writing a program to diagnose car problems, you might have a
``user_question`` question base with questions like::

    engine_starts($ans)
        Can you start the engine?
        ---
        $ans = yn

    mileage($ans)
        How many miles are on the car?
        ---
        $ans = integer(1-999999)
        200000- ! Wow, that's a lot of miles!

    noise_from($location, $ans)
        Do you hear a noise from $location?
        ---
        $ans = yn

These would look like the following statements_ within rules_::

    user_question.engine_starts(True)
    user_question.mileage($mileage)
    user_question.noise_from('under the hood', False)

Presenting Questions to Your End Users
======================================

Pyke provides two modules to actually present a question to your end user:

- ask_tty
    
  This presents the question on stdout and reads stdin for the answer.

- ask_wx

  This presents the question in a dialog box for use with wxpython_.

You may write your own module to present questions to end users.  Look at the
modules provided by Pyke for guidance.

To ask a question, Pyke looks for an ``ask_module`` attribute on:

#. the question_base object, then
#. the `knowledge_engine.engine`_ object

If the `knowledge_engine.engine`_ object does not have an ``ask_module``
attribute, ask_tty is imported (by default) and stored there.

.. This code is hidden.  It will add '' to sys.path, change to the doc.examples
   directory and store the directory path in __file__ for the code section
   following:
   >>> import sys
   >>> if '' not in sys.path: sys.path.insert(0, '')
   >>> import os
   >>> os.chdir("../../examples")
   >>> __file__ = os.getcwd()

Here's an example of setting this attribute::

    >>> from pyke import knowledge_engine
    >>> from pyke import ask_wx

    >>> engine = knowledge_engine.engine(__file__)
    >>> engine.ask_module = ask_wx


