Skip to content

Commit

Permalink
Move text walls out of source code and into docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@stefanholek
stefanholek committed Oct 27, 2022
1 parent 0b29823 commit 495ad7a
Show file tree
Hide file tree
Showing 4 changed files with 254 additions and 142 deletions.
107 changes: 107 additions & 0 deletions docs/overview.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,110 @@ Overview

.. automodule:: rl

Package Contents
================

rl exports the following components:

:obj:`rl.completer <rl.Completer>`
Interface to the readline completer. Used to configure the completion
aspects of readline.

:obj:`rl.completion <rl.Completion>`
Interface to the active readline completion. Used to interact
with readline when a completion is in progress.

:obj:`rl.history <rl.History>`
Interface to the readline history. Used to read and write history files
and to manipulate history entries.

:mod:`rl.readline`
The readline bindings module. Contains everything known from the standard
library plus extensions specific to the rl package. The :obj:`completer <rl.Completer>`,
:obj:`completion <rl.Completion>`, and :obj:`history <rl.History>`
interfaces make use of this module, and you should rarely need to interact
with it directly.

:func:`rl.generator`
A decorator turning any callable into a *completion entry function* that
can be handed to readline.

:func:`rl.print_exc`
A decorator printing exceptions to stderr. Useful when writing Python
completions and hooks, as exceptions occurring there are usually
swallowed by the in-between C code.

Readline Completion
===================

Completion is the process initiated when the user presses the TAB key.
It has three phases: Word breaking, match generation, and
match insertion/display.

For each phase, readline provides configuration settings and hooks that
allow applications to control the way the library behaves. See the
:class:`completer <rl.Completer>` and :class:`completion <rl.Completion>`
objects for detailed descriptions of available properties.

.. _call-graph:

Call Graph
----------

A calling sequence for filename completion may look like this:

* :func:`complete_internal`

* :func:`find_completion_word`

* :attr:`~rl.Completer.word_break_hook`

* :attr:`~rl.Completer.char_is_quoted_function`

* :func:`gen_completion_matches`

* :attr:`~rl.Completer.completer`

* :meth:`~rl.Completion.complete_filename`

* :attr:`~rl.Completer.directory_rewrite_hook` or

* :attr:`~rl.Completer.directory_completion_hook`

* :attr:`~rl.Completer.filename_dequoting_function`

* :attr:`~rl.Completer.filename_rewrite_hook`

* :attr:`~rl.Completer.ignore_some_completions_function`

* :func:`insert_match`

* :attr:`~rl.Completer.filename_quoting_function`

* :attr:`~rl.Completer.filename_stat_hook`

* :func:`display_matches`

* :attr:`~rl.Completer.display_matches_hook`

* :meth:`~rl.Completion.display_match_list`

* :attr:`~rl.Completer.directory_completion_hook` or

* :attr:`~rl.Completer.filename_stat_hook`

Readline History
================

History allows readline to save and later recall lines the user has entered.
The :obj:`history <rl.History>` object provides a list-like interface to the
history buffer as well as functions to persist the history between sessions.

Upstream Documentation
======================

The `GNU Readline Library`_ and the `GNU History Library`_.

.. _`GNU Readline Library`: https://tiswww.case.edu/php/chet/readline/readline.html
.. _`GNU History Library`: https://tiswww.case.edu/php/chet/readline/history.html

146 changes: 145 additions & 1 deletion docs/readline.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,149 @@ Readline Bindings
=================

.. automodule:: rl.readline
:members:

Readline Interface
===================

The :mod:`rl.readline` module is an API-compatible replacement for the standard
library's :mod:`readline <py3k:readline>` bindings.
The standard library documentation applies, with the following exceptions:

#. :func:`get_completion_type` returns a string.
#. :func:`get_completion_append_character` defaults to the space character.
#. :func:`get_history_item` is zero-based.
#. :func:`redisplay` accepts an optional ``force`` argument.

Beyond that, :mod:`rl.readline` adds a plethora of new functionality which is
typically accessed through the high-level interfaces :obj:`rl.completer <rl.Completer>`,
:obj:`rl.completion <rl.Completion>`, and :obj:`rl.history <rl.History>`.
Functions not exposed through a high-level interface:

- :func:`readline_version` returns the readline library version as an integer.
- :func:`read_key` reads a character from the keyboard.
- :func:`stuff_char` stuffs a character into the input stream.
- :func:`complete_internal` executes the completer. Used in tests.

.. note:: It is possible to use ``rl.readline`` without the high-level APIs.
To switch an existing application to ``rl``, change occurrences of
``import readline`` to ``from rl import readline``.

.. note:: Applications must not use the standard library ``readline`` and
``rl.readline`` simultaneously. This is because only one module can own the
``PyOS_ReadlineFunctionPointer``.

Functions
===================

.. autofunction:: rl.readline.add_history
.. autofunction:: rl.readline.append_history_file
.. autofunction:: rl.readline.clear_history
.. autofunction:: rl.readline.complete_internal
.. autofunction:: rl.readline.display_match_list
.. autofunction:: rl.readline.filename_completion_function

.. autofunction:: rl.readline.get_auto_history
.. autofunction:: rl.readline.get_begidx
.. autofunction:: rl.readline.get_char_is_quoted_function

.. autofunction:: rl.readline.get_completer
.. autofunction:: rl.readline.get_completer_delims
.. autofunction:: rl.readline.get_completer_quote_characters

.. autofunction:: rl.readline.get_completion_append_character
.. autofunction:: rl.readline.get_completion_display_matches_hook
.. autofunction:: rl.readline.get_completion_found_quote
.. autofunction:: rl.readline.get_completion_query_items
.. autofunction:: rl.readline.get_completion_quote_character
.. autofunction:: rl.readline.get_completion_suppress_append
.. autofunction:: rl.readline.get_completion_suppress_quote
.. autofunction:: rl.readline.get_completion_type
.. autofunction:: rl.readline.get_completion_word_break_hook

.. autofunction:: rl.readline.get_current_history_length
.. autofunction:: rl.readline.get_directory_completion_hook
.. autofunction:: rl.readline.get_directory_rewrite_hook
.. autofunction:: rl.readline.get_endidx

.. autofunction:: rl.readline.get_filename_completion_desired
.. autofunction:: rl.readline.get_filename_dequoting_function
.. autofunction:: rl.readline.get_filename_quote_characters
.. autofunction:: rl.readline.get_filename_quoting_desired
.. autofunction:: rl.readline.get_filename_quoting_function
.. autofunction:: rl.readline.get_filename_rewrite_hook
.. autofunction:: rl.readline.get_filename_stat_hook

.. autofunction:: rl.readline.get_history_item
.. autofunction:: rl.readline.get_history_iter
.. autofunction:: rl.readline.get_history_length
.. autofunction:: rl.readline.get_history_list
.. autofunction:: rl.readline.get_history_max_entries
.. autofunction:: rl.readline.get_history_reverse_iter

.. autofunction:: rl.readline.get_ignore_some_completions_function
.. autofunction:: rl.readline.get_inhibit_completion
.. autofunction:: rl.readline.get_line_buffer
.. autofunction:: rl.readline.get_pre_input_hook
.. autofunction:: rl.readline.get_rl_end
.. autofunction:: rl.readline.get_rl_point
.. autofunction:: rl.readline.get_special_prefixes
.. autofunction:: rl.readline.get_startup_hook

.. autofunction:: rl.readline.history_is_stifled
.. autofunction:: rl.readline.insert_text
.. autofunction:: rl.readline.parse_and_bind
.. autofunction:: rl.readline.read_history_file
.. autofunction:: rl.readline.read_init_file
.. autofunction:: rl.readline.read_key
.. autofunction:: rl.readline.readline_version
.. autofunction:: rl.readline.redisplay

.. autofunction:: rl.readline.remove_history_item
.. autofunction:: rl.readline.replace_history_item
.. autofunction:: rl.readline.replace_line

.. autofunction:: rl.readline.set_auto_history
.. autofunction:: rl.readline.set_begidx
.. autofunction:: rl.readline.set_char_is_quoted_function

.. autofunction:: rl.readline.set_completer
.. autofunction:: rl.readline.set_completer_delims
.. autofunction:: rl.readline.set_completer_quote_characters

.. autofunction:: rl.readline.set_completion_append_character
.. autofunction:: rl.readline.set_completion_display_matches_hook
.. autofunction:: rl.readline.set_completion_found_quote
.. autofunction:: rl.readline.set_completion_query_items
.. autofunction:: rl.readline.set_completion_quote_character
.. autofunction:: rl.readline.set_completion_suppress_append
.. autofunction:: rl.readline.set_completion_suppress_quote
.. autofunction:: rl.readline.set_completion_type
.. autofunction:: rl.readline.set_completion_word_break_hook

.. autofunction:: rl.readline.set_directory_completion_hook
.. autofunction:: rl.readline.set_directory_rewrite_hook
.. autofunction:: rl.readline.set_endidx

.. autofunction:: rl.readline.set_filename_completion_desired
.. autofunction:: rl.readline.set_filename_dequoting_function
.. autofunction:: rl.readline.set_filename_quote_characters
.. autofunction:: rl.readline.set_filename_quoting_desired
.. autofunction:: rl.readline.set_filename_quoting_function
.. autofunction:: rl.readline.set_filename_rewrite_hook
.. autofunction:: rl.readline.set_filename_stat_hook

.. autofunction:: rl.readline.set_history_length

.. autofunction:: rl.readline.set_ignore_some_completions_function
.. autofunction:: rl.readline.set_inhibit_completion
.. autofunction:: rl.readline.set_pre_input_hook
.. autofunction:: rl.readline.set_special_prefixes
.. autofunction:: rl.readline.set_startup_hook

.. autofunction:: rl.readline.stifle_history
.. autofunction:: rl.readline.stuff_char
.. autofunction:: rl.readline.tilde_expand
.. autofunction:: rl.readline.unstifle_history
.. autofunction:: rl.readline.username_completion_function
.. autofunction:: rl.readline.write_history_file

110 changes: 1 addition & 109 deletions rl/__init__.py
View file
Original file line number Diff line number Diff line change
@@ -1,112 +1,4 @@
"""Alternative Python bindings for GNU Readline.
Package Contents
================
rl exports the following components:
:obj:`rl.completer <rl.Completer>`
Interface to the readline completer. Used to configure the completion
aspects of readline.
:obj:`rl.completion <rl.Completion>`
Interface to the active readline completion. Used to interact
with readline when a completion is in progress.
:obj:`rl.history <rl.History>`
Interface to the readline history. Used to read and write history files
and to manipulate history entries.
:mod:`rl.readline`
The readline bindings module. Contains everything known from the standard
library plus extensions specific to the rl package. The :obj:`completer <rl.Completer>`,
:obj:`completion <rl.Completion>`, and :obj:`history <rl.History>`
interfaces make use of this module, and you should rarely need to interact
with it directly.
:func:`rl.generator`
A decorator turning any callable into a *completion entry function* that
can be handed to readline.
:func:`rl.print_exc`
A decorator printing exceptions to stderr. Useful when writing Python
completions and hooks, as exceptions occurring there are usually
swallowed by the in-between C code.
Readline Completion
===================
Completion is the process initiated when the user presses the TAB key.
It has three phases: Word breaking, match generation, and
match insertion/display.
For each phase, readline provides configuration settings and hooks that
allow applications to control the way the library behaves. See the
:class:`completer <rl.Completer>` and :class:`completion <rl.Completion>`
objects for detailed descriptions of available properties.
.. _call-graph:
Call Graph
----------
A calling sequence for filename completion may look like this:
* :func:`complete_internal`
* :func:`find_completion_word`
* :attr:`~rl.Completer.word_break_hook`
* :attr:`~rl.Completer.char_is_quoted_function`
* :func:`gen_completion_matches`
* :attr:`~rl.Completer.completer`
* :meth:`~rl.Completion.complete_filename`
* :attr:`~rl.Completer.directory_rewrite_hook` or
* :attr:`~rl.Completer.directory_completion_hook`
* :attr:`~rl.Completer.filename_dequoting_function`
* :attr:`~rl.Completer.filename_rewrite_hook`
* :attr:`~rl.Completer.ignore_some_completions_function`
* :func:`insert_match`
* :attr:`~rl.Completer.filename_quoting_function`
* :attr:`~rl.Completer.filename_stat_hook`
* :func:`display_matches`
* :attr:`~rl.Completer.display_matches_hook`
* :meth:`~rl.Completion.display_match_list`
* :attr:`~rl.Completer.directory_completion_hook` or
* :attr:`~rl.Completer.filename_stat_hook`
Readline History
================
History allows readline to save and later recall lines the user has entered.
The :obj:`history <rl.History>` object provides a list-like interface to the
history buffer as well as functions to persist the history between sessions.
Upstream Documentation
======================
The `GNU Readline Library`_ and the `GNU History Library`_.
.. _`GNU Readline Library`: https://tiswww.case.edu/php/chet/readline/readline.html
.. _`GNU History Library`: https://tiswww.case.edu/php/chet/readline/history.html
"""
"""Alternative Python bindings for GNU Readline."""

# Grab the PyOS_ReadlineFunctionPointer
from rl import _init
Expand Down
Loading

0 comments on commit 495ad7a

Please sign in to comment.