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