GAP (hpc) - Chapter 4: Console User Interface

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

4 Console User Interface
4.1 Console UI commands
4.1-1 !shell [name]
4.1-2 !fork [name]
4.1-3 !list
4.1-4 !kill id
4.1-5 !break id
4.1-6 !name [id] name
4.1-7 !info id
4.1-8 !hide [id|*]
4.1-9 !watch [id|*]
4.1-10 !keep num
4.1-11 !prompt (id|*) string
4.1-12 !prefix (id|*) string
4.1-13 !select id
4.1-14 !next
4.1-15 !previous
4.1-16 !replay num [id]
4.1-17 !id
4.1-18 !source file
4.1-19 !alias shortcut expansion
4.1-20 !unalias shortcut
4.1-21 !eval expr
4.1-22 !run function string
4.2 GAP functions to access the Shell UI
4.2-1 TextUIRegisterCommand
4.2-2 TextUIForegroundThread
4.2-3 TextUIForegroundThreadName
4.2-4 TextUISelectThread
4.2-5 TextUIOutputHistory
4.2-6 TextUISetOutputHistoryLength
4.2-7 TextUINewSession
4.2-8 TextUIRunCommand
4.2-9 TextUIWritePrompt

### 4 Console User Interface

HPC-GAP has a multi-threaded user interface to assist with the development and debugging of concurrent programs. This user interface is enabled by default; to disable it, and use the single-threaded interface, GAP has to be started with the `-S` option.

#### 4.1 Console UI commands

The console user interface provides the user with the option to control threads by commands prefixed with an exclamation mark ("!"). Those commands are listed below.

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 `!l` as an abbreviation for `!list`.

##### 4.1-1 !shell [name]

Starts a new shell thread and switches to it. Optionally, a name for the thread can be provided.

    gap> !shell
    --- Switching to thread 4
    [4] gap>

##### 4.1-2 !fork [name]

Starts a new background shell thread. Optionally, a name for the thread can be provided.

    gap> !fork
    --- Created new thread 5

##### 4.1-3 !list

List all current threads that are interacting with the user. This does not list threads created with `CreateThread()` that have not entered a break loop.

    gap> !list
    --- Thread 0 [0]
    --- Thread 4 [4]
    --- Thread 5 [5] (pending output)

##### 4.1-4 !kill id

Terminates the specified thread.

##### 4.1-5 !break id

Makes the specified thread enter a break loop.

##### 4.1-6 !name [id] name

Give the thread with the numerical identifier or name `id` the name `name`.

    gap> !name 5 test
    gap> !list
    --- Thread 0 [0]
    --- Thread 4 [4]
    --- Thread test [5] (pending output)

##### 4.1-7 !info id

Provide information about the thread with the numerical identifier or name `id`. Not yet implemented.

##### 4.1-8 !hide [id|*]

Hide output from the thread with the numerical identifier or name `id` when it is not the foreground thread. If no thread is specified, make this the default behavior for future threads.

##### 4.1-9 !watch [id|*]

Show output from the thread with the numerical identifier or name `id` even when it is not the foreground thread. If no thread is specified, make this the default behavior for future threads.

##### 4.1-10 !keep num

Keep `num` lines of output from each thread.

##### 4.1-11 !prompt (id|*) string

Set the prompt for the specified thread (or for all newly created threads if `*` was specified) to be `string`. If the string contains the pattern `id`, it is replaced with the numerical id of the thread; if it contains the pattern `name`, it is replaced with the name of the thread; if the thread has no name, the numerical id is displayed instead.

##### 4.1-12 !prefix (id|*) string

Prefix the output from the specified thread (or for all newly created threads if `*` was specified) with `string`. The same substitution rules as for the `!prompt` command apply.

##### 4.1-13 !select id

Make the specified thread the foreground thread.

    gap> !select 4
    gap> !select 4
    --- Switching to thread 4
    [4] gap>

##### 4.1-14 !next

Make the next thread in numerical order the foreground thread.

##### 4.1-15 !previous

Make the previous thread in numerical order the foreground thread.

##### 4.1-16 !replay num [id]

Display the last `num` lines of output of the specified thread. If no thread was specified, display the last `num` lines of the current foreground thread.

##### 4.1-17 !id

`!id` is a shortcut for `!select id`.

##### 4.1-18 !source file

Read commands from file `file`.

##### 4.1-19 !alias shortcut expansion

Create an alias. After defining the alias, `!shortcut 'rest of line'` will be replaced with `!expansion 'rest of line'`.

##### 4.1-20 !unalias shortcut

Removes the specified alias.

##### 4.1-21 !eval expr

Evaluates `expr` as a command.

##### 4.1-22 !run function string

Calls the function with name `function`, passing it the single argument `string` as a GAP string.

#### 4.2 GAP functions to access the Shell UI

There are several functions to access the basic functionality of the shell user interface. Other than `TextUIRegisterCommand` (4.2-1), they can only be called from within a registered command.

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.

##### 4.2-1 TextUIRegisterCommand

`‣ TextUIRegisterCommand`( name, func ) | ( function )

Registers the command `!name` with the shell UI. It will call <func> with the rest of the command line passed as a string argument when typed.

##### 4.2-2 TextUIForegroundThread

`‣ TextUIForegroundThread`( ) | ( function )

Returns the numerical identifier of the current foreground thread.

##### 4.2-3 TextUIForegroundThreadName

`‣ TextUIForegroundThreadName`( ) | ( function )

Returns the name of the current foreground thread or `fail` if the current foreground thread has no name.

##### 4.2-4 TextUISelectThread

`‣ TextUISelectThread`( id ) | ( function )

Makes id the current foreground thread. Returns `true` or `false` to indicate success.

##### 4.2-5 TextUIOutputHistory

`‣ TextUIOutputHistory`( id, count ) | ( function )

Returns the last count lines of the thread specified by id (which can be a numerical identifier or a name). Returns `fail` if there is no such thread.

##### 4.2-6 TextUISetOutputHistoryLength

`‣ TextUISetOutputHistoryLength`( length ) | ( function )

By default, retain length lines of output history from each thread.

##### 4.2-7 TextUINewSession

`‣ TextUINewSession`( foreground, name ) | ( function )

Creates a new shell thread. Here, foreground is a boolean variable specifying whether it should be made the new foreground thread and name is the name of the thread. The empty string can be used to leave the thread without a name.

##### 4.2-8 TextUIRunCommand

`‣ TextUIRunCommand`( command ) | ( function )

Run the command denoted by command as though a user had typed it. The command must not contain a newline character.

##### 4.2-9 TextUIWritePrompt

`‣ TextUIWritePrompt`( ) | ( function )

Display a prompt for the current thread.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind

generated by GAPDoc2HTML