Doc/lib/librlcompleter.tex

   1 \section{\module{rlcompleter} ---
   2          Completion function for GNU readline}
   3
   4 \declaremodule{standard}{rlcompleter}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{Python identifier completion, suitable for the GNU readline library.}
   7
   8 The \module{rlcompleter} module defines a completion function suitable for
   9 the \refmodule{readline} module by completing valid Python identifiers
  10 and keywords.
  11
  12 When this module is imported on a \UNIX\ platform with the \module{readline}
  13 module available, an instance of the \class{Completer} class is automatically
  14 created and its \method{complete} method is set as the \module{readline}
  15 completer.
  16
  17 Example:
  18
  19 \begin{verbatim}
  20 >>> import rlcompleter
  21 >>> import readline
  22 >>> readline.parse_and_bind("tab: complete")
  23 >>> readline. <TAB PRESSED>
  24 readline.__doc__          readline.get_line_buffer  readline.read_init_file
  25 readline.__file__         readline.insert_text      readline.set_completer
  26 readline.__name__         readline.parse_and_bind
  27 >>> readline.
  28 \end{verbatim}
  29
  30 The \module{rlcompleter} module is designed for use with Python's
  31 interactive mode.  A user can add the following lines to his or her
  32 initialization file (identified by the \envvar{PYTHONSTARTUP}
  33 environment variable) to get automatic \kbd{Tab} completion:
  34
  35 \begin{verbatim}
  36 try:
  37     import readline
  38 except ImportError:
  39     print "Module readline not available."
  40 else:
  41     import rlcompleter
  42     readline.parse_and_bind("tab: complete")
  43 \end{verbatim}
  44
  45
  46 On platforms without \module{readline}, the \class{Completer} class defined
  47 by this module can still be used for custom purposes.
  48
  49 \subsection{Completer Objects \label{completer-objects}}
  50
  51 Completer objects have the following method:
  52
  53 \begin{methoddesc}[Completer]{complete}{text, state}
  54 Return the \var{state}th completion for \var{text}.
  55
  56 If called for \var{text} that doesn't include a period character
  57 (\character{.}), it will complete from names currently defined in
  58 \refmodule[main]{__main__}, \refmodule[builtin]{__builtin__} and
  59 keywords (as defined by the \refmodule{keyword} module).
  60
  61 If called for a dotted name, it will try to evaluate anything without
  62 obvious side-effects (functions will not be evaluated, but it
  63 can generate calls to \method{__getattr__()}) up to the last part, and
  64 find matches for the rest via the \function{dir()} function.
  65 \end{methoddesc}