Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`readline` --- GNU readline interface |
| 2 | ========================================== |
| 3 | |
| 4 | .. module:: readline |
| 5 | :platform: Unix |
| 6 | :synopsis: GNU readline support for Python. |
Christian Heimes | 895627f | 2007-12-08 17:28:33 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Skip Montanaro <skip@pobox.com> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | |
| 10 | The :mod:`readline` module defines a number of functions to facilitate |
| 11 | completion and reading/writing of history files from the Python interpreter. |
| 12 | This module can be used directly or via the :mod:`rlcompleter` module. Settings |
| 13 | made using this module affect the behaviour of both the interpreter's |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 14 | interactive prompt and the prompts offered by the built-in :func:`input` |
| 15 | function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Ezio Melotti | 6e40e27 | 2010-01-04 09:29:10 +0000 | [diff] [blame] | 17 | .. note:: |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 18 | |
| 19 | On MacOS X the :mod:`readline` module can be implemented using |
| 20 | the ``libedit`` library instead of GNU readline. |
| 21 | |
| 22 | The configuration file for ``libedit`` is different from that |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 23 | of GNU readline. If you programmatically load configuration strings |
Ronald Oussoren | 2efd924 | 2009-09-20 14:53:22 +0000 | [diff] [blame] | 24 | you can check for the text "libedit" in :const:`readline.__doc__` |
| 25 | to differentiate between GNU readline and libedit. |
| 26 | |
| 27 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | The :mod:`readline` module defines the following functions: |
| 29 | |
| 30 | |
| 31 | .. function:: parse_and_bind(string) |
| 32 | |
| 33 | Parse and execute single line of a readline init file. |
| 34 | |
| 35 | |
| 36 | .. function:: get_line_buffer() |
| 37 | |
| 38 | Return the current contents of the line buffer. |
| 39 | |
| 40 | |
| 41 | .. function:: insert_text(string) |
| 42 | |
| 43 | Insert text into the command line. |
| 44 | |
| 45 | |
| 46 | .. function:: read_init_file([filename]) |
| 47 | |
| 48 | Parse a readline initialization file. The default filename is the last filename |
| 49 | used. |
| 50 | |
| 51 | |
| 52 | .. function:: read_history_file([filename]) |
| 53 | |
| 54 | Load a readline history file. The default filename is :file:`~/.history`. |
| 55 | |
| 56 | |
| 57 | .. function:: write_history_file([filename]) |
| 58 | |
| 59 | Save a readline history file. The default filename is :file:`~/.history`. |
| 60 | |
| 61 | |
| 62 | .. function:: clear_history() |
| 63 | |
| 64 | Clear the current history. (Note: this function is not available if the |
| 65 | installed version of GNU readline doesn't support it.) |
| 66 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
| 68 | .. function:: get_history_length() |
| 69 | |
| 70 | Return the desired length of the history file. Negative values imply unlimited |
| 71 | history file size. |
| 72 | |
| 73 | |
| 74 | .. function:: set_history_length(length) |
| 75 | |
| 76 | Set the number of lines to save in the history file. :func:`write_history_file` |
| 77 | uses this value to truncate the history file when saving. Negative values imply |
| 78 | unlimited history file size. |
| 79 | |
| 80 | |
| 81 | .. function:: get_current_history_length() |
| 82 | |
| 83 | Return the number of lines currently in the history. (This is different from |
| 84 | :func:`get_history_length`, which returns the maximum number of lines that will |
| 85 | be written to a history file.) |
| 86 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
| 88 | .. function:: get_history_item(index) |
| 89 | |
| 90 | Return the current contents of history item at *index*. |
| 91 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | .. function:: remove_history_item(pos) |
| 94 | |
| 95 | Remove history item specified by its position from the history. |
| 96 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | |
| 98 | .. function:: replace_history_item(pos, line) |
| 99 | |
| 100 | Replace history item specified by its position with the given line. |
| 101 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | .. function:: redisplay() |
| 104 | |
| 105 | Change what's displayed on the screen to reflect the current contents of the |
| 106 | line buffer. |
| 107 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
| 109 | .. function:: set_startup_hook([function]) |
| 110 | |
| 111 | Set or remove the startup_hook function. If *function* is specified, it will be |
| 112 | used as the new startup_hook function; if omitted or ``None``, any hook function |
| 113 | already installed is removed. The startup_hook function is called with no |
| 114 | arguments just before readline prints the first prompt. |
| 115 | |
| 116 | |
| 117 | .. function:: set_pre_input_hook([function]) |
| 118 | |
| 119 | Set or remove the pre_input_hook function. If *function* is specified, it will |
| 120 | be used as the new pre_input_hook function; if omitted or ``None``, any hook |
| 121 | function already installed is removed. The pre_input_hook function is called |
| 122 | with no arguments after the first prompt has been printed and just before |
| 123 | readline starts reading input characters. |
| 124 | |
| 125 | |
| 126 | .. function:: set_completer([function]) |
| 127 | |
| 128 | Set or remove the completer function. If *function* is specified, it will be |
| 129 | used as the new completer function; if omitted or ``None``, any completer |
| 130 | function already installed is removed. The completer function is called as |
| 131 | ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it |
| 132 | returns a non-string value. It should return the next possible completion |
| 133 | starting with *text*. |
| 134 | |
| 135 | |
| 136 | .. function:: get_completer() |
| 137 | |
| 138 | Get the completer function, or ``None`` if no completer function has been set. |
| 139 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 141 | .. function:: get_completion_type() |
| 142 | |
| 143 | Get the type of completion being attempted. |
| 144 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 145 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | .. function:: get_begidx() |
| 147 | |
| 148 | Get the beginning index of the readline tab-completion scope. |
| 149 | |
| 150 | |
| 151 | .. function:: get_endidx() |
| 152 | |
| 153 | Get the ending index of the readline tab-completion scope. |
| 154 | |
| 155 | |
| 156 | .. function:: set_completer_delims(string) |
| 157 | |
| 158 | Set the readline word delimiters for tab-completion. |
| 159 | |
| 160 | |
| 161 | .. function:: get_completer_delims() |
| 162 | |
| 163 | Get the readline word delimiters for tab-completion. |
| 164 | |
Georg Brandl | 6554cb9 | 2007-12-02 23:15:43 +0000 | [diff] [blame] | 165 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 166 | .. function:: set_completion_display_matches_hook([function]) |
| 167 | |
| 168 | Set or remove the completion display function. If *function* is |
| 169 | specified, it will be used as the new completion display function; |
| 170 | if omitted or ``None``, any completion display function already |
| 171 | installed is removed. The completion display function is called as |
| 172 | ``function(substitution, [matches], longest_match_length)`` once |
| 173 | each time matches need to be displayed. |
| 174 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | |
| 176 | .. function:: add_history(line) |
| 177 | |
| 178 | Append a line to the history buffer, as if it was the last line typed. |
| 179 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | .. seealso:: |
| 181 | |
| 182 | Module :mod:`rlcompleter` |
| 183 | Completion of Python identifiers at the interactive prompt. |
| 184 | |
| 185 | |
| 186 | .. _readline-example: |
| 187 | |
| 188 | Example |
| 189 | ------- |
| 190 | |
| 191 | The following example demonstrates how to use the :mod:`readline` module's |
| 192 | history reading and writing functions to automatically load and save a history |
| 193 | file named :file:`.pyhist` from the user's home directory. The code below would |
| 194 | normally be executed automatically during interactive sessions from the user's |
| 195 | :envvar:`PYTHONSTARTUP` file. :: |
| 196 | |
| 197 | import os |
Georg Brandl | a102ae3 | 2010-10-06 05:08:32 +0000 | [diff] [blame] | 198 | import readline |
Éric Araujo | 4dcf502 | 2011-03-25 20:31:50 +0100 | [diff] [blame] | 199 | histfile = os.path.join(os.path.expanduser("~"), ".pyhist") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | try: |
| 201 | readline.read_history_file(histfile) |
| 202 | except IOError: |
| 203 | pass |
| 204 | import atexit |
| 205 | atexit.register(readline.write_history_file, histfile) |
| 206 | del os, histfile |
| 207 | |
| 208 | The following example extends the :class:`code.InteractiveConsole` class to |
| 209 | support history save/restore. :: |
| 210 | |
| 211 | import code |
| 212 | import readline |
| 213 | import atexit |
| 214 | import os |
| 215 | |
| 216 | class HistoryConsole(code.InteractiveConsole): |
| 217 | def __init__(self, locals=None, filename="<console>", |
| 218 | histfile=os.path.expanduser("~/.console-history")): |
Georg Brandl | ee8783d | 2009-09-16 16:00:31 +0000 | [diff] [blame] | 219 | code.InteractiveConsole.__init__(self, locals, filename) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | self.init_history(histfile) |
| 221 | |
| 222 | def init_history(self, histfile): |
| 223 | readline.parse_and_bind("tab: complete") |
| 224 | if hasattr(readline, "read_history_file"): |
| 225 | try: |
| 226 | readline.read_history_file(histfile) |
| 227 | except IOError: |
| 228 | pass |
| 229 | atexit.register(self.save_history, histfile) |
| 230 | |
| 231 | def save_history(self, histfile): |
| 232 | readline.write_history_file(histfile) |
| 233 | |