Add support for enumerations

[ghost]

We can already do this:

Usage: go (north | west | east | south)

But this uses subcommands, which have an awkward access syntax, and issues #42 and #4 suggest to me they're meant for something rather more heavy-duty. Moreover, the set of legal values might be too verbose or too large to enumerate in an usage pattern. In such cases, something like this would be more useful:

Usage: go <direction>

  <direction>  The direction to go in (north, west, east, south)

[sonwell]

There is support for this in the form of

args = docopt(...)

if args['<direction>'] not in ['north', 'west', 'east', 'south']:
    raise SomeException

[keleshev]

This could be done for options with arguments:

Usage: prog [options]

--option=(this | that | or-that)

but dunno how to do it nicely for positional arguments...

[ghost]

We've already got syntax for default values, which seems to me to be a intuitive basis for this (and other argument value metadata stuff, like in #8.) If/when #37 gets implemented, it would naturally also apply to positional arguments. Something like this:

  <direction>  The direction to go in [north, south, west, east, default: north]

Vis-a-vis prior art, the only programs I could think of that have arguments like this were xrandr and xsetwacom, who communicate the idea with

--rotate normal,inverted,left,right
--orientation <normal,inverted,left,right,0,1,2,3>
Rotate           - Sets the rotation of the tablet. Values = none, cw, ccw, half (default is none).

But I don't really like any of them.

[keleshev]

Maybe this should be dropped (similar to #8) in favor of using schema-validation tools instead, like in this example:

https://github.com/docopt/docopt/blob/master/examples/validation_example.py

[keleshev]

This issue is a special case of #52, further discussion is directed there.