visual display editor clone (UNIX)
elvis [options]... [+command] file...
The elvis utility is an interactive fullscreen editor that is compatible with the Unix/POSIX vi editor. The vi utility in QNX is a link to elvis.
In elvis, changes are buffered and are written to the file only upon request. Since a temporary file is used for storage, elvis can edit files larger than the amount of memory available on the machine it is run on.
There are two major command modes:
You can switch between modes. You'll probably use the visual command mode most of the time. This is the mode elvis normally starts up in.
In visual mode, the entire screen is filled with lines of text from your file (except the last screen line, which is reserved for status). You can view text and move around the file. Each keystroke is interpreted as part of a visual command. If you start typing text, it won't be inserted; instead, it'll be treated as part of a command. To insert text, you must first give an "insert text" command (see "Inserting text").
The ex mode is quite different. In this mode, elvis displays a ":" character on the bottom line of the screen as a prompt. You are then expected to type in a command and press Enter. The set of commands recognized in ex mode differs from those in visual mode, and are known as ex commands. A summary of these commands is found at the end of this man page. (A line-oriented editor, ex is a predecessor of vi, and the two share common functionality.)
The capabilities of elvis are described throughout the following sections:
Most visual mode commands are one keystroke long. The following sections list the operation performed by each keystroke, and any necessary options or operands.
Most commands may be preceded by a decimal number. Usually, this number specifies how many times the command is to be repeated. Without this number, the command will in most cases execute just once.
You cannot enter text into your file directly from visual command mode. Instead, you must first give a command that puts you into input mode. The commands to do this are:
Visual command mode looks a lot like text input mode. If you forget which mode you're in, simply hit Esc. If elvis beeps, you're in visual command mode. If elvis doesn't beep, you were in input mode — by hitting Esc you'll have switched to visual command mode. One way or another, after you hit Esc, elvis will be ready for a command.
Note that if the showmode option is set (this option described in the "Options" section below), the mode will be displayed in the lower right-hand corner as either Command or Input. Also note that each mode uses a different cursor shape.
Among its various commands, elvis has seven basic but powerful operators that let you change, delete, cut, paste, shift, or filter text regions. Although they're described below in the appropriate sections, you should note that, for the most part, they all share a common form:
Where op can be:
One operator does not take an object:
The object operand specifies the range of text that the op operator will act upon. The object can be any movement command or pattern search. (See Movement Commands). In this way, the power of the operators can be seen. The elvis utility can act on words, sentences, regions up to a specified pattern-whatever range the object operand specifies.
When you give a movement command as an operand, you can specify an optional count [n] to multiply the effect of the operand (e.g. d2w to delete next two words). When a count isn't provided, it typically defaults to 1. See the section on Movement Commands.
Operators are frequently used with lines. So, for simplicity, a few special forms of these commands operate only with line objects. The following list shows the syntax of these special forms. Note the count is optional, and precedes the operator (this differs from the above form):
When you yank, delete, change, shift, or filter text, elvis saves the affected region in a single unnamed cut buffer (which you can recall by the put command). However, elvis also has 26 named buffers, a to z, which you can use to save blocks of text during an edit session. These buffers are often used when editing multiple files to move text around.
The previously defined operator forms can now be prefixed by "a through "z (represented below by "<a-z>) to indicate which cut buffer is to be used to store the modified text region:
When you use the uppercase letters to denote the named buffers, the objects are appended to the buffer. Thus adding the following forms:
The following movement commands provide a convenient means to position the cursor throughout the file being edited. Most can be preceded by an optional count to repeat the action. More importantly, these movement commands can be used as operands to the change, yank, delete, put commands to specify the range of action to be performed (see "Inserting text" and "Deleting, yanking, putting" sections).
The following text objects are used in conjunction with the movement commands:
. ! ?
To move the cursor, you can use the keypad arrow keys; you can also use the H, J, K, and L keys.
Tags can't be included as <object> operands for commands such as change, yank, put, delete, shift, and filter.
The following commands enter input mode, where the text you enter is put into the file, until you press Esc.
If the range is within the current line, a $ will be displayed at the end of the <object> to indicate end-of-range. Otherwise, the text in the range is deleted and you're placed in input mode. When within a line, the specified range of text isn't deleted until you type Enter.
In input mode, all keystrokes are inserted into the text at the cursor's position, except for the following:
As mentioned in the Introduction, elvis supports very powerful operator constructs. In this section we'll deal with the delete, yank, and put operators.
When you have a sequence of text you want to copy or move to a different location, you would first use the yank or delete operators to copy or delete the data into a buffer; you would then specify the put command to place the data at its new location. You can switch to another file before putting the text back, thus you can copy from one file to another.
To copy the next four lines, you would yank them with a command such as:
4yy or y4j
then you would move to a new location and put the text by typing:
p
To delete the next four lines, you would use a command such as:
4dd or d4j
To move the next four lines, you would use a command such as:
4dd or d4j
then you would move to a new location and put the text by typing:
p or :pu
With the filter command, you can select regions of text and run them through any command and insert the output into the file. The text in the range specified from the current line to the delimited <object> is filtered through the command and replaces the region specified. The text that was in the region before being replaced by the output of the command is saved in the unnamed buffer — or in a named buffer if one was specified. If uppercase letters are used, elvis will append text to the named buffer.
The shift operators, < and >, shift all the lines delimited by the current line and the <object> operand. Text is shifted by the value of the shiftwidth option (see below). The forms of the shift command are:
"Named Buffer" prefixes don't work with the shift operator.
A pattern used for searching and substituting is called a regular expression. While most characters will match themselves in a search request, some have special meaning. To be used in a search expression, these special characters must be preceded by a backslash: \
Special search characters
| Character | Meaning |
|---|---|
| ^ | Match "beginning of line". |
| $ | Match "end of line". |
| . | Match any single character except the newline. |
| \< | Match the beginning of a word. |
| \> | Match the end of a word. |
| [string] | Match any single character in string. |
| [^string] | Match any single character not in string. |
| [x-y] | Match any character between x and y (range). |
| [^x-y] | Match any character not between x and y (range). |
| * | Match any repeated characters. |
| \ | Escape special characters. |
The substitute command substitutes text matching a pattern with replacement text:
If none of the modifiers c, g, or p are specified, this command will replace the first occurrence of the given pattern. You can modify this behavior by specifying any combination of the three modifiers:
This command is very powerful when used in conjunction with the global command (see below).
You can specify a range wherever [x,y] is indicated. The first element, x, indicates the first line of the range while the second element, y, indicates the last line. Range elements can be line numbers or any of the following special characters:
A range element may also be a pattern specification:
or a marked location:
For example, to print the lines from the next line containing "steve" until the first subsequent blank line:
/steve,/^$/!lp
The global command searches through the lines of the specified range-or through the whole file if no range ([x,y]) is specified-for lines that contain the pattern. For each matching line, command will be performed on it. The global command is of the following form:
You can combine the substitute and global commands, using the following syntax:
This command runs the substitute command on every occurrence of a matched pattern within the given range. The null pattern specification (i.e. //) indicates to the substitute command that it is to use the currently matched global pattern as the text it is to replace.
The following variations may also be used:
Substitute the word fred with the word barney from lines 1 to 10:
1,10g/fred/s//barney
Match every mary that's at the beginning of a line and prompt the user to confirm the substitution:
1,$g/^mary/s//dave/c
On occasion, you need to undo the effects of a command.
The editor saves the last nine deleted blocks of text in save buffers. You can retrieve a buffer with the following command:
If you accidentally select the wrong buffer, you can use the undo command to clear it and then try specifying a different buffer.
You can also use named buffers (See "Deleting, yanking, putting"):
To position the current line at different positions on the screen by scrolling forward/backward:
All w commands can be preceded by an [x,y] range. For example, to write the first 6 lines you could specify: 1,6w
(See the :tags movement command)
To execute a single command from within elvis, you can use the following command:
Sometimes you may wish to execute more than one command, so you would probably want to create a shell.
Macros let you bind a single key to an arbitrary set of editing commands.
Defining a macro is simple: you define an lhs (left-hand side), which is the single character you want translated, followed by an rhs (right hand side), which is the sequence it will be mapped into.
For example:
This would map q into :wq<Enter>. The Ctrl-V is needed to quote (escape) the first Enter, while the second Enter ends the map definition.
Word abbreviations are similar to macros, but they expand a short word into a longer word or words. If you type the word as part of a longer word, it's left alone. Abbreviations are used in input mode primarily to save typing.
Substitution isn't performed until you type a non-alphanumeric character to mark the end of the word. If you type Ctrl-V before the non-alphanumeric character, elvis won't perform the substitution.
For example:
:ab woof mary had a little ram
This would insert the text "mary had a little ram" whenever the word "woof" is typed.
You can set or examine options via the colon command set. The values of options will affect the operation of subsequent commands.
There are three option types:
To print all the option settings, type:
:set all
For convenience, options have both a long descriptive name and a short name that's easier to type. You may use either interchangeably.
| Long name | Short | Default | Meaning |
|---|---|---|---|
| autoindent | ai | noai | Auto-indent during input |
| autoprint | ap | ap | In ex, print the current line |
| autowrite | aw | noaw | Auto-write when switching files |
| directory | dir | dir="/tmp" | Where tmp files are kept |
| edcompatible | ed | noed | Remember :s// options |
| errorbells | eb | eb | Ring bell on error |
| ignorecase | ic | noic | Upper/lowercase distinction ignored in search |
| list | li | noli | Display lines in "list" mode |
| magic | ma | ma | Allow regular expression in search |
| paragraphs | pa | pa="PPppIPLPQP" | Names of "paragraph" for text formatter |
| readonly | ro | noro | Prevent overwriting of original file |
| report | re | re=5 | Report when 5 or more changes |
| scroll | sc | sc=12 | Scroll amount for Ctrl-U and Ctrl-D |
| sections | se | se="NHSHSSSEse" | Names of "section" for text formatter |
| shell | sh | sh="/bin/sh" | Full pathname of the shell |
| showmatch | sm | nosm | Show matching ( ) [ ] { } |
| showmode | smd | nosmd | Say when we're in input mode |
| shiftwidth | sw | sw=8 | Shift amount for < and > |
| tabstop | ts | ts=8 | Width of tab characters |
| term | te | te="$TERM" | Name of terminal |
| warn | wa | wa | Warn for ! if file is modified |
| wrapmargin | wm | wm=0 | Wrap long lines in input mode |
| wrapscan | ws | ws | At EOF, searches wrap to line 1 |
You can configure the option settings with the EXINIT environment variable:
EXINIT="set ai aw"
export EXINIT
You can set this option only in a .exrc file; after that, elvis will have already started making temporary files in some other directory, so it would be too late.
If your /tmp directory is on ramdisk, recovery won't be possible if the system is rebooted.
It's assumed your formatter uses commands that start with a "." character at the front of a line, followed by a one- or two-character command name.
The value of the paragraphs option is a string in which each pair of characters is one possible form of your text formatter's paragraph command. For example, lines starting with .IP, .LP, or .PP would be considered new paragraphs.
If you set the readonly option, elvis pretends you don't have write permission to any file you edit. This is useful when you mean to use elvis only to look at a file, not to change it. This way, you can't change the file accidentally.
This option is normally off, unless you use the view alias of elvis, which is like elvis except the readonly option is on.
This option lets you configure elvis to work with your text formatter's section command, in exactly the same way that the paragraphs option makes it work with the formatter's paragraphs command. For example, lines starting with .SH or .NH would be considered new sections.
) ---> ( ---> )
} ---> { ---> }
] ---> [ ---> ]Normally, elvis also prints a message after a successful search that wrapped at EOF. The [no]warn option also disables this warning.
However, with wrapmargin set to something other that 0 (wrapmargin=70 is nice), long lines are automatically "wrapped" on a word break for lines longer than wrapmargin's setting.
If you turn off the wrapscan option (:se nows), and elvis subsequently hits EOF during a search, it will stop and say so.
The following list of ex commands is intended for your convenience only. It's beyond the scope of this document to describe the operations of these commands in detail. Most of these commands have been indicated as alternatives to the visual mode commands described in the above sections.
The general form of these commands is:
| [Prefix] | Command | Short form |
|---|---|---|
| abbrev abbr text | ab | |
| [line] | append | a |
| args | ar | |
| [x[,y]] | change | c |
| [x[,y]] | copy line | co |
| [x[,y]] | delete ["named_buffer] | d |
| edit[!] file | e | |
| file | f | |
| [x[,y]] | global /pattern/command/ | g |
| [line] | insert | i |
| [x[,y]] | join | j |
| [x[,y]] | list | l |
| map lhs rhs | map | |
| [x[,y]] | move line | m |
| next[!] | n | |
| [x[,y]] | number | nu |
| [x[,y]] | p | |
| [line] | put ["named_buffer] | pu |
| quit[!] | q | |
| [line] | read file | !command | r |
| rewind[!] | rew | |
| set [option] | se | |
| shell | sh | |
| source file | so | |
| [x[,y]] | substitute /pattern/text/[c][g][p] | s |
| tag | ta | |
| unabbrev abbr | una | |
| undo | u | |
| unmap lhs | unm | |
| version | ve | |
| visual | vi | |
| [x[,y]] | write[!][[>>]file] | w |
| xit[!] | x | |
| [x[,y]] | yank ["named_buffer] | ya |
The following ex commands have no long version:
| Command | Form |
|---|---|
| escape | !command |
| print next | CR |
| lshift | < |
| rshift | > |
The elvis utility requires that the TERM environment variable be set to indicate your terminal type. For example, if elvis is running on a console, TERM should be set as follows:
export TERM=qansi
or
export TERM=qnx
depending on the mode your console is running in (QNX vs ANSI).
When displayed, long lines scroll horizontally. On some implementations, these wrap onto multiple rows on the screen.
Steve Kirkendall