home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The C Users' Group Library 1994 August
/
wc-cdrom-cusersgrouplibrary-1994-08.iso
/
vol_300
/
313_01
/
stevie.doc
< prev
next >
Wrap
Text File
|
1990-04-22
|
33KB
|
1,123 lines
STEVIE - An Aspiring VI Clone
User Reference - 3.71
Tony Andrews
1. _O_v_e_r_v_i_e_w
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.
- 1 -
STEVIE User Reference
2. _S_t_a_r_t_i_n_g__t_h_e__E_d_i_t_o_r
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. _S_e_t__C_o_m_m_a_n_d__O_p_t_i_o_n_s
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:
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.
- 2 -
STEVIE User Reference
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.
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.
- 3 -
STEVIE User Reference
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. _C_o_l_o_n__C_o_m_m_a_n_d_s
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,$".
- 4 -
STEVIE User Reference
4.1 _M_o_d_e__L_i_n_e_s
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.
4.2 _T_h_e__G_l_o_b_a_l__C_o_m_m_a_n_d
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.
4.3 _T_h_e__S_u_b_s_t_i_t_u_t_e__C_o_m_m_a_n_d
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
- 5 -
STEVIE User Reference
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.
4.4 _F_i_l_e__M_a_n_i_p_u_l_a_t_i_o_n__C_o_m_m_a_n_d_s
The following table shows the supported file manipulation
commands as well as some other 'ex' commands that aren't
described elsewhere:
- 6 -
STEVIE User Reference
: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.
5. _S_t_r_i_n_g__S_e_a_r_c_h_e_s
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 -
STEVIE User Reference
6. _O_p_e_r_a_t_o_r_s
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.
7. _T_a_g_s
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.
8. _S_y_s_t_e_m_-_S_p_e_c_i_f_i_c__C_o_m_m_e_n_t_s
The following sections provide additional relevant informa-
tion for the systems to which STEVIE has been ported.
8.1 _A_t_a_r_i__S_T
8.1.1 _T_O_S 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 can be used by setting
the 'lines' parameter to 50. Alternatively, the environment
variable 'LINES' can be set. The editor doesn't actively set
the number of lines on the screen. It just operates using
the number of lines it was told.
The arrow keys, as well as the <INSERT>, <HELP>, and <UNDO>
keys are all mapped appropriately.
8.1.2 _M_i_n_i_x The editor is pretty much the same under
Minix, but many of the keyboard mappings aren't yet sup-
ported.
8.2 _U_N_I_X
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.
Job control is supported on BSD systems.
- 8 -
STEVIE User Reference
8.3 _O_S_/_2
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.
8.4 _M_S_D_O_S
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.
9. _M_i_s_s_i_n_g__F_e_a_t_u_r_e_s
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.
- 9 -
STEVIE User Reference
2. Macros with support for function keys.
3. More "set" options.
4. Many others...
10. _K_n_o_w_n__B_u_g_s__a_n_d__P_r_o_b_l_e_m_s
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...
- 10 -
STEVIE User Reference
11. _C_o_n_c_l_u_s_i_o_n
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: uunet!dunike!onecom!raid5!tony
5902E Gunbarrel Ave.
Boulder, CO 80301
- 11 -
STEVIE User Reference
_C_h_a_r_a_c_t_e_r__F_u_n_c_t_i_o_n__S_u_m_m_a_r_y
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 may not be present in the file, as is the case
with vi.
^B Backward one screen.
^D Scroll the window down one half screen.
^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.
^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.
^U Scroll the window up one half screen.
^Y Scroll the screen down one line.
^[ Escape cancels a pending command in command mode,
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).
- 12 -
STEVIE User Reference
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.
' Used to move the cursor to a previously marked posi-
tion, 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.
, Reverse of the last t, T, f, or F command.
- Move to the first non-white character in the previ-
ous 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.
- 13 -
STEVIE User Reference
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.
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 'upto' the given character.
U Restore the current line to its state before you
started changing it.
W Move forward one blank-delimited word.
- 14 -
STEVIE User Reference
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.
- 15 -
STEVIE User Reference
s Replace characters.
t Move forward 'upto' 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-).
| Move to the column given by the preceding count.
~ 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.
- 16 -
STEVIE - User Guide
CONTENTS
1. Overview........................................... 1
2. Starting the Editor................................ 2
3. Set Command Options................................ 2
4. Colon Commands..................................... 4
4.1 Mode Lines.................................... 5
4.2 The Global Command............................ 5
4.3 The Substitute Command........................ 5
4.4 File Manipulation Commands.................... 6
5. String Searches.................................... 7
6. Operators.......................................... 8
7. Tags............................................... 8
8. System-Specific Comments........................... 8
8.1 Atari ST...................................... 8
8.2 UNIX.......................................... 8
8.3 OS/2.......................................... 9
8.4 MSDOS......................................... 9
9. Missing Features................................... 9
10. Known Bugs and Problems............................ 10
11. Conclusion......................................... 11
Character Function Summary.............................. 12
- i -
