The Magma Line Editor

Magma keeps the command lines of the current session in a history buffer — together with any lines it has remembered from earlier sessions (see Section The History File) — and the line editor is how they are recalled and edited.

Magma provides a line editor with both Emacs and VI style key bindings. To enable the VI style of key bindings, type

SetViMode(true): BoolElt

and type

SetViMode(false): BoolElt

to revert to the Emacs style of key bindings. By default ViMode is false; that is, the Emacs style is in effect. Many key bindings are the same in both Emacs and VI style. This is because some VI users like to be able to use some Emacs keys (like <Ctrl>-P) as well as the VI command keys. Thus key bindings in Emacs which are not used in VI insert mode can be made common to both.

Key Bindings (Emacs and VI mode)

<Ctrl>-key means hold down the Control key and press key.

<Return>

Accept the line and print a new line. This works in any mode.

<Backspace>

<Delete>

Delete the previous character.

<Tab>

Complete the word which the cursor is on or just after. If the word doesn’t have a unique completion, it is first expanded up to the common prefix of all the possible completions. An immediately following Tab key will list all of the possible completions. Currently completion occurs for system functions and procedures, parameters, reserved words, and user identifiers.

<Ctrl>-A

Move to the beginning of the line (“alpha” = “beginning”).

<Ctrl>-B

Move back a character (“back”).

<Ctrl>-C

Abort the current line and start a new line.

<Ctrl>-D

On an empty line, send a EOF character (i.e., exit at the top level of the command interpreter). If at end of line, list the completions. Otherwise, delete the character under the cursor (“delete”).

<Ctrl>-E

Move to the end of the line (“end”).

<Ctrl>-F

Move forward a character (“forward”).

<Ctrl>-H

Same as Backspace.

<Ctrl>-I

Same as Tab.

<Ctrl>-J

Same as Return.

<Ctrl>-K

Delete all characters from the cursor to the end of the line (“kill”).

<Ctrl>-L

Redraw the line on a new line (helpful if the screen gets wrecked by programs like “write”, etc.).

<Ctrl>-M

Same as <Return>.

<Ctrl>-N

Go forward a line in the history buffer (“next”). If the cursor is not at the beginning of the line, go forward to the first following line which starts with the same string (ignoring spaces iff the ignore spaces option is on — see SetIgnoreSpaces) as the string consisting of all the characters before the cursor. Also, if <Ctrl>-N is typed initially at a new line and the last line entered was actually a recall of a preceding line, then the next line after that is entered into the current buffer. Thus to repeat a sequence of lines (with minor modifications perhaps to each), then one only needs to go back to the first line with <Ctrl>-P (see below), press <Return>, then successively press <Ctrl>-N followed by <Return> for each line.

<Ctrl>-P

Go back a line in the history buffer (“previous”). If the cursor is not at the beginning of the line, go back to the first preceding line which starts with the same string (ignoring spaces iff the ignore spaces option is on — see SetIgnoreSpaces) as the string consisting of all the characters before the cursor. For example, typing at a new line x:= and then <Ctrl>-P will go back to the last line which assigned x (if a line begins with, say, x :=, it will also be taken).

<Ctrl>-U

Clear the whole of the current line.

<Ctrl>-V<char>

Insert the following character literally.

<Ctrl>-W

Delete the previous word.

<Ctrl>-X

Same as <Ctrl>-U.

<Ctrl>-Y

Insert the contents of the yank-buffer before the character under the cursor.

<Ctrl>-Z

Stop Magma.

<Ctrl>-_

Undo the last change.

<Ctrl>-\

Immediately quit Magma.

On most systems the arrow keys also have the obvious meaning.

Key Bindings in Emacs mode only

<Meta>-key means press the Meta key and then key. (At the moment, the Meta key is only the Esc key.)

<Ctrl>-R

Search backwards through the history for a line containing what the user types, a character at a time — the incremental reverse search of readline and IPython. The row becomes (i-search)`pat': followed by the most recent line that contains pat, and it is re-searched as each character is typed. Where <Ctrl>-P searches by prefix, this searches anywhere in the line.

Another <Ctrl>-R moves to the next older line that matches, and <Ctrl>-N to the next newer. Once the history buffer is exhausted the search goes on into the saved sessions, if an archive is being kept (Section Saved Sessions and the Browser); the prompt then reads (i-search saved), and (failing i-search) when there is nothing left to find. With no archive the buffer is the whole of it — and it holds what was read from the history file (Section The History File), so there is nothing further to reach. <Backspace> shortens the pattern and <Ctrl>-U clears it.

<Return> puts the line that was found into the editor without running it, so that it can be edited first; a second <Return> runs it, as always. <Ctrl>-G or <Esc> abandons the search and puts back the line the user was typing — except that when the pattern has failed, the first <Ctrl>-G takes it back to the last part of it that did match, so that a typo costs one key rather than a <Backspace> for each character of it (as in emacs itself). Any other control character ends the search, keeps the line that was found, and then does what it normally does.

In emacs mode the session browser (Section Saved Sessions and the Browser) is <Esc> r (or <Esc> R), or a second <Ctrl>-R at an empty search prompt on an empty line. In vi mode <Ctrl>-R on an empty line opens the browser instead (or offers to start an archive), and this search is on / in command mode. All of these keys can be changed with the search-key, search-key-vi, browser-key-emacs, and browser-key-vi options (Section The Options File).

<Meta>-b

<Meta>-B

Move back a word (“Back”).

<Meta>-f

<Meta>-F

Move forward a word (“Forward”).

Key Bindings in VI mode only

In the VI mode, the line editor can also be in two modes: the insert mode and the command mode. When in the insert mode, any non-control character is inserted at the current cursor position. The command mode is then entered by typing the Esc key. In the command mode, various commands are given a range giving the extent to which they are performed. The following ranges are available:

0

Move to the beginning of the line.

$

Move to the end of the line.

<Ctrl>-space

Move to the first non-space character of the line.

%

Move to the matching bracket. (Bracket characters are (, ), [, ], \(\{\), \(\}\), \(<\), and \(>\).)

;

Repeat the last ‘f’, ‘F’, ‘t’, or ‘T’ forwards.

,

Repeat the last ‘f’, ‘F’, ‘t’, or ‘T’ backwards.

B

Move back a space-separated word (“Back”).

b

Move back a word (“back”).

E

Move forward to the end of the space-separated word (“End”).

e

Move forward to the end of the word (“end”).

F<char>

Move back to the first occurrence of <char>.

f<char>

Move forward to the first occurrence of <char>.

h

H

Move back a character (<Ctrl>-H = Backspace).

l

L

Move forward a character (<Ctrl>-L on some keyboards).

T<char>

Move back to just after the first occurrence of <char>.

t<char>

Move forward to just before the first occurrence of <char>.

w

Move forward a word (“word”).

W

Move forward a space-separated word (“Word”).

Any range may be preceded by a number to multiply to indicate how many times the operation is done. The VI-mode also provides the yank-buffer, which contains characters which are deleted or “yanked” – see below. The following keys are also available in command mode:

A

Move to the end of the line and change to insert mode (“Append”).

a

Move forward a character (if not already at the end of the line) and change to insert mode (“append”).

C

Delete all the characters to the end of line and change to insert mode (“Change”).

c range

Delete all the characters to the specified range and change to insert mode (“change”).

D

Delete all the characters to the end of line (“Delete”).

d range

Delete all the characters to the specified range (“delete”).

I

Move to the first non-space character in the line and change to insert mode (“Insert”).

i

Change to insert mode (“insert”).

j

Go forward a line in the history buffer (same as <Ctrl>-N).

k

Go back a line in the history buffer (same as <Ctrl>-P).

/

Start the incremental history search, as <Ctrl>-R does in emacs mode; the keys within the search are the same, except that <Ctrl>-P (rather than another /, which is part of the pattern) moves to the next older line that matches. If search-key-vi is set to a control key instead, that key does so, as <Ctrl>-R does in emacs mode. Unlike the / of readline’s vi mode, the search is incremental. The key can be changed with the search-key-vi option (Section The Options File).

P

Insert the contents of the yank-buffer before the character under the cursor.

p

Insert the contents of the yank-buffer before the character after the cursor.

R

Enter over-type mode: typed characters replace the old characters under the cursor without insertion. Pressing returns to the command mode.

r<char>

Replace the character the cursor is over with <char>.

S

Delete the whole line and change to insert mode (“Substitute”).

s

Delete the current character and change to insert mode (“substitute”).

U

u

Undo the last change.

X

Delete the character to the left of the cursor.

x

Delete the character under the cursor.

Y

“Yank” the whole line - i.e., copy the whole line into the yank-buffer (“Yank”).

y range

Copy all characters from the cursor to the specified range into the yank-buffer (“yank”).

Completion Preferences

When the user presses the Tab key for completion, the line editor offers all intrinsics matching the partial word typed so far. Because many intrinsics have more than one spelling (e.g., the British (-ise) and American (-ize) variants, or the -our/-or families), both spellings are normally offered. The following procedures let the user nominate a preferred spelling, so that the non-preferred duplicates are suppressed from the completion list. Usually, the user would simply prefer to use SetCompletionPreferenceStyle("US"); or SetCompletionPreferenceStyle("UK"); but the SetCompletionPreference procedure allows fine-grained behaviour to be specified.

SetCompletionPreference(P, O): MonStgElt, MonStgElt

Record a preference for the spelling given by the string P (‘preferred’) over that given by the string O (‘other’) when the line editor expands tab completions. Thereafter, whenever the completions for a partial word contain two entries that differ only by P versus O – at the end of the word or at the end of an internal subword (as delimited by a capital letter in a CamelCase name), the entry containing O is discarded and only the P form is offered.

As a special case, the pair ("ize", "ise") (or its reverse ("ise", "ize")) also installs the related suffix forms automatically, namely the pairs izes/ises, ized/ised, izing/ising, izer/iser, izers/isers, izable/isable, and ization/isation.

Several preferences may be in force at once; each call adds a new rule.

ClearCompletionPreference()

Remove all completion preferences previously set by SetCompletionPreference, restoring the default behaviour in which every registered spelling is offered as a completion.

SetCompletionPreferenceStyle(S): MonStgElt

A convenience procedure that calls SetCompletionPreference on a standard collection of British/American spelling pairs at once. If S is "US", the American (US) spellings are preferred, so that -ize, -or, -ors, -oring, and -er are kept in preference to -ise, -our, -ours, -ouring, and -re respectively; if S is "UK", the British spellings are preferred instead.