\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}