249 lines
7.1 KiB
ReStructuredText
249 lines
7.1 KiB
ReStructuredText
:mod:`readline` --- GNU readline interface
|
|
==========================================
|
|
|
|
.. module:: readline
|
|
:platform: Unix
|
|
:synopsis: GNU readline support for Python.
|
|
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
|
|
|
|
|
|
The :mod:`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 :mod:`rlcompleter` module. Settings
|
|
made using this module affect the behaviour of both the interpreter's
|
|
interactive prompt and the prompts offered by the :func:`raw_input` and
|
|
:func:`input` built-in functions.
|
|
|
|
.. note::
|
|
|
|
On MacOS X the :mod:`readline` module can be implemented using
|
|
the ``libedit`` library instead of GNU readline.
|
|
|
|
The configuration file for ``libedit`` is different from that
|
|
of GNU readline. If you programmatically load configuration strings
|
|
you can check for the text "libedit" in :const:`readline.__doc__`
|
|
to differentiate between GNU readline and libedit.
|
|
|
|
|
|
The :mod:`readline` module defines the following functions:
|
|
|
|
|
|
.. function:: parse_and_bind(string)
|
|
|
|
Parse and execute single line of a readline init file.
|
|
|
|
|
|
.. function:: get_line_buffer()
|
|
|
|
Return the current contents of the line buffer.
|
|
|
|
|
|
.. function:: insert_text(string)
|
|
|
|
Insert text into the command line.
|
|
|
|
|
|
.. function:: read_init_file([filename])
|
|
|
|
Parse a readline initialization file. The default filename is the last filename
|
|
used.
|
|
|
|
|
|
.. function:: read_history_file([filename])
|
|
|
|
Load a readline history file. The default filename is :file:`~/.history`.
|
|
|
|
|
|
.. function:: write_history_file([filename])
|
|
|
|
Save a readline history file. The default filename is :file:`~/.history`.
|
|
|
|
|
|
.. function:: 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
|
|
|
|
|
|
.. function:: get_history_length()
|
|
|
|
Return the desired length of the history file. Negative values imply unlimited
|
|
history file size.
|
|
|
|
|
|
.. function:: set_history_length(length)
|
|
|
|
Set the number of lines to save in the history file. :func:`write_history_file`
|
|
uses this value to truncate the history file when saving. Negative values imply
|
|
unlimited history file size.
|
|
|
|
|
|
.. function:: get_current_history_length()
|
|
|
|
Return the number of lines currently in the history. (This is different from
|
|
:func:`get_history_length`, which returns the maximum number of lines that will
|
|
be written to a history file.)
|
|
|
|
.. versionadded:: 2.3
|
|
|
|
|
|
.. function:: get_history_item(index)
|
|
|
|
Return the current contents of history item at *index*.
|
|
|
|
.. versionadded:: 2.3
|
|
|
|
|
|
.. function:: remove_history_item(pos)
|
|
|
|
Remove history item specified by its position from the history.
|
|
|
|
.. versionadded:: 2.4
|
|
|
|
|
|
.. function:: replace_history_item(pos, line)
|
|
|
|
Replace history item specified by its position with the given line.
|
|
|
|
.. versionadded:: 2.4
|
|
|
|
|
|
.. function:: redisplay()
|
|
|
|
Change what's displayed on the screen to reflect the current contents of the
|
|
line buffer.
|
|
|
|
.. versionadded:: 2.3
|
|
|
|
|
|
.. function:: set_startup_hook([function])
|
|
|
|
Set or remove the startup_hook function. If *function* is specified, it will be
|
|
used as the new startup_hook function; if omitted or ``None``, any hook function
|
|
already installed is removed. The startup_hook function is called with no
|
|
arguments just before readline prints the first prompt.
|
|
|
|
|
|
.. function:: set_pre_input_hook([function])
|
|
|
|
Set or remove the pre_input_hook function. If *function* is specified, it will
|
|
be used as the new pre_input_hook function; if omitted or ``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.
|
|
|
|
|
|
.. function:: set_completer([function])
|
|
|
|
Set or remove the completer function. If *function* is specified, it will be
|
|
used as the new completer function; if omitted or ``None``, any completer
|
|
function already installed is removed. The completer function is called as
|
|
``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it
|
|
returns a non-string value. It should return the next possible completion
|
|
starting with *text*.
|
|
|
|
|
|
.. function:: get_completer()
|
|
|
|
Get the completer function, or ``None`` if no completer function has been set.
|
|
|
|
.. versionadded:: 2.3
|
|
|
|
|
|
.. function:: get_completion_type()
|
|
|
|
Get the type of completion being attempted.
|
|
|
|
.. versionadded:: 2.6
|
|
|
|
.. function:: get_begidx()
|
|
|
|
Get the beginning index of the readline tab-completion scope.
|
|
|
|
|
|
.. function:: get_endidx()
|
|
|
|
Get the ending index of the readline tab-completion scope.
|
|
|
|
|
|
.. function:: set_completer_delims(string)
|
|
|
|
Set the readline word delimiters for tab-completion.
|
|
|
|
|
|
.. function:: get_completer_delims()
|
|
|
|
Get the readline word delimiters for tab-completion.
|
|
|
|
.. function:: set_completion_display_matches_hook([function])
|
|
|
|
Set or remove the completion display function. If *function* is
|
|
specified, it will be used as the new completion display function;
|
|
if omitted or ``None``, any completion display function already
|
|
installed is removed. The completion display function is called as
|
|
``function(substitution, [matches], longest_match_length)`` once
|
|
each time matches need to be displayed.
|
|
|
|
.. versionadded:: 2.6
|
|
|
|
.. function:: add_history(line)
|
|
|
|
Append a line to the history buffer, as if it was the last line typed.
|
|
|
|
.. seealso::
|
|
|
|
Module :mod:`rlcompleter`
|
|
Completion of Python identifiers at the interactive prompt.
|
|
|
|
|
|
.. _readline-example:
|
|
|
|
Example
|
|
-------
|
|
|
|
The following example demonstrates how to use the :mod:`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. ::
|
|
|
|
import os
|
|
import readline
|
|
histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
|
|
try:
|
|
readline.read_history_file(histfile)
|
|
except IOError:
|
|
pass
|
|
import atexit
|
|
atexit.register(readline.write_history_file, histfile)
|
|
del os, histfile
|
|
|
|
The following example extends the :class:`code.InteractiveConsole` class to
|
|
support history save/restore. ::
|
|
|
|
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, locals, filename)
|
|
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)
|
|
|