Doc/lib/libreadline.tex

   1 \section{\module{readline} ---
   2          GNU readline interface}
   3
   4 \declaremodule{builtin}{readline}
   5   \platform{Unix}
   6 \sectionauthor{Skip Montanaro}{skip@mojam.com}
   7 \modulesynopsis{GNU readline support for Python.}
   8
   9
  10 The \module{readline} module defines a number of functions used either
  11 directly or from the \refmodule{rlcompleter} module to facilitate
  12 completion and history file read and write from the Python
  13 interpreter.
  14
  15 The \module{readline} module defines the following functions:
  16
  17
  18 \begin{funcdesc}{parse_and_bind}{string}
  19 Parse and execute single line of a readline init file.
  20 \end{funcdesc}
  21
  22 \begin{funcdesc}{get_line_buffer}{}
  23 Return the current contents of the line buffer.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{insert_text}{string}
  27 Insert text into the command line.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{read_init_file}{\optional{filename}}
  31 Parse a readline initialization file.
  32 The default filename is the last filename used.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{read_history_file}{\optional{filename}}
  36 Load a readline history file.
  37 The default filename is \file{\~{}/.history}.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{write_history_file}{\optional{filename}}
  41 Save a readline history file.
  42 The default filename is \file{\~{}/.history}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{get_history_length}{}
  46 Return the desired length of the history file.  Negative values imply
  47 unlimited history file size.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{set_history_length}{length}
  51 Set the number of lines to save in the history file.
  52 \function{write_history_file()} uses this value to truncate the
  53 history file when saving.  Negative values imply unlimited history
  54 file size.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{set_completer}{\optional{function}}
  58 Set or remove the completer function.  If \var{function} is specified,
  59 it will be used as the new completer function; if omitted or
  60 \code{None}, any completer function already installed is removed.  The
  61 completer function is called as \code{\var{function}(\var{text},
  62 \var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
  63 until it returns a non-string value.  It should return the next
  64 possible completion starting with \var{text}.
  65 \end{funcdesc}
  66
  67 \begin{funcdesc}{get_begidx}{}
  68 Get the beginning index of the readline tab-completion scope.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{get_endidx}{}
  72 Get the ending index of the readline tab-completion scope.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{set_completer_delims}{string}
  76 Set the readline word delimiters for tab-completion.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{get_completer_delims}{}
  80 Get the readline word delimiters for tab-completion.
  81 \end{funcdesc}
  82
  83
  84 \begin{seealso}
  85   \seemodule{rlcompleter}{Completion of Python identifiers at the
  86                           interactive prompt.}
  87 \end{seealso}
  88
  89
  90 \subsection{Example \label{readline-example}}
  91
  92 The following example demonstrates how to use the
  93 \module{readline} module's history reading and writing functions to
  94 automatically load and save a history file named \file{.pyhist} from
  95 the user's home directory.  The code below would normally be executed
  96 automatically during interactive sessions from the user's
  97 \envvar{PYTHONSTARTUP} file.
  98
  99 \begin{verbatim}
 100 import os
 101 histfile = os.path.join(os.environ["HOME"], ".pyhist")
 102 try:
 103     readline.read_history_file(histfile)
 104 except IOError:
 105     pass
 106 import atexit
 107 atexit.register(readline.write_history_file, histfile)
 108 del os, histfile
 109 \end{verbatim}