STEVIE
STEVIE - An Aspiring VI Clone
User Reference - 3.91
Tony Andrews
Ric Kalford
1. Overview
STEVIE is an editor designed to mimic the interface of the
UNIX editor 'vi'. The name (ST Editor for VI Enthusiasts)
comes from the fact that the editor was first written for
the Atari ST. The current version also supports UNIX, Minix
(ST), MS-DOS, and OS/2, but I've left the name intact for
now.
This program is the result of many late nights of hacking
over the last couple of years. The first version was writ-
ten by Tim Thompson and posted to USENET. From there, I
reworked the data structures completely, added LOTS of
features, and generally improved the overall performance in
the process.
I've labelled STEVIE an 'aspiring' vi clone as a warning to
those who may expect too much. On the whole, the editor is
pretty complete. Nearly all of the visual mode commands are
supported. And several of the more important 'ex' commands
are supported as well. I've tried hard to capture the feel
of vi by getting the little things right. Making lines wrap
correctly, supporting true operators, and even getting the
cursor to land on the right place for tabs are all a pain,
but really help make the editor feel right. I've tried to
resist the temptation to deviate from the behavior of vi,
even where I disagree with the original design.
The biggest problem remaining has to do with the fact that
the edit buffer is maintained entirely in memory, limiting
the size of files that can be edited in some environments.
Other missing features include named buffers and macros.
Performance is generally reasonable, although the screen
update code could be more efficient. This is generally only
visible on fairly slow systems.
STEVIE may be freely distributed. The source isn't copy-
righted or restricted in any way. If you pass the program
along, please include all the documentation and, if practi-
cal, the source as well. I'm not fanatical about this, but I
tried to make STEVIE fairly portable and I'd like to see as
many people have access to the source as possible.
The remainder of this document describes the operation of
the editor. This is intended as a reference for users
already familiar with the real vi editor.
�
2. Starting_the_Editor
The following command line forms are supported:
stevie [file ...] Edit the specified file(s)
stevie -t tag Start at the location of the given tag
stevie + file Edit file starting at end
stevie +n file Edit file starting a line number 'n'
stevie +/pat file Edit file starting at pattern 'pat'
If multiple files are given on the command line (using the
first form), the ":n" command goes to the next file, ":N"
goes backward in the list, and ":rew" can be used to rewind
back to the start of the file list.
3. Set_Command_Options
The ":set" command works as usual to set parameters. Each
parameter has a long and an abbreviated name, either of
which may be used. Boolean parameters are set as in:
set showmatch
or cleared by:
set noshowmatch
Numeric parameters are set as in:
set scroll=5
Several parameters may be set with a single command:
set novb sm report=1
To see the status of all parameters use ":set all". Typing
":set" with no arguments will show only those parameters
that have been changed. The supported parameters, their
names, abbreviations, defaults, and descriptions are shown
below:
aitabs Short: aitabs, Default aitabs, Type Boolean
When autoindenting, STeVIe duplicates VI in
padding the white space at the beginning of the
new line with as many tab characters as is
possible. Setting "noaitabs" forces STeVIe to
only use space characters, while autoindenting.
autoindent Short: ai, Default: noai, Type: Boolean
When in insert mode, start new lines at the same
column as the prior line. Unlike vi, you can
backspace over the indentation.
�
backup Short: bk, Default: nobk, Type: Boolean
Leave a backup on file writes.
errorbells Short: eb, Default: noeb, Type: Boolean
Ring bell when error messages are shown.
ignorecase Short: ic, Default: noic, Type: Boolean
Ignore case in string searches.
lines Short: lines, Default: lines=25, Type: Numeric
Number of physical lines on the screen. The
default value actually depends on the host
machine, but is generally 25.
list Short: list, Default: nolist, Type: Boolean
Show tabs and newlines graphically.
modelines Short: ml, Default: noml, Type: Boolean
Enable processing of modelines in files.
number Short: nu, Default: nonu, Type: Boolean
Display lines on the screen with their line
numbers.
report Short: report, Default: report=5, Type: Numeric
Minimum number of lines to report operations on.
return Short: cr, Default: cr, Type: Boolean
End lines with cr-lf when writing files.
scroll Short: scroll, Default: scroll=12, Type: Numeric
Number of lines to scroll for ^D & ^U.
shiftwidth Short: sw, Default: sw=8, Type: Numeric
Amount of space used during the ^D, ^T, >, and <
shift operations. (^D and ^T indent out and in
during insert mode.)
showmatch Short: sm, Default: nosm, Type: Boolean
When a ), }, or ] is typed, show the matching (,
{, or [ if it's on the current screen by moving
the cursor there briefly.
showmode Short: mo, Default: nomo, Type: Boolean
Show on status line when in insert mode.
tabstop Short: ts, Default: ts=8, Type: Numeric
Number of spaces in a tab.
terse Short: terse, Default: noterse, Type: Boolean
This option is currently ignored. It is pro-
vided only for compatibility with vi.
tildeop Short: to, Default: noto, Type: Boolean
If set, tilde is an operator. Otherwise, tilde
acts as normal.
�
wrapmargin Short: wm, Default: wm=0, Type: Numeric
STeVIe will automatically insert a newline, when
it finds a natural break point between words
(space or tab characters) that occur within
"wm" spaces of the right margin. To disable the
wrapmargin feature, set wm=0.
wrapscan Short: ws, Default: ws, Type: Boolean
String searches wrap around the ends of the
file.
vbell Short: vb, Default: vb, Type: Boolean
Use a visual bell, if possible. (novb for audi-
ble bell)
The EXINIT environment variable can be used to modify the
default values on startup as in:
setenv EXINIT="set sm ts=4"
The 'backup' parameter, if set, causes the editor to retain
a backup of any files that are written. During file writes,
a backup is always kept for safety until the write is com-
pleted. At that point, the 'backup' parameter determines
whether the backup file is deleted.
In environments (e.g. OS/2 or TOS) where lines are normally
terminated by CR-LF, the 'return' parameter allows files to
be written with only a LF terminator (if the parameter is
cleared). This parameter is ignored on UNIX systems.
The 'lines' parameter tells the editor how many lines there
are on the screen. This is useful on systems like the ST
(or OS/2 machines with an EGA adapter) where various screen
resolutions may be used. By using the 'lines' parameter,
different screen sizes can be easily handled.
�
4. Function_Key_Mapping
The "map" command in STeVIe varies slightly from the one
used in VI:
1) The function keys (and SHIFT-function keys) are the
only keys that can be mapped to execute a command macro.
2) The function keys may only be used in command mode
and never during insert mode.
3) The command macros may not include any function key
in the macro definition.
4) The command macros may be up to 91 characters long.
The length limitation is due to the limit placed upon the
":" command line.
5) Lastly, the "unmap" and "map!" commands from VI are
not implemented. Provisions for unmapping a function key
are described below.
4.1 Defining_Macros
Function keys are represented in the macro definition by the
notation fx, where x is an ASCII number. A SHIFT-function
keys is represented by Fx, where x is an ASCII number. By
using the fx and Fx notations, macro definitions may be
placed into the STeVIe configuration file or listed to the
screen.
Within the macro definition, control characters have to be
quoted with a control-V (^V). This can be confusing.
During insert mode and at the colon prompt, all control
characters have to be quoted, even the control-V!
Besides being defined in the configuration file, macros can
also be defined at the ":" prompt.
EXAMPLE 1: Define function key 1 to scroll the screen
down. In order to define the following macro at the colon
prompt:
map f1 ^D
type the following characters:
:map f1 ^V^D <RETURN>
The control-V was necessary to quote the control-D.
�
5. Colon_Commands
Several of the normal 'vi' colon commands are supported by
STEVIE. Some commands may be preceded by a line range
specification. For commands that accept a range of lines,
the following address forms are supported:
addr
addr + number
addr - number
where 'addr' may be one of the following:
a line number
a mark (as in 'a or 'b)
'.' (the current line)
'$' (the last line)
An address range of "%" is accepted as an abbreviation of
"1,$".
5.1 Mode_Lines
Mode lines are a little-known, but often useful, feature of
vi. To use this feature, special strings are placed in the
first or last five lines in a file. When the file is
edited, these strings are detected and processed as though
typed as a colon command. One instance where this can be
useful is to set the "tabstop" parameter on a per-file
basis. The following are examples of mode lines:
vi:set ts=4 noai:
ex:45:
Mode lines are characterized by the string "vi" or "ex" fol-
lowed by a command surrounded by colons. Other text may
appear on the line, and multiple mode lines may be present.
No guarantee is made regarding the order in which multiple
mode lines will be processed.
The processing of mode lines is enabled by setting the "ml"
parameter. This should be done in the "EXINIT" environment
variable, so that mode line processing is enabled as soon as
the editor begins. By default, mode lines are disabled for
security reasons.
�
5.2 The_Global_Command
A limited form of the global command is supported, accepting
the following command form:
g/pattern/X
where X may be either 'd' or 'p' to delete or print lines
that match the given pattern. If a line range is given,
only those lines are checked for a match with the pattern.
If no range is given, all lines are checked.
If the trailing command character is omitted, 'p' is
assumed. In this case, the trailing slash is also optional.
The current version of the editor does not support the undo
operation following the deletion of lines with the global
command.
5.3 The_Substitute_Command
The substitute command provides a powerful mechanism for
making more complex substitutions than can be done directly
from visual mode. The general form of the command is:
s/pattern/replacement/g
Each line in the given range (or the current line, if no
range was given) is scanned for the given regular expres-
sion. When found, the string that matched the pattern is
replaced with the given replacement string. If the replace-
ment string is null, each matching pattern string is
deleted.
The trailing 'g' is optional and, if present, indicates that
multiple occurrences of 'pattern' on a line should all be
replaced.
Some special sequences are recognized in the replacement
string. The ampersand character is replaced by the entire
pattern that was matched. For example, the following com-
mand could be used to put all occurrences of 'foo' or 'bar'
within double quotes:
1,$s/foo|bar/"&"/g
The special sequence "\n" where 'n' is a digit from 1 to 9,
is replaced by the string the matched the corresponding
parenthesized expression in the pattern. The following com-
mand could be used to swap the first two parameters in calls
to the C function "foo":
1,$s/foo\(([^,]*),([^,]*),/foo(\2,\1,/g
Like the global command, substitutions can't be undone with
this version of the editor.
�
5.4 File_Manipulation_Commands
The following table shows the supported file manipulation
commands as well as some other 'ex' commands that aren't
described elsewhere:
:w write the current file
:wq write and quit
:x write (if necessary) and quit
ZZ same as ":x"
:e file edit the named file
:e! re-edit the current file, discarding changes
:e # edit the alternate file
:w file write the buffer to the named file
:x,yw file write lines x through y to the named file
:r file read the named file into the buffer
:n edit the next file
:N edit the previous file
:rew rewind the file list
:f show the current file name
:f name change the current file name
:x= show the line number of address 'x'
:ta tag go to the named tag
^] like ":ta" using the current word as the tag
:help display a command summary
:ve show the version number
:sh run an interactive shell
:!cmd run a command
The ":help" command can also be invoked with the <HELP> key
on the Atari ST. This actually displays a pretty complete
summary of the real vi with unsupported features indicated
appropriately.
The commands above work pretty much like they do in 'vi'.
Most of the commands support a '!' suffix (if appropriate)
to discard any pending changes.
6. String_Searches
String searches are supported, as in vi, accepting the usual
regular expression syntax. This was done using a modified
form of Henry Spencer's regular expression library. I added
code outside the library to support the '\<' and '\>' exten-
sions. The parameter "ignorecase" can be set to ignore case
in all string searches.
�
7. Operators
The vi operators (d, c, y, !, <, and >) work as true opera-
tors. The tilde command may also be used as an operator if
the parameter "tildeop" has been set. By default, this
parameter is not set.
8. Tags
Tags are implemented and a fairly simple version of 'ctags'
is supplied with the editor. The current version of ctags
will find functions and macros following a specific (but
common) form. See 'ctags.doc' for a complete discussion.
9. System-Specific_Comments
The following sections provide additional relevant informa-
tion for the systems to which STEVIE has been ported.
9.1 Atari_ST
9.1.1 TOS The editor has been tested in all three resolu-
tions, although low and high res. are less tested than
medium. The 50-line high res. mode is currently not imple-
mented.
The function keys, as well as SHIFT-function keys, may be
mapped by the user to execute command macros. The function
keys are disabled in insert mode.
The arrow keys, as well as the <INSERT>, <HELP>, and <UNDO>
keys are all mapped appropriately.
9.1.2 Minix The editor is pretty much the same under
Minix, but many of the keyboard mappings aren't yet sup-
ported.
9.2 UNIX
The editor has been ported to UNIX System V release 3 as
well as 4.2 BSD. This was done mainly to get some profiling
data so I haven't put much effort into doing the UNIX ver-
sion right. While the termcap routines are supported, the
editor is still fairly picky about the capabilities it wants
and makes little effort to do clever things with less intel-
ligent terminals.
�
9.3 OS/2
This port was done because the editor that comes with the
OS/2 developer's kit really stinks. Make sure 'ansi' mode is
on (using the 'ansi' command). The OS/2 console driver
doesn't support insert/delete line, so STEVIE bypasses the
driver and makes the appropriate system calls directly.
This is all done in the system-specific part of the editor
so the kludge is at least localized.
The arrow keys, page up/down and home/end all do what you'd
expect. The function keys are hard-coded to some useful mac-
ros until I can get true support for macros into the editor.
The current mappings are:
F1 :N <RETURN>
F2 :n <RETURN>
F3 :e # <RETURN>
F4 :rew <RETURN>
F5 [[
F6 ]]
F7 Convert C declaration to pseudo-english (uses cdecl)
F8 Convert english-style declaration to C (uses cdecl)
F9 :x <RETURN>
F10 :help <RETURN>
S-F1 :N! <RETURN>
S-F2 :n! <RETURN>
The macros for F7 and F8 assume that the "cdecl" program is
available.
9.4 MSDOS
STEVIE has been ported to MSDOS 3.3 using the Microsoft C
compiler, version 5.1. The keyboard mappings are the same
as for OS/2. The only problem with the PC version is that
the inefficiency of the screen update code becomes painfully
apparent on slower machines.
The DOS version requires the use of an extended console
driver that can insert and delete lines. The distributed
code uses "nansi.sys" which seems to be widely available.
10. Configuration_File
When STEVIE is executed from the desktop, it will attempt to
load in commands from a configuration file in the default
directory. The configuration file must be named either
STEVIE.INF or VI.INF. If both files exist, then only the
STEVIE.INF file will be read and executed. The configura-
tion file is used to initialize all of the "set" commands,
as well as any other colon prompt command.
EXAMPLE STEVIE.INF FILE:
set ai nu
set shiftwidth=4
�
11. Missing_Features
1. The ability to edit files larger than the available
memory. This isn't a problem on the machines I use,
but it hits the Minix-PC people pretty hard.
2. More "set" options.
3. Many others...
12. Known_Bugs_and_Problems
1. The yank buffer uses statically allocated memory, so
large yanks will fail. If a delete spans an area
larger than the yank buffer, the program asks for con-
firmation before proceeding. That way, if you were
moving text, you don't get screwed by the limited yank
buffer. You just have to move smaller chunks at a
time. All the internal buffers (yank, redo, etc.)
need to be reworked to allocate memory dynamically.
The 'undo' buffer is now dynamically allocated, so any
change can be undone.
2. If you stay in insert mode for a long time, the insert
buffer can overflow. The editor will print a message
and dump you back into command mode.
3. The current version of the substitute and global com-
mands (i.e. ":s/foo/bar" or ":g/foo/d") can't be
undone. This is due to the current design of the undo
code. To undo these commands would generally involve
unreasonable amounts of memory.
4. Several other less bothersome glitches...
�
13. Conclusion
The editor has reached a pretty stable state, and performs
well on the systems I use it on, so I'm pretty much in
maintenance mode now. There's still plenty to be done; the
screen update code is still pretty inefficient and the
yank/put code is still primitive. I'm still interested in
bug reports, and I do still add a new feature from time to
time, but the rate of change is way down now.
I'd like to thank Tim Thompson for writing the original ver-
sion of the editor. His program was well structured and
quite readable. Thanks for giving me a good base to work
with. Thanks also to many users of STEVIE who have sent in
their changes. Many of the changes I've received aren't
portable to all the systems I support, but I'm working to
get portable implementations integrated into the editor
where possible.
If you're reading this file, but didn't get the source code
for STEVIE, it can be had by sending a disk with return pos-
tage to the address given below. I can write disks for the
Atari ST (SS or DS) or MSDOS (360K or 1.2M). Please be sure
to include the return postage. I don't intend to make money
from this program, but I don't want to lose any either.
Tony Andrews UUCP: onecom!wldrdg!tony
5902E Gunbarrel Ave.
Boulder, CO 80301
�
Character_Function_Summary
The following list describes the meaning of each character
that's used by the editor. In some cases characters have
meaning in both command and insert mode; these are all
described.
^@ The null character. Not used in any mode. This char-
acter currently may not be present in the file.
^B Backward one screen.
^D In command mode, scroll the window down one half
screen. In insert mode, backtab over and delete a
shiftwidth amount of the autoindent space (only
works in non-white characters have not yet been
typed on the current line).
^E Scroll the screen up one line.
^F Forward one screen.
^G Same as ":f" command. Displays file information.
^H (Backspace) Moves cursor left one space in command
mode. In insert mode, erases the last character
typed.
^I Same as a tab character.
^J Move the cursor down one line.
^L Clear and redraw the screen.
^M (Carriage return) Move to the first non-white char-
acter in the next line. In insert mode, a carriage
return opens a new line for input.
^N Move the cursor down a line.
^P Move the cursor up a line.
^T In insert mode, tab forward by shiftwidth. This
operation only works, if non-white text has not yet
been typed on the current line.
^U Scroll the window up one half screen.
^V Embed a control character into the text file during
insert mode. ^V must be immediately followed by the
character to be embedded (null characters cannot be
embedded, yet).
�
^W Erase the last word that was typed during insert
mode. Can be used repeatedly for all of the words
on the current line that were entered during the
current insert session. Does not work once insert
mode is terminated. This function is similar to ^H,
except with entire words (as VI defines words).
^Y Scroll the screen down one line.
^[ Escape cancels a pending command in command mode,
ESC and is used to terminate insert mode.
^] Moves to the tag whose name is given by the word in
which the cursor resides.
^` Same as ":e #" if supported (system-dependent).
SPACE Move the cursor right on column.
! The filter operator always operates on a range of
lines, passing the lines as input to a program, and
replacing them with the output of the program. The
shorthand command "!!" can be used to filter a
number of lines (specified by a preceding count).
The command "!" is replaced by the last command
used, so "!!!<RETURN>" runs the given number of
lines through the last specified command.
$ Move to the end of the current line.
% If the cursor rests on a paren '()', brace '{}', or
bracket '[]', move to the matching one.
( Retreat to the beginning of a sentence. A sentence
ends with a . (period), ! (exclamation), or ?
(question) and is followed by either the end of a
line or by two spaces. The following characters are
ignored when locating sentences: (, ), [, ], ", ',
and tab characters. An empty line fulfills the
requirement of a sentence, however, the cursor will
only be moved to the topmost line in a group of
empty lines.
) Advances to the beginning of a sentence. See ( above
for the definition of a sentence.
' (single quote) Used to move the cursor to a previ-
ously marked position, as in 'a or 'b. The cursor
moves to the start of the marked line. The special
mark '' refers to the "previous context".
+ Same as carriage return, in command mode.
, (comma) Reverse of the last t, T, f, or F command.
- (dash) Move to the first non-white character in the
previous line.
�
. Repeat the last edit command.
/ Start of a forward string search command. String
searches may be optionally terminated with a closing
slash. To search for a slash use '\/' in the search
string.
0 Move to the start of the current line. Also used
within counts.
1-9 Used to add 'count' prefixes to commands.
: Prefix character for "ex" commands.
; Repeat last t, T, f, or F command.
< The 'left shift' operator.
> The 'right shift' operator.
? Same as '/', but search backward.
A Append at the end of the current line.
B Backward one blank-delimited word.
C Change the rest of the current line.
D Delete the rest of the current line.
E End of the end of a blank-delimited word.
F Find a character backward on the current line.
G Go to the given line number (end of file, by
default).
H Move to the first non-white char. on the top screen
line.
I Insert before the first non-white char. on the
current line.
J Join two lines.
L Move to the first non-white char. on the bottom
screen line.
M Move to the first non-white char. on the middle
screen line.
N Reverse the last string search.
O Open a new line above the current line, and start
inserting.
P Put the yank/delete buffer before the current cursor
position.
�
Q Quit to the ":" prompt.
R Replace characters until an "escape" character is
received. Similar to insert mode, but replaces
instead of inserting. Typing a newline in replace
mode is the same as in insert mode, but replacing
continues on the new line.
T Reverse search 'up to' the given character.
U Restore the current line to its state before you
started changing it.
W Move forward one blank-delimited word.
X Delete one character before the cursor.
Y Yank the current line. Same as 'yy'.
ZZ Exit from the editor, saving changes if necessary.
[[ Move backward one C function.
]] Move forward one C function.
^ Move to the first non-white on the current line.
` Move to the given mark, as with '. The distinction
between the two commands is important when used with
operators. I support the difference correctly. If
you don't know what I'm talking about, don't worry,
it won't matter to you.
a Append text after the cursor.
b Back one word.
c The change operator.
d The delete operator.
e Move to the end of a word.
f Find a character on the current line.
h Move left one column.
i Insert text before the cursor.
j Move down one line.
k Move up one line.
l Move right one column.
m Set a mark at the current position (e.g. ma or mb).
n Repeat the last string search.
�
o Open a new line and start inserting text.
p Put the yank/delete buffer after the cursor.
r Replace a character.
s Replace characters.
t Move forward 'up to' the given character on the
current line.
u Undo the last edit.
w Move forward one word.
x Delete the character under the cursor.
y The yank operator.
z Redraw the screen with the current line at the top
(zRETURN), the middle (z.), or the bottom (z-).
{ Retreats to the beginning of the preceding para-
graph. A paragraph is a series of text lines that
begins after either a completely empty line or a
line that just contains spaces and tabs.
| Move to the column given by the preceding count.
} Advance to the beginning of the next paragraph. See
{ above for the definition of a paragraph.
~ Invert the case of the current character (if alpha)
and move to the right. If the parameter "tildeop"
is set, this command functions as an operator.
�
STEVIE - User Guide
CONTENTS
1. Overview........................................... 1
2. Starting the Editor................................ 2
3. Set Command Options................................ 2
4. Function Key Mapping............................... 5
4.1 Defining Macros............................... 5
4.2 Unmapping Macros.............................. 6
4.3 Listing Macros................................ 6
5. Colon Commands..................................... 7
5.1 Mode Lines.................................... 7
5.2 The Global Command............................ 8
5.3 The Substitute Command........................ 8
5.4 File Manipulation Commands.................... 9
6. String Searches.................................... 9
7. Operators.......................................... 10
8. Tags............................................... 10
9. System-Specific Comments........................... 10
9.1 Atari ST...................................... 10
9.2 UNIX.......................................... 10
9.3 OS/2.......................................... 11
9.4 MSDOS......................................... 11
10. Configuration File................................. 11
11. Missing Features................................... 12
12. Known Bugs and Problems............................ 12
13. Conclusion......................................... 13
Character Function Summary.............................. 14