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 to
  11 facilitate completion and reading/writing of history files from the
  12 Python interpreter.  This module can be used directly or via the
  13 \refmodule{rlcompleter} module.  Settings made using
  14 this module affect the behaviour of both the interpreter's interactive prompt
  15 and the prompts offered by the \function{raw_input()} and \function{input()}
  16 built-in functions.
  17
  18 The \module{readline} module defines the following functions:
  19
  20
  21 \begin{funcdesc}{parse_and_bind}{string}
  22 Parse and execute single line of a readline init file.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{get_line_buffer}{}
  26 Return the current contents of the line buffer.
  27 \end{funcdesc}
  28
  29 \begin{funcdesc}{insert_text}{string}
  30 Insert text into the command line.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{read_init_file}{\optional{filename}}
  34 Parse a readline initialization file.
  35 The default filename is the last filename used.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{read_history_file}{\optional{filename}}
  39 Load a readline history file.
  40 The default filename is \file{\~{}/.history}.
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{write_history_file}{\optional{filename}}
  44 Save a readline history file.
  45 The default filename is \file{\~{}/.history}.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{clear_history}{}
  49 Clear the current history.  (Note: this function is not available if
  50 the installed version of GNU readline doesn't support it.)
  51 \versionadded{2.4}
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{get_history_length}{}
  55 Return the desired length of the history file.  Negative values imply
  56 unlimited history file size.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{set_history_length}{length}
  60 Set the number of lines to save in the history file.
  61 \function{write_history_file()} uses this value to truncate the
  62 history file when saving.  Negative values imply unlimited history
  63 file size.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{get_current_history_length}{}
  67 Return the number of lines currently in the history.  (This is different
  68 from \function{get_history_length()}, which returns the maximum number of
  69 lines that will be written to a history file.)  \versionadded{2.3}
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{get_history_item}{index}
  73 Return the current contents of history item at \var{index}.
  74 \versionadded{2.3}
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{remove_history_item}{pos}
  78 Remove history item specified by its position from the history.
  79 \versionadded{2.4}
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{replace_history_item}{pos, line}
  83 Replace history item specified by its position with the given line.
  84 \versionadded{2.4}
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{redisplay}{}
  88 Change what's displayed on the screen to reflect the current contents
  89 of the line buffer.  \versionadded{2.3}
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{set_startup_hook}{\optional{function}}
  93 Set or remove the startup_hook function.  If \var{function} is specified,
  94 it will be used as the new startup_hook function; if omitted or
  95 \code{None}, any hook function already installed is removed.  The
  96 startup_hook function is called with no arguments just
  97 before readline prints the first prompt.
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{set_pre_input_hook}{\optional{function}}
 101 Set or remove the pre_input_hook function.  If \var{function} is specified,
 102 it will be used as the new pre_input_hook function; if omitted or
 103 \code{None}, any hook function already installed is removed.  The
 104 pre_input_hook function is called with no arguments after the first prompt
 105 has been printed and just before readline starts reading input characters.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{set_completer}{\optional{function}}
 109 Set or remove the completer function.  If \var{function} is specified,
 110 it will be used as the new completer function; if omitted or
 111 \code{None}, any completer function already installed is removed.  The
 112 completer function is called as \code{\var{function}(\var{text},
 113 \var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
 114 until it returns a non-string value.  It should return the next
 115 possible completion starting with \var{text}.
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{get_completer}{}
 119 Get the completer function, or \code{None} if no completer function
 120 has been set.  \versionadded{2.3}
 121 \end{funcdesc}
 122
 123 \begin{funcdesc}{get_begidx}{}
 124 Get the beginning index of the readline tab-completion scope.
 125 \end{funcdesc}
 126
 127 \begin{funcdesc}{get_endidx}{}
 128 Get the ending index of the readline tab-completion scope.
 129 \end{funcdesc}
 130
 131 \begin{funcdesc}{set_completer_delims}{string}
 132 Set the readline word delimiters for tab-completion.
 133 \end{funcdesc}
 134
 135 \begin{funcdesc}{get_completer_delims}{}
 136 Get the readline word delimiters for tab-completion.
 137 \end{funcdesc}
 138
 139 \begin{funcdesc}{add_history}{line}
 140 Append a line to the history buffer, as if it was the last line typed.
 141 \end{funcdesc}
 142
 143 \begin{seealso}
 144   \seemodule{rlcompleter}{Completion of Python identifiers at the
 145                           interactive prompt.}
 146 \end{seealso}
 147
 148
 149 \subsection{Example \label{readline-example}}
 150
 151 The following example demonstrates how to use the
 152 \module{readline} module's history reading and writing functions to
 153 automatically load and save a history file named \file{.pyhist} from
 154 the user's home directory.  The code below would normally be executed
 155 automatically during interactive sessions from the user's
 156 \envvar{PYTHONSTARTUP} file.
 157
 158 \begin{verbatim}
 159 import os
 160 histfile = os.path.join(os.environ["HOME"], ".pyhist")
 161 try:
 162     readline.read_history_file(histfile)
 163 except IOError:
 164     pass
 165 import atexit
 166 atexit.register(readline.write_history_file, histfile)
 167 del os, histfile
 168 \end{verbatim}
 169
 170 The following example extends the \class{code.InteractiveConsole} class to
 171 support history save/restore.
 172
 173 \begin{verbatim}
 174 import code
 175 import readline
 176 import atexit
 177 import os
 178
 179 class HistoryConsole(code.InteractiveConsole):
 180     def __init__(self, locals=None, filename="<console>",
 181                  histfile=os.path.expanduser("~/.console-history")):
 182         code.InteractiveConsole.__init__(self)
 183         self.init_history(histfile)
 184
 185     def init_history(self, histfile):
 186         readline.parse_and_bind("tab: complete")
 187         if hasattr(readline, "read_history_file"):
 188             try:
 189                 readline.read_history_file(histfile)
 190             except IOError:
 191                 pass
 192             atexit.register(self.save_history, histfile)
 193
 194     def save_history(self, histfile):
 195         readline.write_history_file(histfile)
 196 \end{verbatim}