What is it ?
============

This is pyswitch, a simple yet powerful 'switch'-like dispatcher for
Python.  It's inspired by the C language switch statement, but with more
flexibility; case values are not limited to integers like in C, but can
be any value usable with the '==' equality operator, or any string usable
on the left-hand side of the 'in' operator, or any regular expression.
Iterables of these types can also be use as case values.

New in Release 1.2:
-------------------
It's no longer necessary to call the  switch method of the Switch class to
dispatch a value, as the __call__ method is now a synonym.  So instead, you
can use::
    
    mySwitch = Switch()
    
    ... register your cases ...
    
    returnValue = mySwitch(value_to_switch_on)

But the switch method is still there for backwards compatibility.

Example
=======

Here's a small example of its use::
        
    >>> from pyswitch import Switch, SwitchError
    
    # Instantiate a Switch object.
    >>> mySwitch = Switch()
    
    # Register some cases and case handlers, using the handy-dandy
    # decorators provided by the Switch object.
    
    # A default handler.  A default handler is optional.  If defined,
    # it will be called for all switch values not handled by any other
    # handler.  If not defined, a SwitchError will be raised for an unhandled
    # switch value.
   
    # All handlers are passed the value being switched on, along with any
    # other optional positional and keyword parameters given to the switch.
    # Handlers can return a value, which is then returned by the call to
    # switch which caused the handler to be called.
    
    # Naturally, handlers can do anything you want.  In this default case
    # example, we return a string of interesting info.
    >>> @mySwitch.default
    ... def gotDefault(value, *args, **kwargs):
    ...    return "Default handler: I got unregistered value %r, "\
    ...          "with args: %r and kwargs: %r" % \
    ...          (value, args, kwargs)
        
    # A single numeric case value.  The 'case' decorator is for exact matching
    # to the switch value.  The value given to the case function, called
    # the case value, can be any type usable with the '==' equality operator.
    >>> @mySwitch.case(0)
    ... def gotZero(value, *args, **kwargs):
    ...    return "gotZero: I got a %d, with args: %r and kwargs: %r" % \
    ...          (value, args, kwargs)

    # A range of numeric case values. An iterable of values can be given
    # as the case value.
    >>> @mySwitch.case(range(5, 10))
    ... def gotFiveThruNine(value, *args, **kwargs):    
    ...    return "gotFiveThruNine: I got a %d, with args: %r and kwargs: %r" % \
    ...          (value, args, kwargs)
        
    # A string case value, for an exact match.
    >>> @mySwitch.case('Guido')
    ... def gotGuido(value, *args, **kwargs):
    ...    return "gotGuido: I got '%s', with args: %r and kwargs: %r" % \
    ...          (value, args, kwargs)
        
    # A string value for use with the 'in' operator.
    >>> @mySwitch.caseIn('lo')
    ... def gotLo(value, *args, **kwargs):
    ...    return "gotLo: I got '%s', with args: %r and kwargs: %r" % \
    ...          (value, args, kwargs)
        
    # A regular expression pattern match in a string.
    # You can also pass in a pre-compiled regular expression.
    # For caseRegEx, the value passed to the case handler is actually
    # the Match Object resulting from the successful regular expression
    # pattern match.
    >>> @mySwitch.caseRegEx(r'\b([Pp]y\w*)\b')
    ... def gotPyword(matchObj, *args, **kwargs):
    ...     return "gotPyword: I got a matchObject where group(1) is '%s', "\
    ...           "with args: %r and kwargs: %r" % \
    ...           (matchObj.group(1), args, kwargs)
        
    # And lastly, you can pass a iterable of mixed-type values to case,
    # caseIn, and caseRegEx.  Here, we pass in a list of heterogenous
    # values to be use for exact matches.
    >>> @mySwitch.case([ 99, 'yo', 200 ])
    ... def gotStuffInSeq(value, *args, **kwargs):
    ...     return "gotStuffInSeq: I got %r, with args: %r and kwargs: %r" % \
    ...           (value, args, kwargs)
    
    
    # Now show what we can do.
    
    >>> mySwitch(0, testing=False)
    "gotZero: I got a 0, with args: () and kwargs: {'testing': False}"
    
    >>> mySwitch(6, flag='boring')    
    "gotFiveThruNine: I got a 6, with args: () and kwargs: {'flag': 'boring'}"
    
    >>> mySwitch(10, 42)
    'Default handler: I got unregistered value 10, with args: (42,) and kwargs: {}'
    
    >>> mySwitch('Guido', BDFL=True)
    "gotGuido: I got 'Guido', with args: () and kwargs: {'BDFL': True}"
    
    >>> mySwitch('Anyone seen Guido around?')
    "Default handler: I got unregistered value 'Anyone seen Guido around?', with args: () and kwargs: {}"
    
    >>> mySwitch('Yep, and he said "hello".', 99, yes='no')
    "gotLo: I got 'lo', with args: (99,) and kwargs: {'yes': 'no'}"
    
    >>> mySwitch('Bird is the Python word of the day.')    
    "gotPyword: I got a matchObject where group(1) is 'Python', with args: () and kwargs: {}"
    
    >>> mySwitch('yo')
    "gotStuffInSeq: I got 'yo', with args: () and kwargs: {}"
