\section{Built-in Module \sectcode{pyrl}}
\bimodindex{pyrl}
\renewcommand{\indexsubitem}{(in module pyrl)}

The \code{pyrl} module plugins the \dfn{GNU readline} facilities into
the interpreter when it runs in interactive mode. You do not need to
import this module, as this is done automatically whenever the
interpreter goes in interactive mode. You may need to do it explicitly
if you want to use its functionalities in your own scripts.

Putting the readline facility in its own module has several
advantages: if you can build it as a shared module, it will save
hundreds of kilobytes in the core interpreter binary image, as it will
be loaded only when you execute Python in interactive mode; since the
GNU readline may be configured to fits your needs, the module provides
hooks to modify its behaviour in an easy and pythonic way.

Because the module requires a patched Python interpreter, it's
available separately.

The \code{pyrl} module defines the following functions:

\begin{funcdesc}{set_completer}{callable-object}
Replaces the builtin completer function with
\var{callable-object}. This function gets called whenever the user
hits \code{M-Tab} (or \code{ESC-Tab}): it receives three arguments,
the \var{TEXT} entered so far, \var{START} and \var{END} delimit the
region of \var{TEXT} that contains the word to complete. It should
return the list of the possible completions for \var{TEXT}, or None.

Passing None as \var{callable-object} restores the builtin completer.

It returns the old completer object, or None if it was the builtin
one.
\end{funcdesc}

\begin{funcdesc}{builtin_completer}{text, start, end}
This is the builtin completer function. You can use it from
your own completer function. It returns the list containing the
completions, or None if there is no possible completion.
\end{funcdesc}

\begin{funcdesc}{readline}{\optional{prompt}}
Reads a line of user input using the GNU readline facilities. Returns
a string object.
\end{funcdesc}

The \dfn{callable object} you pass to \code{set\_completer()} should
return a list containing the possible completion for \var{TEXT}.

\begin{verbatim}
>>> def my_completer (text, start, end):
...     from pyrl import builtin_completer
...     print "Text: %s start: %d end: %d" % (text, start, end)
...     compl = builtin_completer (text, start, end)
...     print compl
...     return compl
...
>>> pyrl.set_completer (my_completer)
>>> py M-Tab
Text: py start: 0 end: 2
['pyrl']
>>> pyrl
\end{verbatim}



