# The Magma Line Editor 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 `-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) `-`*key* means hold down the Control key and press *key*. ### `` Accept the line and print a new line. This works in any mode. ### `` ### `` Delete the previous character. ### `` 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. ### `-A` Move to the beginning of the line (“alpha” = “beginning”). ### `-B` Move back a character (“back”). ### `-C` Abort the current line and start a new line. ### `-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”). ### `-E` Move to the end of the line (“end”). ### `-F` Move forward a character (“forward”). ### `-H` Same as Backspace. ### `-I` Same as Tab. ### `-J` Same as Return. ### `-K` Delete all characters from the cursor to the end of the line (“kill”). ### `-L` Redraw the line on a new line (helpful if the screen gets wrecked by programs like “write”, etc.). ### `-M` Same as ``. ### `-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 -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 -P (see below), press ``, then successively press -N followed by `` for each line. ### `-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 -P will go back to the last line which assigned `x` (if a line begins with, say, `x :=`, it will also be taken). ### `-U` Clear the whole of the current line. ### `-V` Insert the following character literally. ### `-W` Delete the previous word. ### `-X` Same as -U. ### `-Y` Insert the contents of the yank-buffer before the character under the cursor. ### `-Z` Stop Magma. ### `-_` Undo the last change. ### `-\` Immediately quit Magma. On most systems the arrow keys also have the obvious meaning. ## Key Bindings in Emacs mode only -*key* means press the Meta key and then *key*. (At the moment, the Meta key is only the Esc key.) ### `-R` Search backwards through the history for a line CONTAINING what you type, 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 -P searches by PREFIX, this searches anywhere in the line. Another -R moves to the next older line that matches, and -N to the next newer. Once the history buffer is exhausted the search goes on into the saved sessions, if a history directory is configured (see `MAGMA_CONFIG_DIR` above); the prompt then reads `(i-search saved)`, and `(failing i-search)` when there is nothing left to find. `` shortens the pattern and -U clears it. `` puts the line that was found into the editor WITHOUT running it, so that it can be edited first; a second `` runs it, as always. -G or `` abandons the search and puts back the line you were typing — except that when the pattern has failed, the first -G takes it back to the last part of it that did match, so that a typo costs one key rather than a `` 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 vi mode this key opens the session browser instead (see `MAGMA_CONFIG_DIR` in Section [Environment Variables](environment-variable.md#sec-environment-variable)); in emacs mode the browser is ` r`, or a second -R typed at an empty search prompt. Both keys can be changed, with the `search-key`, `browser-key-emacs` and `browser-key-vi` options (Section [The Options File](history-files.md#sec-options-file)). ### `-b` ### `-B` Move back a word (“Back”). ### `-f` ### `-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. ### `-space` Move to the first non-space character of the line. ### `%` Move to the matching bracket. (Bracket characters are (, ), [, ], $\{$, $\}$, $<$, and $>$.) ### `;` Move to the next character. (See ‘F’, ‘f’, ‘T’, and ‘t’.) ### `,` Move to the previous character. (See ‘F’, ‘f’, ‘T’, and ‘t’.) ### `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` Move back to the first occurrence of . ### `f` Move forward to the first occurrence of . ### `h` ### `H` Move back a character (-H = Backspace). ### `l` ### `L` Move back a character (-L = forward on some keyboards). ### `T` Move back to just after the first occurrence of . ### `t` Move forward to just before the first occurrence of . ### `w` Move forward a space-separated word (“Word”). ### `W` Move forward a 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 -N). ### `k` Go back a line in the history buffer (same as -P). ### `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` Replace the character the cursor is over with . ### `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.