\section{\module{rlcompleter} ---
         Completion function for GNU readline}

\declaremodule{standard}{rlcompleter}
\sectionauthor{Moshe Zadka}{[email protected]}
\modulesynopsis{Python identifier completion, suitable for the GNU readline library.}

The \module{rlcompleter} module defines a completion function suitable for
the \refmodule{readline} module by completing valid Python identifiers
and keywords.

When this module is imported on a \UNIX\ platform with the \module{readline}
module available, an instance of the \class{Completer} class is automatically
created and its \method{complete} method is set as the \module{readline}
completer.

Example:

\begin{verbatim}
>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__          readline.get_line_buffer  readline.read_init_file
readline.__file__         readline.insert_text      readline.set_completer
readline.__name__         readline.parse_and_bind
>>> readline.
\end{verbatim}

The \module{rlcompleter} module is designed for use with Python's
interactive mode.  A user can add the following lines to his or her
initialization file (identified by the \envvar{PYTHONSTARTUP}
environment variable) to get automatic \kbd{Tab} completion:

\begin{verbatim}
try:
    import readline
except ImportError:
    print "Module readline not available."
else:
    import rlcompleter
    readline.parse_and_bind("tab: complete")
\end{verbatim}


On platforms without \module{readline}, the \class{Completer} class defined
by this module can still be used for custom purposes.

\subsection{Completer Objects \label{completer-objects}}

Completer objects have the following method:

\begin{methoddesc}[Completer]{complete}{text, state}
Return the \var{state}th completion for \var{text}.

If called for \var{text} that doesn't include a period character
(\character{.}), it will complete from names currently defined in
\refmodule[main]{__main__}, \refmodule[builtin]{__builtin__} and
keywords (as defined by the \refmodule{keyword} module).

If called for a dotted name, it will try to evaluate anything without
obvious side-effects (functions will not be evaluated, but it
can generate calls to \method{__getattr__()}) up to the last part, and
find matches for the rest via the \function{dir()} function.
\end{methoddesc}