/Doc/library/readline.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 238 lines · 138 code · 100 blank · 0 comment · 0 complexity · 06fd9a5936c18d94ca3fa29534ddd471 MD5 · raw file
- :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.
- 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
- 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
- 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)
- 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)