1tclreadline(n) tclreadline(n)
2
6 tclreadline - gnu readline for the tcl scripting language
7
10 ::tclreadline::readline command [options]
11
15 The tclreadline package makes the gnu readline available to the script‐
16 ing language tcl. The primary purpose of the package is to facilitate
17 the interactive script development by the means of word and file name
18 completion as well as history expansion (well known from shells like
19 bash).
20 Additionally tclreadline can also be used for tcl scripts which want to
22 use a shell like input interface. In this case the ::tclreadline::read‐
23 line read command has to be called explicitly.
24 The advantage of tclreadline is that it uses the callback handler mech‐
27 anism of the gnu readline while it processes tcl events. This way X
28 events from a wish gui will processed as well as events from the
29 tclreadline line interface.
30 tclreadline is basically a shared library and a few tcl scripts which
33 are accessed with the tcl package require command. Therefore tclread‐
34 line should work with all common extensions like blt, itcl, itk, tix
35 ....
36
42 If you want to use tclreadline as a line interface for developing tcl
43 scripts, you probably don't have to read this section. In this case the
44 only thing you should do is to modify your .tclshrc according to the
45 section FILES.
46 For the functionality of the GNU readline you should refer to the read‐
48 line's documentation.
49 The following list will give all commands, which are currently imple‐
52 mented in the shared lib (e.g. libtclreadline-2.1.0.so). Additional
53 commands were introduced in a startup script tclreadlineSetup.tcl,
54 which lives in the tclreadline installation directory. (typically
55 something like /usr/local/lib/tclreadline ..) These commands are pri‐
56 marily for internal use and not documented here.
57 Note that all commands reside in the namespace ::tclreadline::.
59 ::tclreadline::readline add string
63 adds a string to the completer. If the string contains white spa‐
64 ces, each of the words will be completed consecutively when hit‐
65 ting <Tab>. Example:
66 ::tclreadline::readline add "button pathName ?options?"
68 typing but<Tab> will complete to button. Hitting <Tab> again will
70 complete to "button pathName". ...
71 ::tclreadline::readline complete string
74 returns 1 if string is a complete tcl command and 0 otherwise.
75 ::tclreadline::readline customcompleter [string]
78 Register the proc string as custom completer. This proc is called
79 with exactly four arguments each time completion takes place: the
80 word to complete ("text"), the "start" and "end" positions of this
81 word in the line entered so far, and this line ("line"). The cus‐
82 tom completion script should return an array of strings which is a
83 list of completions for "text". If there are no completions, it
84 should return an empty string "". The first entry in the returned
85 list is the substitution for "text". The remaining entries are the
86 possible completions. If the custom completion script returns an
87 empty string and builtin completion is enabled (see tclread‐
88 line::readline builtincompleter), the builtin completer is called.
89 tclreadline::readline customcompleter simply returns the current
90 custom completer if called w/o string. To turn of custom comple‐
91 tion, call tclreadline::readline customcompleter with an empty
92 string.
93 Example: % puts $b<TAB> will call the custom completer with the
95 four arguments "$b", "5", "8" and "puts $b". The custom completer
96 could return a string like "$bl $black $blue", which will complete
97 "$b" to "$bl" (the longest match) and offer a list of two further
98 matches "$black" and "$blue".
99 For further reference, see the proc tclreadline::ScriptCompleter
101 in the file tclreadlineSetup.tcl.
102 ::tclreadline::readline builtincompleter [bool]
105 enable or disable the builtin completer. If the builtin completer
106 is enabled, it will be invoked either if there is no custom com‐
107 pleter, or the custom completer returned an empty string. The
108 builtin completer is on by default. tclreadline::readline built‐
109 incompleter returns the current custom completer (also, if called
110 w/o the bool argument).
111 ::tclreadline::readline eofchar [script]
114 set a script which will be called, if readline returns the eof
115 character (this is typically the case if CTRL-D is entered at the
116 very beginning of the line). The default for this script is "puts
117 {}; exit". Setting this to an empty value disables any action on
118 eof. tclreadline::readline eof returns the current eof script.
119 ::tclreadline::readline initialize historyfile
122 initialize the tclreadline interface and read the history from the
123 historyfile. On success an empty string is returned. This command
124 has to be called before any other tclreadline commands.
125 ::tclreadline::readline read prompt
128 prints the prompt to stdout and enters the tclreadline event loop.
129 Both readline and X events are processed. Returns the (eventually
130 history-expanded) input string. tclreadline::readline read rises
131 an error, if an error occurs while evaluating a script completer.
132 ::tclreadline::readline write historyfile
135 writes the history to the historyfile. This command is called
136 automatically from the internal routine ::tclreadline::Exit. If
137 the variable tclreadline::historyLength is non-negative, the his‐
138 toryfile will be truncated to hold only this number lines.
139 ::tclreadline::readline reset-terminal [terminalName]
142 w/o argument: reset the state of the terminal to what it was
143 before tclreadline was used. With argument: reinitialize read‐
144 line's idea of the terminal settings using terminalName as the
145 terminal type. The form w/o argument might not work if tclread‐
146 line was compiled with an older version of libreadline.
147 ::tclreadline::readline bell
150 Ring the terminal bell, obeying the setting of bell-style -- audi‐
151 ble or visible.
152 ::tclreadline::text
155 Return the current input.
156 ::tclreadline::readline update
159 Redraw the current input line.
160 ::tclreadline::Print [yes / no]
163 turns on or off the default behavior of tclsh to print the result
164 of every command. This is turned on by default, so it will just
165 behave as the tclsh w/o tclreadline. Turning off might be useful,
166 when reading binary data for example. If ::tclreadline::Print is
167 called w/o arguments, it returns the current setting.
168 ::tclreadline::Loop [historyfile]
171 enter the tclreadline main loop. This command is typically called
172 from the startup resource file (something .tclshrc, depending on
173 the interpreter you use, see the file `sample.tclshrc'). The main
174 loop sets up some completion characteristics as variable -- try
175 something like "puts $b<TAB>" -- and command completion -- try
176 "puts [in<TAB>". If the optional argument historyfile is given,
177 this file will be used for reading and writing the command history
178 instead of the default .tclsh-history. ::tclreadline::Loop will
179 normally not return. If you want to write your own main loop
180 and/or own custom completers, it is probably a good idea to start
181 with tclreadline::Loop (see the file tclreadlineSetup.tcl).
182 ::tclreadline::prompt1
185 a proc which is called by ::tclreadline::Loop and returns a string
186 which will be displayed as the primary prompt. This prompt will be
187 something like "[info nameofexecutable] \[[pwd]\]" possibly fancy
188 colored. The default proc is defined on entering the ::tclread‐
189 line::Loop, if it is not already defined. So: If you define your
190 own proc ::tclreadline::prompt1 before entering ::tclread‐
191 line::Loop, this proc is called each time the prompt is to be dis‐
192 played. Example:
193 package require tclreadline
194 namespace eval tclreadline {
195 proc prompt1 {} {
196 return "[clock format [clock seconds]]> "
197 }
198 }
199 ::tclreadline::Loop
200 Note that non-printable control characters as color control characters
202 must be enclosed in literal ctrl-a / ctrl-b to tell readline the length
203 of the printable prompt. See for example the variable `prompt_string'
204 in the file tclreadlineSetup.tcl in your tclreadline installation
205 directory.
206
213 tclreadline defines the following variables in the namespace ::tclread‐
214 line: (for backwards compatibility the global variables tclread‐
215 line_version,
216 tclreadline_patchLevel and tclreadline_library are still present).
217 tclreadline::version (read-only)
220 holds the version string "2.1.0".
221 tclreadline::patchLevel (read-only)
224 holds the patch level string "2.1.0".
225 tclreadline::library (read-only)
228 holds the library string "/usr/lib64/tcl8.6/tclreadline2.1.0".
229 tclreadline::license (read-only)
232 holds a BSD license statement.
233 tclreadline::historyLength
236 Number of lines, which will be written to the historyfile. This
237 number is -1 by default, which means that the historyfile will not
238 be truncated. See also tclreadline::write.
239
242 the .tclshrc file in the HOME directory, which is read on tclsh
243 startup. Alternatively, the name of this initialization file might be
244 .wishrc ... depending on what interpreter you use. These files should
245 typically contain something like
246 if {$tcl_interactive} {
247 package require tclreadline
248 ::tclreadline::Loop
249 }
250 which will enter the tclreadline main loop.
252 the .tclsh-history file in the HOME directory. On startup commands will
255 be read from this file. On exit, the readline history is written to
256 this file. Note that if you abort tclsh with <cntrl-c> no history is
257 written. For the future it is planned to set up a signal handler, which
258 will write the history on <ctrl-c> before exiting.
259 the .inputrc file in the users HOME directory. This file is used nor‐
262 mally for all programs which use the gnu readline (e.g. bash). The
263 `global' readline settings there will be valid also for tclreadline.
264 Additionally the .inputrc might hold conditional settings for the
265 implementation name tclreadline. Example of some lines in your .inpu‐
266 trc:
267 $if tclreadline
268 "\C-xp": "puts $env(PATH)"
269 $endif
270 For further documentation please refer to the gnu readline documenta‐
272 tion.
273
276 citing the readline manual: It's too big and too slow.
277
281 The official tclreadline web site at:
282 http://www.zellner.org/tclreadline/
285
289 Johannes Zellner, <johannes@zellner.org>
290
293 Magnus Eriksson <magnus.eriksson@netinsight.se>, Les Johnson <les@info‐
294 labs.com>, Harald Kirsch <kir@iitb.fhg.de>, Christian Krone
295 <krischan@sql.de>, Larry W. Virden <lvirden@cas.org>, David Engel
296 <dlengel@home.com> <david@debian.org>, Matthew Clarke
297 <Matthew_Clarke@mindlink.bc.ca>
298
301 David Engel <dlengel@home.com>, <david@debian.org>
302
305 tclreadline comes with a BSD type license. The read-only variable
306 tclreadline::license holds the complete license statement.
307Johannes Zellner 2.1.0 tclreadline(n)