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_startup_hook}{\optional{function}}
  58 Set or remove the startup_hook function.  If \var{function} is specified,
  59 it will be used as the new startup_hook function; if omitted or
  60 \code{None}, any hook function already installed is removed.  The
  61 startup_hook function is called with no arguments just
  62 before readline prints the first prompt.
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{set_pre_input_hook}{\optional{function}}
  66 Set or remove the pre_input_hook function.  If \var{function} is specified,
  67 it will be used as the new pre_input_hook function; if omitted or
  68 \code{None}, any hook function already installed is removed.  The
  69 pre_input_hook function is called with no arguments after the first prompt
  70 has been printed and just before readline starts reading input characters.
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{set_completer}{\optional{function}}
  74 Set or remove the completer function.  If \var{function} is specified,
  75 it will be used as the new completer function; if omitted or
  76 \code{None}, any completer function already installed is removed.  The
  77 completer function is called as \code{\var{function}(\var{text},
  78 \var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
  79 until it returns a non-string value.  It should return the next
  80 possible completion starting with \var{text}.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{get_completer}{}
  84 Get the completer function, or \code{None} if no completer function
  85 has been set.  \versionadded{2.3}
  86 \end{funcdesc}
  87
  88 \begin{funcdesc}{get_begidx}{}
  89 Get the beginning index of the readline tab-completion scope.
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{get_endidx}{}
  93 Get the ending index of the readline tab-completion scope.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{set_completer_delims}{string}
  97 Set the readline word delimiters for tab-completion.
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{get_completer_delims}{}
 101 Get the readline word delimiters for tab-completion.
 102 \end{funcdesc}
 103
 104 \begin{funcdesc}{add_history}{line}
 105 Append a line to the history buffer, as if it was the last line typed.
 106 \end{funcdesc}
 107
 108
 109 \begin{seealso}
 110   \seemodule{rlcompleter}{Completion of Python identifiers at the
 111                           interactive prompt.}
 112 \end{seealso}
 113
 114
 115 \subsection{Example \label{readline-example}}
 116
 117 The following example demonstrates how to use the
 118 \module{readline} module's history reading and writing functions to
 119 automatically load and save a history file named \file{.pyhist} from
 120 the user's home directory.  The code below would normally be executed
 121 automatically during interactive sessions from the user's
 122 \envvar{PYTHONSTARTUP} file.
 123
 124 \begin{verbatim}
 125 import os
 126 histfile = os.path.join(os.environ["HOME"], ".pyhist")
 127 try:
 128     readline.read_history_file(histfile)
 129 except IOError:
 130     pass
 131 import atexit
 132 atexit.register(readline.write_history_file, histfile)
 133 del os, histfile
 134 \end{verbatim}