libreadline.tex 3.14 KB
Newer Older
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 12 13
directly or from the \refmodule{rlcompleter} module to facilitate
completion and history file read and write from the Python
interpreter.
14 15 16

The \module{readline} module defines the following functions:

17

18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
\begin{funcdesc}{parse_and_bind}{string}
Parse and execute single line of a readline init file.
\end{funcdesc}

\begin{funcdesc}{get_line_buffer}{}
Return the current contents of the line buffer.
\end{funcdesc}

\begin{funcdesc}{insert_text}{string}
Insert text into the command line.
\end{funcdesc}

\begin{funcdesc}{read_init_file}{\optional{filename}}
Parse a readline initialization file.
The default filename is the last filename used.
\end{funcdesc}

\begin{funcdesc}{read_history_file}{\optional{filename}}
Load a readline history file.
37
The default filename is \file{\~{}/.history}.
38 39 40 41
\end{funcdesc}

\begin{funcdesc}{write_history_file}{\optional{filename}}
Save a readline history file.
42
The default filename is \file{\~{}/.history}.
43 44
\end{funcdesc}

45 46 47 48 49 50 51
\begin{funcdesc}{get_history_length}{}
Return the desired length of the history file.  Negative values imply
unlimited history file size.
\end{funcdesc}

\begin{funcdesc}{set_history_length}{length}
Set the number of lines to save in the history file.
Fred Drake's avatar
Fred Drake committed
52 53 54
\function{write_history_file()} uses this value to truncate the
history file when saving.  Negative values imply unlimited history
file size.
55 56
\end{funcdesc}

57
\begin{funcdesc}{set_completer}{\optional{function}}
58 59
Set or remove the completer function.  The completer function is
called as \code{\var{function}(\var{text}, \var{state})},
60
\code{for i in [0, 1, 2, ...]} until it returns a non-string.
61
It should return the next possible completion starting with \var{text}.
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
\end{funcdesc}

\begin{funcdesc}{get_begidx}{}
Get the beginning index of the readline tab-completion scope.
\end{funcdesc}

\begin{funcdesc}{get_endidx}{}
Get the ending index of the readline tab-completion scope.
\end{funcdesc}

\begin{funcdesc}{set_completer_delims}{string}
Set the readline word delimiters for tab-completion.
\end{funcdesc}

\begin{funcdesc}{get_completer_delims}{}
Get the readline word delimiters for tab-completion.
\end{funcdesc}


81 82 83 84 85 86 87 88 89 90 91 92 93 94
\begin{seealso}
  \seemodule{rlcompleter}{Completion of Python identifiers at the
                          interactive prompt.}
\end{seealso}


\subsection{Example \label{readline-example}}

The following example demonstrates how to use the
\module{readline} module's history reading and writing functions to
automatically load and save a history file named \file{.pyhist} from
the user's home directory.  The code below would normally be executed
automatically during interactive sessions from the user's
\envvar{PYTHONSTARTUP} file.
95 96

\begin{verbatim}
97 98 99 100 101 102 103 104 105
import os
histfile = os.path.join(os.environ["HOME"], ".pyhist")
try:
    readline.read_history_file(histfile)
except IOError:
    pass
import atexit
atexit.register(readline.write_history_file, histfile)
del os, histfile
106
\end{verbatim}