diff options
Diffstat (limited to 'Doc/library/readline.rst')
| -rw-r--r-- | Doc/library/readline.rst | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst new file mode 100644 index 0000000..9a40747 --- /dev/null +++ b/Doc/library/readline.rst @@ -0,0 +1,222 @@ + +:mod:`readline` --- GNU readline interface +========================================== + +.. module:: readline + :platform: Unix + :synopsis: GNU readline support for Python. +.. sectionauthor:: Skip Montanaro <skip@mojam.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_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:: 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) + |