===========
About qanda
===========

Background
----------

Interactive command-line programs need to query users for information, be it
text, choices from a list, or simple yes-or-no answers. *qanda* [qanda-home]_
[qanda-pypi]_ module of simple functions to prompt users for such information,
allowing validation and cleanup of answers, default responses, consistent
formatting and presentation of help text, hints and choices. It is not a
replacement for textual interfaces like curses and urwid, but intended solely
for simple console scripts with user input is required.

**Status:** *qanda* is in use by one other non-trivial library, and so is
functional. However this is still an early release and the API may change.
Comment is invited.


Installation
------------

The simplest way to install *qanda* is via ``easy_install`` [setuptools]_ or an
equivalent program::

	% easy_install qanda

Alternatively the tarball can be downloaded, unpacked and ``setup.py`` run::

	% tar zxvf qanda.tgz
	% cd qanda
	% python set.py install

*qanda* has one prequisite - the konval library [konval]_ for validators - 
although it may also use the colorama library [colorama]_ for prettifying text.
It should work with just about any version of Python.


Using qanda
-----------

A full API is included in the source distribution.


An example
~~~~~~~~~~

::

	>>> from qanda import prompt
	>>> prompt.string ("What is your name")
	What is your name: Foo
	>>> fname = prompt.string ("Your friends name is",
			help="I need to know your friends name as well before I talk to you.",
			hints="first name",
			default='Bar',
		)

	I need to know your friends name as well before I talk to you.
	Your friends name is (first name) [Bar]:
	>>> print fname
	Bar
	>>> years = prompt.integer ("And what is your age", min=1, max=100)
	And what is your age: 101
	A problem: 101 is higher than 100. Try again ...
	And what is your age: 28



Central concepts
~~~~~~~~~~~~~~~~

*qanda* packages all question-asking methods in a Session class. This allows
the appearance and functioning of all these methods to be handled consistently
and modified centrally. However, you don't necessarily have to create a Session
to use it - there's pre-existing Session in the variable called ``prompt``::

	>>> from qanda import Session
	>>> s = Session()
	>>> from qanda import prompt
	>>> type (prompt)
	<class 'qanda.session.Session'>

The question methods are named after the type of data they elicit::

	>>> print type(prompt.integer ("Pick a number"))
	Pick a number: 2
	<type 'int'>
	>>> print type(prompt.string ("Pick a name"))
	Pick a name: Bob
	<type 'string'>

Many of the question methods with accept a list of "converters", each of which
is used to successively transform or validate user input. This follows the idiom
of Ian Bicking's FormEncode: raw values are passed into  a converter and the
results are passed into the next. If input fails validation, the question is
posed again::

	>>> prompt.string ("Choose a password", converters=[ToStripped(),
	...   CheckLength(min=8)])

These validators are also used internally. For this, *qanda* use the konval
library [konval-pypi]_:

ToInt, ToFloat
	Convert inputs to other types
MatchRegex
	Only allow values that match a certain pattern
IsInRange
	Check that input falls within given bounds
CheckLength
	Check that input length falls within given bounds
ToSynonym
	Map values to other values
IsInVocab
	Ensure values fall within a fixed set

*Note: the earliest version of the qanda library had it's own validation
library, but this was spun off into the konval package.*


References
----------

.. [qanda-home] `qanda home page <http://www.agapow.net/software/py-qanda>`__

.. [qanda-pypi] `qanda on PyPi <http://pypi.python.org/pypi/qanda>`__

.. [setuptools] `Setuptools & easy_install <http://packages.python.org/distribute/easy_install.html>`__

.. [qanda-github] `qanda on github <https://github.com/agapow/py-qanda>`__

.. [colorama-pypi] `colorama on PyPi <http://pypi.python.org/pypi/colorama>`__

.. [konval-pypi] `konval on PyPi <http://pypi.python.org/pypi/konval>`__