C/C++ Interactive Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource5 / 313_01 / stevie.doc < prev next >

Wrap

Text File | 1990-04-23 | 32.3 KB | 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 -