← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/readline.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/readline.rst
 
1
 
 
2
:mod:`readline` --- GNU readline interface
 
3
==========================================
 
4
 
 
5
.. module:: readline
 
6
   :platform: Unix
 
7
   :synopsis: GNU readline support for Python.
 
8
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
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
 
15
interactive prompt  and the prompts offered by the built-in :func:`input`
 
16
function.
 
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
 
 
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
 
 
77
 
 
78
.. function:: get_history_item(index)
 
79
 
 
80
   Return the current contents of history item at *index*.
 
81
 
 
82
 
 
83
.. function:: remove_history_item(pos)
 
84
 
 
85
   Remove history item specified by its position from the history.
 
86
 
 
87
 
 
88
.. function:: replace_history_item(pos, line)
 
89
 
 
90
   Replace history item specified by its position with the given line.
 
91
 
 
92
 
 
93
.. function:: redisplay()
 
94
 
 
95
   Change what's displayed on the screen to reflect the current contents of the
 
96
   line buffer.
 
97
 
 
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
 
 
130
 
 
131
.. function:: get_completion_type()
 
132
 
 
133
   Get the type of completion being attempted.
 
134
 
 
135
 
 
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
 
 
155
 
 
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
 
 
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")):
 
209
           code.InteractiveConsole.__init__(self)
 
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