File: tclreadline.n.html

package info (click to toggle)
tclreadline 1.2.0-6
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 476 kB
  • ctags: 312
  • sloc: tcl: 5,958; sh: 1,544; ansic: 694; makefile: 202
file content (346 lines) | stat: -rw-r--r-- 13,592 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
<!-- manual page source format generated by PolyglotMan v3.0.8, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>tclreadline(n) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
<P>
            <P>
 <P>
   <P>
 
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
tclreadline - gnu readline for the tcl scripting language
<P>
 
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>

<DL>

<DT><B>::tclreadline::readline</B> <I>command</I> [<I>options</I>] </DT>
<DD><P>
 <P>
 </DD>
</DL>

<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
<P>
 The <B>tclreadline</B>
package makes the gnu readline available to the scripting language tcl.
The primary purpose of the package is to facilitate the interactive script
development by the means of word and file name completion as well as history
expansion (well known from shells like bash). <P>
 Additionally tclreadline
can also be used for tcl scripts which want to use a shell like input interface.
In this case the <B>::tclreadline::readline read</B> command has to be called
explicitly. <P>
 <P>
<P>
 The advantage of <B>tclreadline</B> is that it uses the callback
handler mechanism of the gnu readline while it processes tcl events. This
way X events from a wish gui will processed as well as events from the
tclreadline line interface. <P>
 <P>
<P>
 <B>tclreadline</B> is basically a shared library
and a few tcl scripts which are accessed with the tcl package require command.
Therefore <B>tclreadline</B> should work with all common extensions like <B>blt,
itcl, itk, tix ...</B>. <P>
 <P>
  <P>
 <P>
 
<H2><A NAME="sect3" HREF="#toc3">Commands</A></H2>
<P>
 If you want to use <B>tclreadline</B> as a line
interface for developing tcl scripts, you probably don't have to read this
section. In this case the only thing you should do is to modify your .tclshrc
according to the section <B>FILES</B>. <P>
 For the functionality of the GNU readline
you should refer to the readline's documentation. <P>
 <P>
The following list will
give all commands, which are currently implemented in the shared lib (e.g.
libtclreadline1.2.so). Additional commands were introduced in a startup script
<B>tclreadlineSetup.tcl</B>, which lives in the tclreadline installation directory.
(typically something like /usr/local/lib/tclreadline ..) These commands are
primarily for internal use and not documented here. <P>
 Note that all commands
reside in the namespace <B>::tclreadline::</B>. <P>
 <P>
 
<DL>

<DT><B>::tclreadline::readline add</B> <I>string</I>
</DT>
<DD>adds a string to the completer. If the string contains white spaces, each
of the words will be completed consecutively when hitting &lt;Tab&gt;. Example:
<P>
     ::tclreadline::readline add "button pathName ?options?"<BR>
 <P>
 typing but&lt;Tab&gt; will complete to button. Hitting &lt;Tab&gt; again will complete
to "button pathName".  ... <P>
 </DD>

<DT><B>::tclreadline::readline complete</B> <I>string</I> </DT>
<DD>returns
1 if <I>string</I> is a complete tcl command and 0 otherwise. <P>
 </DD>

<DT><B>::tclreadline::readline
customcompleter</B> [<I>string</I>] </DT>
<DD>Register the proc <I>string</I> as custom completer. This
proc is called with exactly four arguments each time completion takes place:
the word to complete ("text"), the "start" and "end" positions of this
word in the line entered so far, and this line ("line"). The custom completion
script should return an array of strings which is a list of completions
for "text".  If there are no completions, it should return an empty string
"".  The first entry in the returned list is the substitution for "text".
The remaining entries are the possible completions. If the custom completion
script returns an empty string and builtin completion is enabled (see <B>tclreadline::readline
builtincompleter</B>), the builtin completer is called. <B>tclreadline::readline
customcompleter</B> simply returns the current custom completer if called w/o
<I>string</I>. To turn of custom completion, call <B>tclreadline::readline customcompleter</B>
with an empty <I>string</I>. <P>
 Example: <B>% puts $b&lt;TAB&gt;</B> will call the custom completer
with the four arguments <I>"$b"</I>, <I>"5"</I>, <I>"8"</I> and <I>"puts $b"</I>. The custom completer
could return a string like "$bl $black $blue", which will complete "$b"
to "$bl" (the longest match) and offer a list of two further matches "$black"
and "$blue". <P>
 For further reference, see the proc tclreadline::ScriptCompleter
in the file tclreadlineSetup.tcl. <P>
 </DD>

<DT><B>::tclreadline::readline builtincompleter</B>
[<I>bool</I>] </DT>
<DD>enable or disable the builtin completer. If the builtin completer
is enabled, it will be invoked either if there is no custom completer,
or the custom completer returned an empty  string. The builtin completer
is on by default. <B>tclreadline::readline builtincompleter</B> returns the current
custom completer (also, if called w/o the <I>bool</I> argument). <P>
 </DD>

<DT><B>::tclreadline::readline
eofchar</B> [<I>script</I>] </DT>
<DD>set a script which will be called, if readline returns
the eof character (this is typically the case if CTRL-D is entered at the
very beginning of the line). The default for this script is "puts {}; exit".
Setting this to an empty value disables any action on eof. <B>tclreadline::readline
eof</B> returns the current eof script. <P>
 </DD>

<DT><B>::tclreadline::readline initialize</B>
<I>historyfile</I> </DT>
<DD>initialize the tclreadline interface and read the history from
the <I>historyfile</I>. On succes an empty string is returned. This command has
to be called before any other tclreadline commands. <P>
 </DD>

<DT><B>::tclreadline::readline
read</B> <I>prompt</I> </DT>
<DD>prints the <I>prompt</I> to stdout and enters the tclreadline event
loop. Both readline and X events are processed. Returns the (eventually history-expanded)
input string. <B>tclreadline::readline read</B> rises an error, if an error occurs
while evaluating a script completer. <P>
 </DD>

<DT><B>::tclreadline::readline write</B> <I>historyfile</I>
</DT>
<DD>writes the history to the <I>historyfile</I>. This command is called automatically
from the internal routine ::tclreadline::Exit. If the variable <B>tclreadline::historyLength</B>
is non-negative, the historyfile will be truncated to hold only this number
lines. <P>
 </DD>

<DT><B>::tclreadline::readline reset-terminal</B> [<I>terminalName</I>] </DT>
<DD>w/o argument:
reset the state of the terminal to what it was before tclreadline was used.
With argument: reinitialize readline's idea of the terminal settings using
terminalName as the terminal type. The form w/o argument might not work
if tclreadline was compiled with an older version of libreadline. <P>
 </DD>

<DT><B>::tclreadline::readline
bell</B> </DT>
<DD>Ring the terminal bell, obeying the setting of bell-style -- audible
or visible. <P>
 </DD>

<DT><B>::tclreadline::Print</B> [<I>yes / no</I>] </DT>
<DD>turns on or off the default
behavior of tclsh to print the result of every command. This is turned on
by default, so it will just behave as the tclsh w/o tclreadline. Turning
off might be useful, when reading binary data for example. If <B>::tclreadline::Print</B>
is called w/o arguments, it returns the current setting. <P>
 </DD>

<DT><B>::tclreadline::Loop</B>
[<I>historyfile</I>] </DT>
<DD>enter the tclreadline main loop. This command is typically
called from the startup resource file (something .tclshrc, depending on
the interpreter you use, see the file `sample.tclshrc'). The main loop sets
up some completion characteristics as variable -- try something like "puts
$b&lt;TAB&gt;" --  and command completion -- try "puts [in&lt;TAB&gt;". If the optional argument
<I>historyfile</I> is given, this file will be used for reading and writing the
command history instead of the default <B>.tclsh-history</B>. <B>::tclreadline::Loop</B>
will normally not return.  If you want to write your own main loop and/or
own custom completers, it is probably a good idea to start with tclreadline::Loop
(see the file tclreadlineSetup.tcl). <P>
 </DD>

<DT><B>::tclreadline::prompt1</B> </DT>
<DD>a proc which
is called by ::tclreadline::Loop and returns a string which will be displayed
as the primary prompt. This prompt will be something like "[info nameofexecutable]
[[pwd]]" possibly fancy colored. The default proc is defined on entering
the ::tclreadline::Loop, if it is not already defined. So: If you define
your own proc ::tclreadline::prompt1 before entering ::tclreadline::Loop,
this proc is called each time the prompt is to be displayed. Example: <blockquote><BR>
<PRE>    package require tclreadline
    namespace eval tclreadline {
        proc prompt1 {} {
            return "[clock format [clock seconds]]&gt; "
        }
    }
    ::tclreadline::Loop
</PRE></DD>
</DL>
</blockquote>
 <P>
 Note that non-printable control characters as color control characters
must be enclosed in literal ctrl-a / ctrl-b to tell readline the length of
the printable prompt. See for example the variable `prompt_string' in the
file tclreadlineSetup.tcl in your tclreadline installation directory. <P>
 <P>
 
<P>
 <P>
  <P>
 
<H2><A NAME="sect4" HREF="#toc4">Variables</A></H2>
<P>
 <I>tclreadline</I> defines the following variables in the namespace
<I>::tclreadline</I>: (for backwards compatiblity the global variables tclreadline_version,
 tclreadline_patchLevel and tclreadline_library are still present).<BR>
 <P>
 
<DL>

<DT><B>tclreadline::version</B> (read-only) </DT>
<DD>holds the version string "1.2". <P>
 </DD>

<DT><B>tclreadline::patchLevel</B>
(read-only) </DT>
<DD>holds the patch level string "1.2.0". <P>
 </DD>

<DT><B>tclreadline::library</B> (read-only)
</DT>
<DD>holds the library string "/usr/lib/tclreadline1.2". <P>
 </DD>

<DT><B>tclreadline::license</B>
(read-only) </DT>
<DD>holds a BSD license statement. <P>
 </DD>

<DT><B>tclreadline::historyLength</B> </DT>
<DD>Number
of lines, which will be written to the historyfile. This number is -1 by
default, which means that the historyfile will not be truncated.  See also
<B>tclreadline::write</B>. <P>
 </DD>
</DL>

<H2><A NAME="sect5" HREF="#toc5">Files</A></H2>
<P>
 the <B>.tclshrc</B> file in the HOME directory, which
is read on tclsh startup. Alternatively, the name of this initialization
file might be <B>.wishrc</B> ... depending on what interpreter you use. These files
should typically contain something like <blockquote><BR>
<PRE>    if {$tcl_interactive} {
        package require tclreadline
        ::tclreadline::Loop
    }
</PRE></blockquote>
 <P>
 which will enter the tclreadline main loop. <P>
 <P>
the <B>.tclsh-history</B> file in
the HOME directory. On startup commands will be read from this file. On exit,
the readline history is written to this file. Note that if you abort tclsh
with &lt;cntrl-c&gt; no history is written. For the future it is planned to set up
a signal handler, which will write the history on &lt;ctrl-c&gt; before exiting.
<P>
 <P>
the <B>.inputrc</B> file in the users HOME directory. This file is used normally
for all programs which use the gnu readline (e.g.  bash). The `global' readline
settings there will be valid also for <B>tclreadline</B>. Additionally the .inputrc
might hold conditional settings for the implementation name <B>tclreadline</B>.
Example of  some lines in your .inputrc: <blockquote><BR>
<PRE>    $if tclreadline
    "\C-xp": "puts $env(PATH)"
    $endif
</PRE></blockquote>
 <P>
 For further documentation please refer to the gnu readline documentation.
<P>
 
<H2><A NAME="sect6" HREF="#toc6">Bugs</A></H2>
citing the readline manual:  It's too big and too slow. <P>
 <P>
 
<H2><A NAME="sect7" HREF="#toc7">See Also</A></H2>
<P>
 <P>

<P>
The official <B>tclreadline</B> web site at: <P>
 <P>
<blockquote><A HREF="http://www.zellner.org/tclreadline/">http://www.zellner.org/tclreadline/</A>

</blockquote>
<P>
 <P>
 
<H2><A NAME="sect8" HREF="#toc8">Author</A></H2>
Johannes Zellner, &lt;johannes@zellner.org&gt; <P>
 
<H2><A NAME="sect9" HREF="#toc9">Contributions, Suggestions
and Patches</A></H2>
Magnus Eriksson &lt;magnus.eriksson@netinsight.se&gt;, Les Johnson &lt;les@infolabs.com&gt;,
Harald Kirsch &lt;kir@iitb.fhg.de&gt;, Christian Krone &lt;krischan@sql.de&gt;, Larry W. Virden
&lt;lvirden@cas.org&gt;, David Engel &lt;dlengel@home.com&gt; &lt;david@debian.org&gt;, Matthew Clarke
&lt;Matthew_Clarke@mindlink.bc.ca&gt; <P>
 
<H2><A NAME="sect10" HREF="#toc10">Debian Package</A></H2>
David Engel &lt;dlengel@home.com&gt;,
&lt;david@debian.org&gt; <P>
 
<H2><A NAME="sect11" HREF="#toc11">Disclaimer</A></H2>
<P>
 <B>tclreadline</B> comes with a BSD type license. The
read-only variable tclreadline::license holds the complete license statement.
<P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Commands</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Variables</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Files</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Bugs</A></LI>
<LI><A NAME="toc7" HREF="#sect7">See Also</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Author</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Contributions, Suggestions and Patches</A></LI>
<LI><A NAME="toc10" HREF="#sect10">Debian Package</A></LI>
<LI><A NAME="toc11" HREF="#sect11">Disclaimer</A></LI>
</UL>
</BODY></HTML>