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
|
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head><title>The GAP Shell User Interface</title></head>
<body>
<h1>The GAP Shell User Interface</h1>
<h2 id="s1.">1. Shell UI commands</h2>
<p>The shell user interface provides the user with the option to control
threads by commands prefixed with an exclamation mark ("!").
Those commands are listed below.</p>
<p>For ease of use, users only need to type as many letters of each
commands so that it can be unambiguously selected. Thus, the shell will
recognize <tt>!l</tt> as an abbreviation for <tt>!list</tt>.</p>
<h3 id="s1.1">1.1 !shell [<name>]</h3>
<p>Starts a new shell thread and switches to it. Optionally, a name for
the thread can be provided.</p>
<h3 id="s1.2">1.2 !fork [<name>]</h3>
<p>Starts a new background shell thread. Optionally, a name for the
thread can be provided.</p>
<h3 id="s1.3">1.3 !list</h3>
<p>List all current threads that are interacting with the user. This
does not list threads created with <tt>CreateThread()</tt> that have not
entered a break loop.</p>
<h3 id="s1.4">1.4 !name [<id>] <name></h3>
<p>Give the thread with the numerical identifier or name
<tt><id></tt> the name name.</p>
<h3 id="s1.5">1.5 !info <id></h3>
<p>Provide information about the thread with the numerical identifier or
name <tt><id></tt>.</p>
<h3 id="s1.6">1.6 !hide [<id>|*]</h3>
<p>Hide output from the thread with the numerical identifier or name
<tt><id></tt> when it is not the foreground thread. If no thread
is specified, make this the default behavior for future threads.</p>
<h3 id="s1.7">1.7 !show [<id>|*]</h3>
<p>Show output from the thread with the numerical identifier or name
<tt><id></tt> even when it is not the foreground thread. If no
thread is specified, make this the default behavior for future
threads.</p>
<h3 id="s1.8">1.8 !keep [<id>] <num></h3>
<p>Keep <tt><num></tt> lines of output from the specified thread.
If no thread was specified, make this the default.</p>
<h3 id="s1.9">1.9 !prompt (<id>|*) <string></h3>
<p>Set the prompt for the specified thread (or for all newly created
threads if <tt>*</tt> was specified) to be <tt><string></tt>. If
the string contains the pattern <tt>%id%</tt>, it is replaced with the
numerical id of the thread; if it contains the pattern <tt>%name%</tt>,
it is replaced with the name of the thread; if the thread has no name,
the numerical id is displayed instead.</p>
<h3 id="s1.10">1.10 !prefix ([<id>]|*) <string></h3>
<p>Prefix the output from the specified thread (or for all newly created
threads if <tt>*</tt> was specified) wiht <tt><string></tt>. The
same substitution rules as for the <tt>!prompt</tt> command apply.</p>
<h3 id="s1.11">1.11 !select <id></h3>
<p>Make the specified thread the foreground thread.</p>
<h3 id="s1.12">1.12 !next</h3>
<p>Make the next thread in numerical order the foreground thread.</p>
<h3 id="s1.13">1.13 !previous</h3>
<p>Make the previous thread in numerical order the foreground
thread.</p>
<h3 id="s1.14">1.14 !replay <num> [<id>]</h3>
<p>Display the last <tt><num></tt> lines of output of the
specified thread. If no thread was specified, display the last
<tt><num></tt> lines of the current foreground thread.</p>
<h3 id="s1.15">1.15 !<id></h3>
<p><tt>!<id></tt> is a shortcut for <tt>!select
<id></tt>.</p>
<h3 id="s1.16">1.16 !source <file></h3>
<p>Read commands from file <tt><file></tt>.</p>
<h3 id="s1.17">1.17 !!<file></h3>
<p><tt>!!<file></tt> is shortcut for <tt>!source
<file></tt>.</p>
<h3 id="s1.18">1.18 !alias <shortcut> <expansion></h3>
<p>Create an alias. After defining the alias, <tt>!<shortcut>
<rest of line></tt> will be replaced with <tt>!<expansion>
<rest of line></tt>.</p>
<h3 id="s1.19">1.19 !unalias <shortcut></h3>
<p>Removes the specified alias.</p>
<h3 id="s1.20">1.20 !eval <gap code></h3>
<p>Evaluates <tt><gap code></tt> as a command.</p>
<h3 id="s1.21">1.21 !run <function> <string></h3>
<p>Calls the function with name <tt><function></tt>, passing it
the single argument <tt><string></tt> as a GAP string.</p>
<hr>
<h2 id="s2.">2. GAP functions to access the Shell UI</h2>
<p><em>Note: These functions currently aren't available due to some
necessary internal reorganization.</em></p>
<p>There are several functions to access the basic functionality of the
shell user interface. Other than <tt><a
href="#s2.1">ShellUIRegisterCommand</a></tt>, they can only be called
from within a registered command.</p>
<p>Threads can be specified either by their numerical identifier or by
their name (as a string). The empty string can be used to specify the
current foreground thread.</p>
<h3 id="s2.1">2.1 ShellUIRegisterCommand(name, func)</h3>
<p>Registers the command <tt>!name</tt> with the shell UI. It will call
<func> with the rest of the command line passed as a string
argument when typed.</p>
<h3 id="s2.2">2.2 ShellUIForegroundThread()</h3>
<p>Returns the numerical identifier of the current foreground
thread.</p>
<h3 id="s2.3">2.3 ShellUIForegroundThreadName()</h3>
<p>Returns the name of the current foreground thread or <tt>fail</tt> if
the current foreground thread has no name.</p>
<h3 id="s2.4">2.4 ShellUISelectThread(id)</h3>
<p>Makes <tt>id</tt> the current foreground thread. Returns
<tt>true</tt> or <tt>false</tt> to indicate success.</p>
<h3 id="s2.5">2.5 ShellUIOutputHistory(id, count)</h3>
<p>Returns the last <tt>count</tt> lines of the thread specified by
<tt>id</tt> (which can be a numerical identifier or a name). Returns
<tt>fail</tt> if there is no such thread.</p>
<h3 id="s2.6">2.6 ShellUIOutputHistoryLength(id, length)</h3>
<p>Retain <tt>length</tt> lines of output history from thread
<tt>id</tt>.</p>
<h3 id="s2.7">2.7 ShellUIOutputHistoryDefaultLength(length)</h3>
<p>By default, retain <tt>length</tt> lines of output history from each
thread.</p>
<h3 id="s2.8">2.8 ShellUIAtomicRegion</h3>
<p><tt>ShellUIAtomicRegion</tt> is a global variable to be used for
synchronization when one wishes to perform multiple operations on the
shell UI as one atomic step, as in:</p>
<pre>
atomic ShellUIAtomicRegion do
...
od;
</pre>
<h3 id="s2.9">2.9 ShellUINewSession(foreground, name)</h3>
<p>Creates a new shell thread. Here, <tt>foreground</tt> is a boolean
variable specifying whether it should be made the new foreground thread
and <tt>name</tt> is the name of the thread. The empty string can be
used to leave the thread without a name.</p>
|
