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