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 | |
Skip Montanaro | 7cb1524 | 2000-07-19 16:56:26 +0000 | [diff] [blame] | 45 | \begin{funcdesc}{get_history_length}{} |
| 46 | Return the desired length of the history file. Negative values imply |
| 47 | unlimited history file size. |
| 48 | \end{funcdesc} |
| 49 | |
| 50 | \begin{funcdesc}{set_history_length}{length} |
| 51 | Set the number of lines to save in the history file. |
Fred Drake | 3fe9a98 | 2000-08-09 14:37:05 +0000 | [diff] [blame] | 52 | \function{write_history_file()} uses this value to truncate the |
| 53 | history file when saving. Negative values imply unlimited history |
| 54 | file size. |
Skip Montanaro | 7cb1524 | 2000-07-19 16:56:26 +0000 | [diff] [blame] | 55 | \end{funcdesc} |
| 56 | |
Martin v. Löwis | 0daad59 | 2001-09-30 21:09:59 +0000 | [diff] [blame] | 57 | \begin{funcdesc}{set_startup_hook}{\optional{function}} |
| 58 | Set or remove the startup_hook function. If \var{function} is specified, |
| 59 | it will be used as the new startup_hook function; if omitted or |
| 60 | \code{None}, any hook function already installed is removed. The |
| 61 | startup_hook function is called with no arguments just |
| 62 | before readline prints the first prompt. |
| 63 | \end{funcdesc} |
| 64 | |
| 65 | \begin{funcdesc}{set_pre_input_hook}{\optional{function}} |
| 66 | Set or remove the pre_input_hook function. If \var{function} is specified, |
| 67 | it will be used as the new pre_input_hook function; if omitted or |
| 68 | \code{None}, any hook function already installed is removed. The |
| 69 | pre_input_hook function is called with no arguments after the first prompt |
| 70 | has been printed and just before readline starts reading input characters. |
| 71 | \end{funcdesc} |
| 72 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 73 | \begin{funcdesc}{set_completer}{\optional{function}} |
Fred Drake | 905dc55 | 2001-08-01 21:42:45 +0000 | [diff] [blame] | 74 | Set or remove the completer function. If \var{function} is specified, |
| 75 | it will be used as the new completer function; if omitted or |
| 76 | \code{None}, any completer function already installed is removed. The |
| 77 | completer function is called as \code{\var{function}(\var{text}, |
| 78 | \var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ..., |
| 79 | until it returns a non-string value. It should return the next |
| 80 | possible completion starting with \var{text}. |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 81 | \end{funcdesc} |
| 82 | |
Neal Norwitz | b7d1d3c | 2003-02-21 18:57:05 +0000 | [diff] [blame] | 83 | \begin{funcdesc}{get_completer}{} |
Michael W. Hudson | f5dd753 | 2003-02-21 20:11:09 +0000 | [diff] [blame] | 84 | Get the completer function, or \code{None} if no completer function |
| 85 | has been set. \versionadded{2.3} |
Neal Norwitz | b7d1d3c | 2003-02-21 18:57:05 +0000 | [diff] [blame] | 86 | \end{funcdesc} |
| 87 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 88 | \begin{funcdesc}{get_begidx}{} |
| 89 | Get the beginning index of the readline tab-completion scope. |
| 90 | \end{funcdesc} |
| 91 | |
| 92 | \begin{funcdesc}{get_endidx}{} |
| 93 | Get the ending index of the readline tab-completion scope. |
| 94 | \end{funcdesc} |
| 95 | |
| 96 | \begin{funcdesc}{set_completer_delims}{string} |
| 97 | Set the readline word delimiters for tab-completion. |
| 98 | \end{funcdesc} |
| 99 | |
| 100 | \begin{funcdesc}{get_completer_delims}{} |
| 101 | Get the readline word delimiters for tab-completion. |
| 102 | \end{funcdesc} |
| 103 | |
Guido van Rossum | b6c1d52 | 2001-10-19 01:18:43 +0000 | [diff] [blame] | 104 | \begin{funcdesc}{add_history}{line} |
| 105 | Append a line to the history buffer, as if it was the last line typed. |
| 106 | \end{funcdesc} |
| 107 | |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 108 | |
| 109 | \begin{seealso} |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 110 | \seemodule{rlcompleter}{Completion of Python identifiers at the |
| 111 | interactive prompt.} |
Skip Montanaro | 510ca1d | 2000-07-06 03:25:26 +0000 | [diff] [blame] | 112 | \end{seealso} |
Fred Drake | 3c62d9e | 2000-07-06 04:51:04 +0000 | [diff] [blame] | 113 | |
| 114 | |
| 115 | \subsection{Example \label{readline-example}} |
| 116 | |
| 117 | The following example demonstrates how to use the |
| 118 | \module{readline} module's history reading and writing functions to |
| 119 | automatically load and save a history file named \file{.pyhist} from |
| 120 | the user's home directory. The code below would normally be executed |
| 121 | automatically during interactive sessions from the user's |
| 122 | \envvar{PYTHONSTARTUP} file. |
| 123 | |
| 124 | \begin{verbatim} |
| 125 | import os |
| 126 | histfile = os.path.join(os.environ["HOME"], ".pyhist") |
| 127 | try: |
| 128 | readline.read_history_file(histfile) |
| 129 | except IOError: |
| 130 | pass |
| 131 | import atexit |
| 132 | atexit.register(readline.write_history_file, histfile) |
| 133 | del os, histfile |
| 134 | \end{verbatim} |