From aad86a6015f8d4e1e4faea07e1400152f5843443 Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Tue, 5 Apr 2016 07:37:22 +0000 Subject: Issue #6953: Rearrange and expand Readline module documentation * Group functions into six new subsections * Document the underlying Readline function or variable accessed * get_history_length() returns the history file limit * clear_history() is conditionally compiled in * Clarify zero and one bases for history item indexes * parse_and_bind() uses its argument directly as an init line * Change "command line" to "line buffer" for consistency * read_init_file() also executes the file * read_history_file() replaces the previous history * write_history_file() overwrites any existing file * Differentiate history file lines from history list items, which could be multi-line * Add more information about completion, also addressing Issue #10796 * libedit (Editline) may be used on any platform; detection is OS X specific --- Doc/library/readline.rst | 172 +++++++++++++++++++++++++++++++---------------- Misc/NEWS | 7 ++ Modules/readline.c | 30 ++++----- 3 files changed, 136 insertions(+), 73 deletions(-) diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index 4fc3e93..d7e7dc6 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -9,15 +9,18 @@ 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 +This module can be used directly, or via the :mod:`rlcompleter` module, which +supports completion of Python identifiers at the interactive prompt. 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 underlying Readline library API may be implemented by the ``libedit`` library instead of GNU readline. + On MacOS X the :mod:`readline` module detects which library is being used + at run time. The configuration file for ``libedit`` is different from that of GNU readline. If you programmatically load configuration strings @@ -25,64 +28,97 @@ interactive prompt and the prompts offered by the :func:`raw_input` and to differentiate between GNU readline and libedit. -The :mod:`readline` module defines the following functions: +Init file +--------- + +The following functions relate to the init file and user configuration: .. function:: parse_and_bind(string) - Parse and execute single line of a readline init file. + Execute the init line provided in the *string* argument. This calls + :c:func:`rl_parse_and_bind` in the underlying library. + + +.. function:: read_init_file([filename]) + + Execute a readline initialization file. The default filename is the last filename + used. This calls :c:func:`rl_read_init_file` in the underlying library. + + +Line buffer +----------- + +The following functions operate on the line buffer: .. function:: get_line_buffer() - Return the current contents of the line buffer. + Return the current contents of the line buffer (:c:data:`rl_line_buffer` + in the underlying library). .. function:: insert_text(string) - Insert text into the command line. + Insert text into the line buffer at the cursor position. This calls + :c:func:`rl_insert_text` in the underlying library, but ignores + the return value. -.. function:: read_init_file([filename]) +.. function:: redisplay() + + Change what's displayed on the screen to reflect the current contents of the + line buffer. This calls :c:func:`rl_redisplay` in the underlying library. + + +History file +------------ - Parse a readline initialization file. The default filename is the last filename - used. +The following functions operate on a history file: .. function:: read_history_file([filename]) - Load a readline history file. The default filename is :file:`~/.history`. + Load a readline history file, and append it to the history list. + The default filename is :file:`~/.history`. This calls + :c:func:`read_history` in the underlying library. .. function:: write_history_file([filename]) - Save a readline history file. The default filename is :file:`~/.history`. + Save the history list to a readline history file, overwriting any + existing file. The default filename is :file:`~/.history`. This calls + :c:func:`write_history` in the underlying library. -.. function:: clear_history() +.. function:: get_history_length() + set_history_length(length) - Clear the current history. (Note: this function is not available if the - installed version of GNU readline doesn't support it.) + Set or return the desired number of lines to save in the history file. + The :func:`write_history_file` function uses this value to truncate + the history file, by calling :c:func:`history_truncate_file` in + the underlying library. Negative values imply + unlimited history file size. - .. versionadded:: 2.4 +History list +------------ -.. function:: get_history_length() +The following functions operate on a global history list: - Return the desired length of the history file. Negative values imply unlimited - history file size. +.. function:: clear_history() -.. function:: set_history_length(length) + Clear the current history. This calls :c:func:`clear_history` in the + underlying library. The Python function only exists if Python was + compiled for a version of the library that supports it. - 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. + .. versionadded:: 2.4 .. function:: get_current_history_length() - Return the number of lines currently in the history. (This is different from + Return the number of items 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.) @@ -91,7 +127,8 @@ The :mod:`readline` module defines the following functions: .. function:: get_history_item(index) - Return the current contents of history item at *index*. + Return the current contents of history item at *index*. The item index + is one-based. This calls :c:func:`history_get` in the underlying library. .. versionadded:: 2.3 @@ -99,42 +136,63 @@ The :mod:`readline` module defines the following functions: .. function:: remove_history_item(pos) Remove history item specified by its position from the history. + The position is zero-based. This calls :c:func:`remove_history` in + the underlying library. .. versionadded:: 2.4 .. function:: replace_history_item(pos, line) - Replace history item specified by its position with the given line. + Replace history item specified by its position with *line*. + The position is zero-based. This calls :c:func:`replace_history_entry` + in the underlying library. .. versionadded:: 2.4 -.. function:: redisplay() +.. function:: add_history(line) - Change what's displayed on the screen to reflect the current contents of the - line buffer. + Append *line* to the history buffer, as if it was the last line typed. + This calls :c:func:`add_history` in the underlying library. + + +Startup hooks +------------- .. 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 + Set or remove the function invoked by the :c:data:`rl_startup_hook` + callback of the underlying library. If *function* is specified, it will + be used as the new hook function; if omitted or ``None``, any function + already installed is removed. The hook 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 + Set or remove the function invoked by the :c:data:`rl_pre_input_hook` + callback of the underlying library. If *function* is specified, it will + be used as the new hook function; if omitted or ``None``, any + function already installed is removed. The hook is called with no arguments after the first prompt has been printed and just before readline starts reading input characters. +Completion +---------- + +The following functions relate to implementing a custom word completion +function. This is typically operated by the Tab key, and can suggest and +automatically complete a word being typed. By default, Readline is set up +to be used by :mod:`rlcompleter` to complete Python identifiers for +the interactive interpreter. If the :mod:`readline` module is to be used +with a custom completer, a different set of word delimiters should be set. + + .. function:: set_completer([function]) Set or remove the completer function. If *function* is specified, it will be @@ -144,6 +202,12 @@ The :mod:`readline` module defines the following functions: returns a non-string value. It should return the next possible completion starting with *text*. + The installed completer function is invoked by the *entry_func* callback + passed to :c:func:`rl_completion_matches` in the underlying library. + The *text* string comes from the first parameter to the + :c:data:`rl_attempted_completion_function` callback of the + underlying library. + .. function:: get_completer() @@ -154,50 +218,42 @@ The :mod:`readline` module defines the following functions: .. function:: get_completion_type() - Get the type of completion being attempted. + Get the type of completion being attempted. This returns the + :c:data:`rl_completion_type` variable in the underlying library as + an integer. .. versionadded:: 2.6 .. function:: get_begidx() + get_endidx() - Get the beginning index of the readline tab-completion scope. - - -.. function:: get_endidx() - - Get the ending index of the readline tab-completion scope. + Get the beginning or ending index of the completion scope. + These indexes are the *start* and *end* arguments passed to the + :c:data:`rl_attempted_completion_function` callback of the + underlying library. .. function:: set_completer_delims(string) + get_completer_delims() - Set the readline word delimiters for tab-completion. - - -.. function:: get_completer_delims() - - Get the readline word delimiters for tab-completion. + Set or get the word delimiters for completion. These determine the + start of the word to be considered for completion (the completion scope). + These functions access the :c:data:`rl_completer_word_break_characters` + variable in the underlying library. .. 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 + installed is removed. This sets or clears the + :c:data:`rl_completion_display_matches_hook` callback in the + underlying library. 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 diff --git a/Misc/NEWS b/Misc/NEWS index d6b490a..c0e0e4d 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -184,6 +184,13 @@ IDLE installing IDLE 2.7 on OS X: default configuration settings are no longer installed from OS X specific copies. +Documentation +------------- + +- Issue #6953: Rework the Readline module documentation to group related + functions together, and add more details such as what underlying Readline + functions and variables are accessed. + Tests ----- diff --git a/Modules/readline.c b/Modules/readline.c index 0a00c9f..e3a5ed1 100644 --- a/Modules/readline.c +++ b/Modules/readline.c @@ -96,7 +96,7 @@ parse_and_bind(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_parse_and_bind, "parse_and_bind(string) -> None\n\ -Parse and execute single line of a readline init file."); +Execute the init line provided in the string argument."); /* Exported function to parse a readline init file */ @@ -115,7 +115,7 @@ read_init_file(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_read_init_file, "read_init_file([filename]) -> None\n\ -Parse a readline initialization file.\n\ +Execute a readline initialization file.\n\ The default filename is the last filename used."); @@ -176,7 +176,7 @@ set_history_length(PyObject *self, PyObject *args) PyDoc_STRVAR(set_history_length_doc, "set_history_length(length) -> None\n\ -set the maximal number of items which will be written to\n\ +set the maximal number of lines which will be written to\n\ the history file. A negative length is used to inhibit\n\ history truncation."); @@ -191,7 +191,7 @@ get_history_length(PyObject *self, PyObject *noarg) PyDoc_STRVAR(get_history_length_doc, "get_history_length() -> int\n\ -return the maximum number of items that will be written to\n\ +return the maximum number of lines that will be written to\n\ the history file."); @@ -269,7 +269,7 @@ set_startup_hook(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_set_startup_hook, "set_startup_hook([function]) -> None\n\ -Set or remove the startup_hook function.\n\ +Set or remove the function invoked by the rl_startup_hook callback.\n\ The function is called with no arguments just\n\ before readline prints the first prompt."); @@ -286,7 +286,7 @@ set_pre_input_hook(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_set_pre_input_hook, "set_pre_input_hook([function]) -> None\n\ -Set or remove the pre_input_hook function.\n\ +Set or remove the function invoked by the rl_pre_input_hook callback.\n\ The function is called with no arguments after the first prompt\n\ has been printed and just before readline starts reading input\n\ characters."); @@ -325,7 +325,7 @@ get_begidx(PyObject *self, PyObject *noarg) PyDoc_STRVAR(doc_get_begidx, "get_begidx() -> int\n\ -get the beginning index of the readline tab-completion scope"); +get the beginning index of the completion scope"); /* Get the ending index for the scope of the tab-completion */ @@ -339,7 +339,7 @@ get_endidx(PyObject *self, PyObject *noarg) PyDoc_STRVAR(doc_get_endidx, "get_endidx() -> int\n\ -get the ending index of the readline tab-completion scope"); +get the ending index of the completion scope"); /* Set the tab-completion word-delimiters that readline uses */ @@ -368,7 +368,7 @@ set_completer_delims(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_set_completer_delims, "set_completer_delims(string) -> None\n\ -set the readline word delimiters for tab-completion"); +set the word delimiters for completion"); /* _py_free_history_entry: Utility function to free a history entry. */ @@ -408,7 +408,7 @@ py_remove_history(PyObject *self, PyObject *args) int entry_number; HIST_ENTRY *entry; - if (!PyArg_ParseTuple(args, "i:remove_history", &entry_number)) + if (!PyArg_ParseTuple(args, "i:remove_history_item", &entry_number)) return NULL; if (entry_number < 0) { PyErr_SetString(PyExc_ValueError, @@ -438,7 +438,7 @@ py_replace_history(PyObject *self, PyObject *args) char *line; HIST_ENTRY *old_entry; - if (!PyArg_ParseTuple(args, "is:replace_history", &entry_number, + if (!PyArg_ParseTuple(args, "is:replace_history_item", &entry_number, &line)) { return NULL; } @@ -479,7 +479,7 @@ py_add_history(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_add_history, "add_history(string) -> None\n\ -add a line to the history buffer"); +add an item to the history buffer"); /* Get the tab-completion word-delimiters that readline uses */ @@ -492,7 +492,7 @@ get_completer_delims(PyObject *self, PyObject *noarg) PyDoc_STRVAR(doc_get_completer_delims, "get_completer_delims() -> string\n\ -get the readline word delimiters for tab-completion"); +get the word delimiters for completion"); /* Set the completer function */ @@ -553,7 +553,7 @@ get_history_item(PyObject *self, PyObject *args) int idx = 0; HIST_ENTRY *hist_ent; - if (!PyArg_ParseTuple(args, "i:index", &idx)) + if (!PyArg_ParseTuple(args, "i:get_history_item", &idx)) return NULL; #ifdef __APPLE__ if (using_libedit_emulation) { @@ -645,7 +645,7 @@ insert_text(PyObject *self, PyObject *args) PyDoc_STRVAR(doc_insert_text, "insert_text(string) -> None\n\ -Insert text into the command line."); +Insert text into the line buffer at the cursor position."); /* Redisplay the line buffer */ -- cgit v0.12