===========
tl.readline
===========

  >>> import tl.readline

Convenience functions for custom tab completion
===============================================

The Python ``readline`` module uses two kinds of functions for implementing
custom tab completion rules:

- Completers that determine all possible completions on some partial text and
  possibly the whole input line. The return value is an iterable of all
  possible matching strings.

- Completion generators that return possible completions on some partial text
  one at a time. Their iteration behaviour is controlled by a status argument.

``tl.readline`` provides a function factory that produces a completer function
of the former kind that completes partial text from a static list of strings:

  >>> completer = tl.readline.static_completions(["foo", "bar", "baz"])
  >>> completer
  <function completions at 0x...>

Calling this completer function always produces a generator which may in turn
yield any number of possible completions:

  >>> matches = completer("asdf")
  >>> matches
  <generator object at 0x...>
  >>> list(matches)
  []

  >>> matches = completer("f")
  >>> matches
  <generator object at 0x...>
  >>> list(matches)
  ['foo']

  >>> matches = completer("foo")
  >>> matches
  <generator object at 0x...>
  >>> list(matches)
  ['foo']

  >>> matches = completer("ba")
  >>> matches
  <generator object at 0x...>
  >>> list(matches)
  ['bar', 'baz']


.. Local Variables:
.. mode: rst
.. End:
