10. SESSIONS, INITIALIZATION, AND RECOVERY

This section of the manual describes the life-cycle of an edit session. We begin with the definition of an edit session and what that means to elvis. This is followed by sections discussing initialization and recovery after a crash.

10.1 Sessions

Elvis is eventually expected to meet the COSE standards, which require (among other things) that programs be able to save their state so that they can be restarted later. It isn't required to restart in exactly the same state, but it should come as close as possible.

For elvis, this means that edit sessions should be restartable. It is possible to begin an edit session with one elvis process, exit that process, and then later start a new elvis process which resumes the previous edit session.

To accomplish this, elvis stores its state in a file, called the session file. For all practical purposes, the session file is the session.

The name of the session file is stored in the session option. By default, this will be a file in your home directory, named "elvis*.ses", where "*" represents a number chosen at run-time to make the file name unique. You can specify some other name for the session file via the -ssession command-line flag.

If the session file doesn't already exist when elvis starts running, then elvis will create it.

When elvis exits, it will normally delete the session file if this is the elvis process that created it. If the session file was left over from some other elvis process, then elvis will not delete it upon exiting. This is controlled by the tempsession option; if you don't like elvis' default behavior then you can change it.

10.2 Initialization

Before discussing elvis' initialization, let me just say that if you're having trouble configuring elvis, you might want to try invoking elvis with the command line flag -VVV, which causes elvis to write status information to stdout/stderr so you can see what it is doing. The flag -ologfile will redirect this information to a file named logfile. Windows programs such as WinElvis.exe aren't allowed to write anything to stdout, so you must use -ologfile any time you use -VVV. Now, back to the topic at hand...

Elvis begins by initializing some options to hardcoded values.

Elvis then chooses which user interface it should use. Elvis does this by scanning the command line arguments for a -Ggui flag; if there is no such flag, then elvis tests each user interface and uses the best one that is expected to work. (For example, the "x11" interface is expected to work if there is a DISPLAY environment variable and the X server is accessible. If not, then the "x11" interface is rejected and some other interface is used.)

The session file is then opened or created. For preexisting session files, elvis scans the session file for any buffers in it, and adds them to its internal list. Elvis can even reload the "undo" versions of some buffers.

Elvis searches through the directories named in the elvispath option for a file named "elvis.ini". If it finds that file, then it loads it into a buffer named "Elvis initialization" and executes its contents as a series of ex commands. See section 10.2.1 for description of the default contents of this file.

After that, it attempts to similarly load some other files, but they aren't executed. Some of them will be executed later. These files are:

.-----------.----------------------.------------------------------.
| FILE NAME | BUFFER NAME          | PURPOSE                      |
|-----------|----------------------|------------------------------|
| elvis.msg | Elvis messages       | used to translate messages   |
| elvis.brf | Elvis before reading | executed before loading file |
| elvis.arf | Elvis after reading  | executed after loading file  |
| elvis.bwf | Elvis before writing | executed before saving file  |
| elvis.awf | Elvis after writing  | executed after saving file   |
^-----------^----------------------^------------------------------^

The "elvis.msg" file is described in section 11: Messages. The other files are described later in this section.

The next step in initialization is to load the first file and display it in a window. To do this, it first creates an empty buffer with the same name as the file. It then executes the "Elvis before reading" buffer (if it exists) on the empty buffer. The file's contents are then read into the buffer. Then the "Elvis after reading" buffer (if it exists) is executed on the new buffer. Finally, elvis creates a new window that shows the new buffer.

If the -a flag was given on the command line, then elvis will repeat the above steps for each file named on the command line. On the other hand, if no filenames were given on the command line then elvis will simply create a single untitled buffer and a window that shows it.

10.2.1 The "elvis.ini" file

The "elvis.ini" file is loaded into a buffer named "Elvis initialization". That buffer is then executed before any other initialization files are loaded. If the session file is later restarted, this script will be executed again at that time. Here's a line-by-line analysis of the default "elvis.ini" file...

	" DEFINE SOME DIGRAPHS
	if os=="msdos" || os=="os2" || (os=="win32" && gui!="windows")
	then source! (elvispath("elvis.pc8"))
	else source! (elvispath("elvis.lat"))

This attempts to locate the "elvis.lat" or "elvis.pc8" file and execute it. Those files contain ex scripts, consisting of a bunch of :digraph commands that set up the digraph table appropriately for the Latin-1 symbol set. The "!" at the end of the :source command name causes :source to silently ignore errors.

	" CHOOSE SOME DEFAULT OPTION VALUES BASED ON THE INVOCATION NAME
	let p=tolower(basename(program))
	if p == "ex" || p == "edit"
	then set! initialstate=ex
	if p == "view"
	then set! defaultreadonly
	if p == "edit" || p == "vedit"
	then set! novice
	if home == ""
	then let home=dirdir(program)

These lines initialize certain options according to the name by which elvis was invoked. Traditionally, invoking vi by the name "ex" causes it to start up in ex mode instead of vi mode, and "view" causes the files to be treated as readonly.

	" SYSTEM TWEAKS GO HERE
	"
	" The Linux console can't handle colors and underlining.
	if gui=="termcap"
	then {
	 if term=="linux"
	 then set! nottyunderline
	}

This is an attempt to work around a bug in the Linux console driver. The Linux console can't mix color attributes with the underline attribute.

" WINDOWS DEFAULT COLORS GO HERE (may be overridden in elvis.rc file)
if gui=="windows"
then {
 color e green
 color i magenta
 color u blue
 color f red
}
" X11 DEFAULT COLORS AND TOOLBAR GO HERE (may be overridden in .exrc file)
if gui=="x11"
then so! (elvispath("elvis.x11"))

These lines set the defaults for the "windows" and "x11" user interfaces.

Note that "x11" configuration commands are actually stored in a separate file. This is because there are large number of commands for setting up the toolbar, and I didn't want to force other GUIs to read them just to ignore them. You should set the defaults in "elvis.x11", and not in an app-defaults file. If you aren't using the "x11" user interface, then these lines have no effect.

	" EXECUTE THE STANDARD CUSTOMIZATION SCRIPTS
	let f=(os=="unix" ? ".elvisrc" : "elvis.rc")
	if $EXINIT
	then eval $EXINIT
	else source! (exists("~"/f) ? "~"/f : "~/.exrc")
	if exrc && getcwd()!=home
	then safer! (exists(f) ? f : ".exrc")
	set f=""

These lines set the f option to either ".elvisrc" or "elvis.rc", whichever is appropriate for your operating system. They then check whether an environment variable named "EXINIT" is set to a non-empty value. If so, then the value of EXINIT is executed as an ex command line; otherwise the ".elvisrc" or "elvis.rc" file in your home directory is executed, if it exists. If that file doesn't exist, then it tries ".exrc"... which probably only makes sense for Unix, but it is quicker to try & fail then to test before trying. The "~" notation is UNIX's conventional alias for referring to files in your home directory; elvis handles it correctly on non-UNIX systems too.

Note: There is a hardcoded limit of (normally) 1023 characters for the n\} or \{n} operator, in particular, means that the preceding expression should be repeated exactly n times. For example, /^-\{80\}$/ matches a line of eighty hyphens, and /\<[[:alpha:]]\{4}\>/ matches any four-letter word.

\{n,m\} or \{n,m}

This is a closure operator which means that the preceding single-character expression should be repeated between n and m times, inclusive. If the m is omitted (but the comma is present) then m is taken to be infinity. For example, /"[^"]\{3,5\}"/ matches any pair of quotes which contains three, four, or five non-quote characters. /.\{81,}/ matches any line which contains more than 80 characters.

The * metacharacter is a closure operator which means that the preceding single-character expression can be repeated zero or more times. It is equivalent to \{0,\}. For example, /.*/ matches a whole line.

NOTE: If the magic option is turned off, then * is treated as an ordinary, literal character. You should use \* to get the meta-character version in this case.

The \+ metacharacter is a closure operator which means that the preceding single-character expression can be repeated one or more times. It is equivalent to \{1,\}. For example, /.\+/ matches a whole line, but only if the line contains at least one character. It doesn't match empty lines.

The \? metacharacter is a closure operator which indicates that the preceding single-character expression is optional -- that is, that it can occur 0 or 1 times. It is equivalent to \{0,1\}. For example, /no[ -]\?one/ matches "no one", "no-one", or "noone".

Anything else is treated as a normal character which must exactly match a character from the scanned text. The special strings may all be preceded by a backslash to force them to be treated normally.

5.2 Substitutions

The :s command has at least two arguments: a regular expression, and a substitution string. The text that matched the regular expression is replaced by text which is derived from the substitution string.

You can use any punctuation character to delimit the regular expression and the replacement text. The first character after the command name is used as the delimiter. Most folks prefer to use a slash character most of the time, but if either the regular expression or the replacement text uses a lot of slashes, then some other punctuation character may be more convenient.

Most other characters in the substitution string are copied into the text literally but a few have special meaning:

.-------.----------------------------------------------------------.
|SYMBOL | MEANING                                                  |
|-------|----------------------------------------------------------|
|   &   | Insert a copy of the original text                       |
|   ~   | Insert a copy of the previous replacement text           |
|  \1   | Insert a copy of that portion of the original text which |
|       |      matched the first set of \( \) parentheses          |
| \2-\9 | Do the same for the second (etc.) pair of \( \)          |
|  \U   | Convert all chars of any later & or \# to uppercase      |
|  \L   | Convert all chars of any later & or \# to lowercase      |
|  \E   | End the effect of \U or \L                               |
|  \u   | Convert the first char of the next & or \# to uppercase  |
|  \l   | Convert the first char of the next & or \# to lowercase  |
^-------^----------------------------------------------------------^

These may be preceded by a backslash to force them to be treated normally. The delimiting character can also be preceeded by a backslash to include it in either the regular expression or the substitution string.

5.3 Options

Elvis has two options which affect the way regular expressions are used. These options may be examined or set via the :set command.

The first option is called "[no]magic". This is a boolean option, and it is "magic" (TRUE) by default. While in magic mode, all of the meta-characters behave as described above. In nomagic mode, the ., [...], and * characters loose their special meaning unless preceeded by a backslash. Also, in substitution text the & and ~ characters are treated literally unless preceeded by a backslash.

The second option is called "[no]ignorecase". This is a boolean option, and it is "noignorecase" (FALSE) by default. While in ignorecase mode, the searching mechanism will not distinguish between an uppercase letter and its lowercase form, except in a character list metacharacter. In noignorecase mode, uppercase and lowercase are treated as being different.

Also, the "[no]wrapscan" and "[no]autoselect" options affect searches.

5.4 Examples

This example changes every occurrence of "utilize" to "use":

:%s/utilize/use/g

This example deletes all whitespace that occurs at the end of a line anywhere in the file. (The brackets contain a single space and a single tab.):

:%s/[   ]\+$//

This example converts the current line to uppercase:

:s/.*/\U&/

This example underlines each letter in the current line, by changing it into an "underscore backspace letter" sequence. (The ^H is entered as "control-V backspace".):

:s/[a-zA-Z]/_^H&/g

This example locates the last colon in a line, and swaps the text before the colon with the text after the colon. The first  pair is used to delimit the stuff before the colon, and the second pair delimit the stuff after. In the substitution text, \1 and \2 are given in reverse order to perform the swap:

:s/\(.*\):\(.*\)/\2:\1/

usr/doc/elvis/elvisses.html100644 0 0 51701 6502273123 14404 0ustar rootroot Elvis 2.1 Sessions