Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 1 | \section{\module{readline} --- |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 2 | GNU readline interface} |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 3 | |
| 4 | \declaremodule{builtin}{readline} |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 5 | \platform{Unix} |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 6 | \sectionauthor{Skip Montanaro}{skip@mojam.com} |
Fred Drake | f8ca7d8 | 2000-10-10 17:03:45 +0000 | [diff] [blame] | 7 | \modulesynopsis{GNU readline support for Python.} |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 8 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 9 | |
| 10 | The \module{readline} module defines a number of functions used either |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 11 | directly or from the \refmodule{rlcompleter} module to facilitate |
| 12 | completion and history file read and write from the Python |
| 13 | interpreter. |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 14 | |
| 15 | The \module{readline} module defines the following functions: |
| 16 | |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 17 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 18 | \begin{funcdesc}{parse_and_bind}{string} |
| 19 | Parse and execute single line of a readline init file. |
| 20 | \end{funcdesc} |
| 21 | |
| 22 | \begin{funcdesc}{get_line_buffer}{} |
| 23 | Return the current contents of the line buffer. |
| 24 | \end{funcdesc} |
| 25 | |
| 26 | \begin{funcdesc}{insert_text}{string} |
| 27 | Insert text into the command line. |
| 28 | \end{funcdesc} |
| 29 | |
| 30 | \begin{funcdesc}{read_init_file}{\optional{filename}} |
| 31 | Parse a readline initialization file. |
| 32 | The default filename is the last filename used. |
| 33 | \end{funcdesc} |
| 34 | |
| 35 | \begin{funcdesc}{read_history_file}{\optional{filename}} |
| 36 | Load a readline history file. |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 37 | The default filename is \file{\~{}/.history}. |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 38 | \end{funcdesc} |
| 39 | |
| 40 | \begin{funcdesc}{write_history_file}{\optional{filename}} |
| 41 | Save a readline history file. |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 42 | The default filename is \file{\~{}/.history}. |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 43 | \end{funcdesc} |
| 44 | |
Martin v. Löwis | e7a9796 | 2003-09-20 16:08:33 +0000 | [diff] [blame] | 45 | \begin{funcdesc}{clear_history}{} |
| 46 | Clear the current history. (Note: this function is not available if |
| 47 | the installed version of GNU readline doesn't support it.) |
| 48 | \versionadded{2.4} |
| 49 | \end{funcdesc} |
| 50 | |
Skip Montanaro | 7cb1524 | 2000-07-19 16:56:26 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{get_history_length}{} |
| 52 | Return the desired length of the history file. Negative values imply |
| 53 | unlimited history file size. |
| 54 | \end{funcdesc} |
| 55 | |
| 56 | \begin{funcdesc}{set_history_length}{length} |
| 57 | Set the number of lines to save in the history file. |
Fred Drake | 3fe9a98 | 2000-08-09 14:37:05 +0000 | [diff] [blame] | 58 | \function{write_history_file()} uses this value to truncate the |
| 59 | history file when saving. Negative values imply unlimited history |
| 60 | file size. |
Skip Montanaro | 7cb1524 | 2000-07-19 16:56:26 +0000 | [diff] [blame] | 61 | \end{funcdesc} |
| 62 | |
Phillip J. Eby | 5068c87 | 2004-05-04 19:20:22 +0000 | [diff] [blame] | 63 | \begin{funcdesc}{get_current_history_length}{} |
| 64 | Return the number of lines currently in the history. (This is different |
| 65 | from \function{get_history_length()}, which returns the maximum number of |
| 66 | lines that will be written to a history file.) \versionadded{2.3} |
| 67 | \end{funcdesc} |
| 68 | |
| 69 | \begin{funcdesc}{get_history_item}{index} |
| 70 | Return the current contents of history item at \var{index}. |
| 71 | \versionadded{2.3} |
| 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{redisplay}{} |
| 75 | Change what's displayed on the screen to reflect the current contents |
| 76 | of the line buffer. \versionadded{2.3} |
| 77 | \end{funcdesc} |
| 78 | |
Martin v. Löwis | 0daad59 | 2001-09-30 21:09:59 +0000 | [diff] [blame] | 79 | \begin{funcdesc}{set_startup_hook}{\optional{function}} |
| 80 | Set or remove the startup_hook function. If \var{function} is specified, |
| 81 | it will be used as the new startup_hook function; if omitted or |
| 82 | \code{None}, any hook function already installed is removed. The |
| 83 | startup_hook function is called with no arguments just |
| 84 | before readline prints the first prompt. |
| 85 | \end{funcdesc} |
| 86 | |
| 87 | \begin{funcdesc}{set_pre_input_hook}{\optional{function}} |
| 88 | Set or remove the pre_input_hook function. If \var{function} is specified, |
| 89 | it will be used as the new pre_input_hook function; if omitted or |
| 90 | \code{None}, any hook function already installed is removed. The |
| 91 | pre_input_hook function is called with no arguments after the first prompt |
| 92 | has been printed and just before readline starts reading input characters. |
| 93 | \end{funcdesc} |
| 94 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 95 | \begin{funcdesc}{set_completer}{\optional{function}} |
Fred Drake | 905dc55 | 2001-08-01 21:42:45 +0000 | [diff] [blame] | 96 | Set or remove the completer function. If \var{function} is specified, |
| 97 | it will be used as the new completer function; if omitted or |
| 98 | \code{None}, any completer function already installed is removed. The |
| 99 | completer function is called as \code{\var{function}(\var{text}, |
| 100 | \var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ..., |
| 101 | until it returns a non-string value. It should return the next |
| 102 | possible completion starting with \var{text}. |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 103 | \end{funcdesc} |
| 104 | |
Neal Norwitz | b7d1d3c | 2003-02-21 18:57:05 +0000 | [diff] [blame] | 105 | \begin{funcdesc}{get_completer}{} |
Michael W. Hudson | f5dd753 | 2003-02-21 20:11:09 +0000 | [diff] [blame] | 106 | Get the completer function, or \code{None} if no completer function |
| 107 | has been set. \versionadded{2.3} |
Neal Norwitz | b7d1d3c | 2003-02-21 18:57:05 +0000 | [diff] [blame] | 108 | \end{funcdesc} |
| 109 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 110 | \begin{funcdesc}{get_begidx}{} |
| 111 | Get the beginning index of the readline tab-completion scope. |
| 112 | \end{funcdesc} |
| 113 | |
| 114 | \begin{funcdesc}{get_endidx}{} |
| 115 | Get the ending index of the readline tab-completion scope. |
| 116 | \end{funcdesc} |
| 117 | |
| 118 | \begin{funcdesc}{set_completer_delims}{string} |
| 119 | Set the readline word delimiters for tab-completion. |
| 120 | \end{funcdesc} |
| 121 | |
| 122 | \begin{funcdesc}{get_completer_delims}{} |
| 123 | Get the readline word delimiters for tab-completion. |
| 124 | \end{funcdesc} |
| 125 | |
Guido van Rossum | b6c1d52 | 2001-10-19 01:18:43 +0000 | [diff] [blame] | 126 | \begin{funcdesc}{add_history}{line} |
| 127 | Append a line to the history buffer, as if it was the last line typed. |
| 128 | \end{funcdesc} |
| 129 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 130 | |
| 131 | \begin{seealso} |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 132 | \seemodule{rlcompleter}{Completion of Python identifiers at the |
| 133 | interactive prompt.} |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 134 | \end{seealso} |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 135 | |
| 136 | |
| 137 | \subsection{Example \label{readline-example}} |
| 138 | |
| 139 | The following example demonstrates how to use the |
| 140 | \module{readline} module's history reading and writing functions to |
| 141 | automatically load and save a history file named \file{.pyhist} from |
| 142 | the user's home directory. The code below would normally be executed |
| 143 | automatically during interactive sessions from the user's |
| 144 | \envvar{PYTHONSTARTUP} file. |
| 145 | |
| 146 | \begin{verbatim} |
| 147 | import os |
| 148 | histfile = os.path.join(os.environ["HOME"], ".pyhist") |
| 149 | try: |
| 150 | readline.read_history_file(histfile) |
| 151 | except IOError: |
| 152 | pass |
| 153 | import atexit |
| 154 | atexit.register(readline.write_history_file, histfile) |
| 155 | del os, histfile |
| 156 | \end{verbatim} |
Skip Montanaro | 0dc2310 | 2004-05-23 17:46:50 +0000 | [diff] [blame] | 157 | |
Skip Montanaro | b98a8ba | 2004-05-23 19:06:41 +0000 | [diff] [blame] | 158 | The following example extends the \class{code.InteractiveConsole} class to |
Skip Montanaro | 79cddc5 | 2004-05-24 14:20:16 +0000 | [diff] [blame] | 159 | support history save/restore. |
Skip Montanaro | b98a8ba | 2004-05-23 19:06:41 +0000 | [diff] [blame] | 160 | |
| 161 | \begin{verbatim} |
| 162 | import code |
| 163 | import readline |
| 164 | import atexit |
| 165 | import os |
| 166 | |
| 167 | class HistoryConsole(code.InteractiveConsole): |
| 168 | def __init__(self, locals=None, filename="<console>", |
| 169 | histfile=os.path.expanduser("~/.console-history")): |
| 170 | code.InteractiveConsole.__init__(self) |
| 171 | self.init_history(histfile) |
| 172 | |
| 173 | def init_history(self, histfile): |
| 174 | readline.parse_and_bind("tab: complete") |
| 175 | if hasattr(readline, "read_history_file"): |
| 176 | try: |
| 177 | readline.read_history_file(histfile) |
| 178 | except IOError: |
| 179 | pass |
| 180 | atexit.register(self.save_history, histfile) |
| 181 | |
Skip Montanaro | b98a8ba | 2004-05-23 19:06:41 +0000 | [diff] [blame] | 182 | def save_history(self, histfile): |
| 183 | readline.write_history_file(histfile) |
| 184 | \end{verbatim} |