ref: 5513dae7d9eee46f7e1843c8eeeaf9066d0ec632
dir: /sys/src/cmd/python/Doc/lib/libreadline.tex/
\section{\module{readline} ---
GNU readline interface}
\declaremodule{builtin}{readline}
\platform{Unix}
\sectionauthor{Skip Montanaro}{skip@mojam.com}
\modulesynopsis{GNU readline support for Python.}
The \module{readline} module defines a number of functions to
facilitate completion and reading/writing of history files from the
Python interpreter. This module can be used directly or via the
\refmodule{rlcompleter} module. Settings made using
this module affect the behaviour of both the interpreter's interactive prompt
and the prompts offered by the \function{raw_input()} and \function{input()}
built-in functions.
The \module{readline} module defines the following functions:
\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.
The default filename is \file{\~{}/.history}.
\end{funcdesc}
\begin{funcdesc}{write_history_file}{\optional{filename}}
Save a readline history file.
The default filename is \file{\~{}/.history}.
\end{funcdesc}
\begin{funcdesc}{clear_history}{}
Clear the current history. (Note: this function is not available if
the installed version of GNU readline doesn't support it.)
\versionadded{2.4}
\end{funcdesc}
\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.
\function{write_history_file()} uses this value to truncate the
history file when saving. Negative values imply unlimited history
file size.
\end{funcdesc}
\begin{funcdesc}{get_current_history_length}{}
Return the number of lines currently in the history. (This is different
from \function{get_history_length()}, which returns the maximum number of
lines that will be written to a history file.) \versionadded{2.3}
\end{funcdesc}
\begin{funcdesc}{get_history_item}{index}
Return the current contents of history item at \var{index}.
\versionadded{2.3}
\end{funcdesc}
\begin{funcdesc}{remove_history_item}{pos}
Remove history item specified by its position from the history.
\versionadded{2.4}
\end{funcdesc}
\begin{funcdesc}{replace_history_item}{pos, line}
Replace history item specified by its position with the given line.
\versionadded{2.4}
\end{funcdesc}
\begin{funcdesc}{redisplay}{}
Change what's displayed on the screen to reflect the current contents
of the line buffer. \versionadded{2.3}
\end{funcdesc}
\begin{funcdesc}{set_startup_hook}{\optional{function}}
Set or remove the startup_hook function. If \var{function} is specified,
it will be used as the new startup_hook function; if omitted or
\code{None}, any hook function already installed is removed. The
startup_hook function is called with no arguments just
before readline prints the first prompt.
\end{funcdesc}
\begin{funcdesc}{set_pre_input_hook}{\optional{function}}
Set or remove the pre_input_hook function. If \var{function} is specified,
it will be used as the new pre_input_hook function; if omitted or
\code{None}, any hook function already installed is removed. The
pre_input_hook function is called with no arguments after the first prompt
has been printed and just before readline starts reading input characters.
\end{funcdesc}
\begin{funcdesc}{set_completer}{\optional{function}}
Set or remove the completer function. If \var{function} is specified,
it will be used as the new completer function; if omitted or
\code{None}, any completer function already installed is removed. The
completer function is called as \code{\var{function}(\var{text},
\var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
until it returns a non-string value. It should return the next
possible completion starting with \var{text}.
\end{funcdesc}
\begin{funcdesc}{get_completer}{}
Get the completer function, or \code{None} if no completer function
has been set. \versionadded{2.3}
\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}
\begin{funcdesc}{add_history}{line}
Append a line to the history buffer, as if it was the last line typed.
\end{funcdesc}
\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.
\begin{verbatim}
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
\end{verbatim}
The following example extends the \class{code.InteractiveConsole} class to
support history save/restore.
\begin{verbatim}
import code
import readline
import atexit
import os
class HistoryConsole(code.InteractiveConsole):
def __init__(self, locals=None, filename="<console>",
histfile=os.path.expanduser("~/.console-history")):
code.InteractiveConsole.__init__(self)
self.init_history(histfile)
def init_history(self, histfile):
readline.parse_and_bind("tab: complete")
if hasattr(readline, "read_history_file"):
try:
readline.read_history_file(histfile)
except IOError:
pass
atexit.register(self.save_history, histfile)
def save_history(self, histfile):
readline.write_history_file(histfile)
\end{verbatim}