=========
Utilities
=========

Boolean settings
================

Configuration settings are often Boolean values that can be spelled in
several different ways.  The `boolean` function will return a Python
Boolean value based on the setting, or raise a `ValueError` if setting
is not a valid Boolean.  **This is not equivalent to Python bool()
function.**  Only explicit on/off, yes/no, true/false, and 1/0 settings
are allowed.

    >>> from zc.wsgisessions.utils import boolean
    >>> for setting in (True, 'true', 'yes', 'on', 1, '1'):
    ...     if not boolean(setting):
    ...         print 'Failed'
    ...         break
    ... else:
    ...     print 'Passed'
    Passed
    >>> for setting in (False, 'false', 'no', 'off', 0, '0'):
    ...     if boolean(setting):
    ...         print 'Failed'
    ...         break
    ... else:
    ...     print 'Passed'
    Passed

The settings are *case insensitive*.

    >>> for setting in ('TRUE', 'True', 'tRuE', 'YES', 'Yes', 'ON', 'On'):
    ...     if not boolean(setting):
    ...         print 'Failed'
    ...         break
    ... else:
    ...     print 'Passed'
    Passed
    >>> for setting in ('FALSE', 'False', 'FaLsE', 'NO', 'No', 'OFF', 'Off'):
    ...     if boolean(setting):
    ...         print 'Failed'
    ...         break
    ... else:
    ...     print 'Passed'
    Passed

Any numbers, other than 1 and 0, are invalid Boolean values.

    >>> for setting in (2, 10, -1, '3'):
    ...     try:
    ...         value = boolean(setting)
    ...         print 'Failed'
    ...         break
    ...     except ValueError:
    ...         pass
    ... else:
    ...     print 'Passed'
    Passed

Other strings are invalid Boolean settings.

    >>> for setting in ('', 'y', 'n', 'good', 'bad'):
    ...     try:
    ...         value = boolean(setting)
    ...         print 'Failed'
    ...         break
    ...     except ValueError:
    ...         pass
    ... else:
    ...     print 'Passed'
    Passed

Other objects are invalid Boolean settings.

    >>> for setting in (
    ...     None, (), (0,), [], [1], {}, {'true': 1},
    ...     set([]), set([1]), frozenset([]), frozenset([1]), object(),
    ...     ):
    ...     try:
    ...         value = boolean(setting)
    ...         print 'Failed'
    ...         break
    ...     except ValueError:
    ...         pass
    ... else:
    ...     print 'Passed'
    Passed

The error prints an informative message based on `__repr__` for the
object.

    >>> boolean('')
    Traceback (most recent call last):
      ...
    ValueError: Invalid Boolean setting: ''

    >>> boolean(object())
    Traceback (most recent call last):
      ...
    ValueError: Invalid Boolean setting: <object ...>
