Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`rlcompleter` --- Completion function for GNU readline |
| 3 | =========================================================== |
| 4 | |
| 5 | .. module:: rlcompleter |
| 6 | :synopsis: Python identifier completion, suitable for the GNU readline library. |
| 7 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 8 | |
| 9 | |
| 10 | The :mod:`rlcompleter` module defines a completion function suitable for the |
| 11 | :mod:`readline` module by completing valid Python identifiers and keywords. |
| 12 | |
| 13 | When this module is imported on a Unix platform with the :mod:`readline` module |
| 14 | available, an instance of the :class:`Completer` class is automatically created |
| 15 | and its :meth:`complete` method is set as the :mod:`readline` completer. |
| 16 | |
| 17 | Example:: |
| 18 | |
| 19 | >>> import rlcompleter |
| 20 | >>> import readline |
| 21 | >>> readline.parse_and_bind("tab: complete") |
| 22 | >>> readline. <TAB PRESSED> |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 23 | readline.__doc__ readline.get_line_buffer( readline.read_init_file( |
| 24 | readline.__file__ readline.insert_text( readline.set_completer( |
| 25 | readline.__name__ readline.parse_and_bind( |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | >>> readline. |
| 27 | |
| 28 | The :mod:`rlcompleter` module is designed for use with Python's interactive |
| 29 | mode. A user can add the following lines to his or her initialization file |
| 30 | (identified by the :envvar:`PYTHONSTARTUP` environment variable) to get |
| 31 | automatic :kbd:`Tab` completion:: |
| 32 | |
| 33 | try: |
| 34 | import readline |
| 35 | except ImportError: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 36 | print("Module readline not available.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | else: |
| 38 | import rlcompleter |
| 39 | readline.parse_and_bind("tab: complete") |
| 40 | |
| 41 | On platforms without :mod:`readline`, the :class:`Completer` class defined by |
| 42 | this module can still be used for custom purposes. |
| 43 | |
| 44 | |
| 45 | .. _completer-objects: |
| 46 | |
| 47 | Completer Objects |
| 48 | ----------------- |
| 49 | |
| 50 | Completer objects have the following method: |
| 51 | |
| 52 | |
| 53 | .. method:: Completer.complete(text, state) |
| 54 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 55 | Return the *state*\ th completion for *text*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | If called for *text* that doesn't include a period character (``'.'``), it will |
Georg Brandl | 1a3284e | 2007-12-02 09:40:06 +0000 | [diff] [blame] | 58 | complete from names currently defined in :mod:`__main__`, :mod:`builtins` and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | keywords (as defined by the :mod:`keyword` module). |
| 60 | |
| 61 | If called for a dotted name, it will try to evaluate anything without obvious |
| 62 | side-effects (functions will not be evaluated, but it can generate calls to |
| 63 | :meth:`__getattr__`) up to the last part, and find matches for the rest via the |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 64 | :func:`dir` function. Any exception raised during the evaluation of the |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 65 | expression is caught, silenced and :const:`None` is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | |