Issue #6953: Merge readline doc from 3.5
This commit is contained in:
Martin Panter
commit
b15c304984
|
|
@ -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 built-in :func:`input`
|
||||
function.
|
||||
|
||||
.. 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,112 +28,168 @@ function.
|
|||
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.
|
||||
|
||||
|
||||
.. function:: get_line_buffer()
|
||||
|
||||
Return the current contents of the line buffer.
|
||||
|
||||
|
||||
.. function:: insert_text(string)
|
||||
|
||||
Insert text into the command line.
|
||||
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])
|
||||
|
||||
Parse a readline initialization file. The default filename is the last filename
|
||||
used.
|
||||
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 (:c:data:`rl_line_buffer`
|
||||
in the underlying library).
|
||||
|
||||
|
||||
.. function:: insert_text(string)
|
||||
|
||||
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:: 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
|
||||
------------
|
||||
|
||||
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:: append_history_file(nelements[, filename])
|
||||
|
||||
Append the last *nelements* of history to a file. The default filename is
|
||||
:file:`~/.history`. The file must already exist.
|
||||
Append the last *nelements* items of history to a file. The default filename is
|
||||
:file:`~/.history`. The file must already exist. This calls
|
||||
:c:func:`append_history` in the underlying library.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
.. function:: get_history_length()
|
||||
set_history_length(length)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
History list
|
||||
------------
|
||||
|
||||
The following functions operate on a global history list:
|
||||
|
||||
|
||||
.. function:: clear_history()
|
||||
|
||||
Clear the current history. (Note: this function is not available if the
|
||||
installed version of GNU readline doesn't support it.)
|
||||
|
||||
|
||||
.. 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.
|
||||
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.
|
||||
|
||||
|
||||
.. 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.)
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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
|
||||
-------------
|
||||
|
||||
|
||||
.. 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
|
||||
|
|
@ -140,6 +199,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()
|
||||
|
||||
|
|
@ -148,27 +213,27 @@ 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.
|
||||
|
||||
|
||||
.. 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])
|
||||
|
|
@ -176,21 +241,13 @@ The :mod:`readline` module defines the following functions:
|
|||
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.
|
||||
|
||||
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -895,6 +895,10 @@ IDLE
|
|||
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.
|
||||
|
||||
- Issue #23606: Adds note to ctypes documentation regarding cdll.msvcrt.
|
||||
|
||||
- Issue #24952: Clarify the default size argument of stack_size() in
|
||||
|
|
|
|||
|
|
@ -149,7 +149,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 */
|
||||
|
|
@ -174,7 +174,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.");
|
||||
|
||||
|
||||
|
|
@ -271,7 +271,7 @@ append_history_file(PyObject *self, PyObject *args)
|
|||
|
||||
PyDoc_STRVAR(doc_append_history_file,
|
||||
"append_history_file(nelements[, filename]) -> None\n\
|
||||
Append the last nelements of the history list to file.\n\
|
||||
Append the last nelements items of the history list to file.\n\
|
||||
The default filename is ~/.history.");
|
||||
#endif
|
||||
|
||||
|
|
@ -290,7 +290,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.");
|
||||
|
||||
|
|
@ -305,7 +305,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.");
|
||||
|
||||
|
||||
|
|
@ -371,7 +371,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.");
|
||||
|
||||
|
|
@ -388,7 +388,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.");
|
||||
|
|
@ -419,7 +419,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 */
|
||||
|
|
@ -433,7 +433,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 */
|
||||
|
|
@ -462,7 +462,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. */
|
||||
|
||||
|
|
@ -502,7 +502,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,
|
||||
|
|
@ -532,7 +532,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;
|
||||
}
|
||||
|
|
@ -573,7 +573,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 */
|
||||
|
|
@ -586,7 +586,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 */
|
||||
|
|
@ -647,7 +647,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) {
|
||||
|
|
@ -739,7 +739,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 */
|
||||
|
|
|
|||
Loading…
Reference in New Issue