Y
A Programmer's Text Editor
==========================

Version 1.0
(C) Copyright 1991 by Peter Chapin


User Documentation
Printed: April 21, 1991






Table Of Contents
=================

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Registration Information . . . . . . . . . . . . . . . . . . . . 1

Invoking and Terminating Y . . . . . . . . . . . . . . . . . . . 2

Editor Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 5

Keyboard Handler . . . . . . . . . . . . . . . . . . . . . . . . 6

Parameter Handler . . . . . . . . . . . . . . . . . . . . . . . . 8

Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Text Creation and Destruction . . . . . . . . . . . . . . . 10
Cursor Movement . . . . . . . . . . . . . . . . . . . . . . 12
Standard Function Keys . . . . . . . . . . . . . . . . . . . 13
Alt+Function Keys . . . . . . . . . . . . . . . . . . . . . 17
Cntrl+Function Keys . . . . . . . . . . . . . . . . . . . . 19
Shift+Function Keys . . . . . . . . . . . . . . . . . . . . 21
Alt+Letter Keys . . . . . . . . . . . . . . . . . . . . . . 22

APPENDIX 1: Limits . . . . . . . . . . . . . . . . . . . . . . . 23

APPENDIX 2: Sorry, OUT OF MEMORY . . . . . . . . . . . . . . . . 23

APPENDIX 3: Format of FILELIST.YFY . . . . . . . . . . . . . . . 24

APPENDIX 4: File Extensions . . . . . . . . . . . . . . . . . . . 26

APPENDIX 5: Future Directions . . . . . . . . . . . . . . . . . . 28
















i





Introduction
============

Y is yet another programmer's text editor. I wrote it anyway.

I wanted an editor with source code I could understand, that I could
modify legally, and that would be useful to both myself and the
students at Vermont Technical College (where I teach). I wanted an
editor that was reasonably fast, compact, and powerful.

Some of Y's nicer features include:

1. Y operates on text files in a natural way for manipulating line
oriented program source code.

2. Y can load and manipulate multiple files.

3. Y grants extensive access to operating system resources. External
programs can be used by Y to manipulate the files (or portions of
the files) you are editing. By writing special purpose programs,
you can extend the abilities of Y considerably.

4. Y automatically saves files before changes are lost, and
automatically refreshes files from disk when the disk versions
are modified by external programs.

5. Y can save a list of the files which you are editing when you
exit. When you restart Y, it can automatically reload all the
files you were working with, letting you pick up your work where
you left off.

Comments, bug reports, etc are welcome. Please send them to

Peter Chapin
P.O. Box 317
Randolph Center, VT 05061
[email protected]

Registration Information
========================

Y in its current form was developed during the period ranging from
Summer 1990 through Spring 1991. It is written in a combination of
C++, C, and 8086 Assembly Language using Borland International's Turbo
C++ Professional (Version 1.0).

Y's executable file, its source code, and it's documentation are
copyrighted works. However, I grant permission for the executable
file (Y.EXE) and the user documentation (YUSER.DOC) to be copied
freely, for any purpose, provided they are not modified, not
separated, and nothing more than a nominal handling fee is charged for
each copy.

1






If you send me $30.00, I will send you the most recent version of Y
available and the complete source code for that version. Furthermore,
for your $30.00, I will grant you permission to produce a custom
version of Y which you may distribute throughout your organization,
but no further. In addition, I will grant you permission to use the
source modules of Y in your own, unrelated, software. In such a case I
do not ask for royalties unless you distribute the source code (and
hence my copyrighted material) of your software.

If you are interested in a custom version of Y but don't have the time
or expertise to produce one yourself, I may be able, for a fee, to
produce a custom version for you. Don't hesitate to contact me if this
possibility interests you.

Disclaimer

Peter Chapin makes no warranty of any kind, either express or implied,
including but not limited to implied warranties of merchantability and
fitness for a particular purpose with respect to this software, its
source code, and accompanying documentation.

IN NO EVENT SHALL PETER CHAPIN BE LIABLE FOR ANY DAMAGES (INCLUDING
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF
BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE
OF OR INABILITY TO USE THIS PROGRAM OR ITS SOURCE CODE, EVEN IF PETER
CHAPIN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


Invoking and Terminating Y
==========================

Y can be invoked by simply typing its name at the keyboard as in

A:\>y

In this case, Y does the following:

1. Searches the current directory for the file FILELIST.YFY. If it
is found, Y will reload all the files so indicated in
FILELIST.YFY and adjust all their attributes accordingly. In this
way, Y lets you resume your work where you left off when you last
exited the editor using the Alt+Y command.

2. If FILELIST.YFY cannot be found or if it was produced by a
different version of Y, the editor will prompt you for a
filename. You may provide the name of new file or of an existing
file. You may provided a wildcard sequence (in which case all
matching files will be loaded). If you attempt to ESC out of the
initial prompt, Y will abort with an error message. Y must have a
filename before it will allow you to edit.


2





One or more filenames can be specified on the command line when Y is
invoked. In this case, FILELIST.YFY is ignored. For example

A:\>y first.c second.c third.c

Y will load all the named files (or create them if they don't exist)
and then display the first file in the list before accepting your
commands. The order the files are named on the command line will be
the same order used by the {Next_File} command (F3).

Wildcard characters are legal on the command line. Y will load all
matching files in the order that they appear in the "physical"
directory listing (from the DIR command). If no files match the wild
card specification, Y will produce a warning message. For example

A:\>y *.c x??.doc afile.txt

This command will cause Y to load all .c files, all files that match
the pattern x??.doc, and the file afile.txt. If, for example, there
are no files that match the pattern x??.doc, Y will produce a warning
message and then proceed to load afile.txt. If afile.txt does not
exist, Y assumes it is a new file.

You can force Y to jump immediately to a certain line in the file by
using the -L command line switch. For example

A:\>y -L10 first.c second.c -L1 third.c

Here, Y will position the cursor on line 10 for both the files first.c
and second.c. Y will position the cursor on line 1 of third.c. The -L
switch affects all files that are named after it on the command line
until overridden by another -L switch.

Also, you can force Y to jump immediately to a certain column in the
file by using the -C command line switch. For example

A:\>y -L10 -C40 first.c

Here, Y will position the cursor on line 10, column 40 of first.c.
Similar rules as for the -L switch apply.

A '/' can be used instead of a '-'. Both upper and lower case letters
are accepted for switches. Illegal switches will produce warning
messages.

Y can be terminated using the Alt+Y command, the Alt+X command, or the
Alt+Q command. Alt+Y is the normal way to terminate as it causes the
editor to save all files that have been changed and rewrite the file
FILELIST.YFY. When Alt+X is used, FILELIST.YFY is not written
(although changes are saved). When Alt+Q is used, changes will be lost
and FILELIST.YFY is not written.


3





Alt+Y is appropriate if you are editing several files in a big
project. Alt+X is appropriate if you are doing a "quick and dirty"
edit of a file and you don't want to disturb a previously saved
FILELIST.YFY. Alt+Q is appropriate if you want to dump all the changes
that you've made.


Editor Model
============

To use Y effectively, you must understand it's attitude. It is the
purpose of this section to discuss my mental model of Y.

Y does not have a configuration file. Similarly, Y does not have any
separate help files. The only file required to use Y is Y.EXE.
Furthermore, everybody's Y.EXE acts the same way.

Y does not do windows. Tiled windows are too small on the IBM PC
screen to be useful. Overlapping windows don't let you see several
things at the same time anyway. Instead, Y allows you to set a
bookmark and jump back and forth between your working point and the
bookmark.

Y does not make backup files. Y will save changes whenever the editor
is exited or whenever a file is removed from the list of active files.
Furthermore, Y will refresh an active file if it notices that the
disk version has been changed by an external program. Thus when you
change a file in Y, it is as though the change was made immediately to
the disk version of that file.

Y provides features which allow external programs access to the text
you are editing. Thus you can add custom features by writing your own
programs and directing Y to use them at the appropriate time. This
makes Y powerful without making it ungainly in size.

Y must have a file name before it will allow you to edit. It is
possible to start Y without specifying a file on the command line.
However, in such a situation Y either reads a previously saved list of
filenames or it prompts you for a filename.

Y is sensitive to the extension of the file you are editing. Certain
file attributes vary from file type to file type. Also certain
commands operate differently depending on the file type.

Y only allows you to define blocks which are totally line oriented. It
is not possible to define a block which contains only part of a line.
Many of the commands behave differently if block mode is on. This
behavior is documented below.





4





Messages
========

Y messages are displayed in a box in the center of the screen. There
are several types of messages.

Informational messages are unadorned. They are typically shown while Y
is doing something else, and will go away when Y is done. For example
"Reading program.c..." is an informational message that might be seen
when you start editing a file. Some informational messages are
displayed only long enough for you to read them and will disappear
after a set time (typically one second).

Query messages are also unadorned. They do, however, require some kind
of response from you. Generally, any key will get rid of the message.
However, only certain keys are likely to be special; all other keys
represent a default value which is shown to you in square brackets.
For example "Are you sure? y/[n]" is a query message with "no" as the
default. Only 'y' (or 'Y') will trigger the "yes" response. If a
query message has 'y' as the default, the ESC key can be used as an
alternate way to say 'n'.

Warning messages have the line "Warning" above them. These messages
wait for acknowledgment via the ESC key. They are shown when
something funny happened that you should probably know about, but that
does not represent a mistake on your part. For example, "Problems
writing program.c" is a warning message.

Error messages have the line "Sorry" above them. They occur when you
ask Y to do something it can't deal with. Typically an error message
implies that you requested an illegal operation. Y waits for
acknowledgment via the ESC key.

Internal error messages have the line "Bug Found!" above them. They
occur when Y has detected some internal inconsistency. The message
itself refers to objects in the source code and won't make much sense
until you look at the source code. Please let me know if you get any
of these messages -- they represent bugs.


File Attributes
===============

Each file that you edit has certain attributes associated with it. Y
maintains these attributes separately for each file. Furthermore, when
Y saves its state in response to the Alt+Y command, these attributes
are saved for each file. Y restores all of these attributes when
reloading files based on a previously saved state.

Current Point
The current point of the file defines where the cursor is located
in that file. The cursor is just after the current point. This is

5





the point where new text is inserted, etc. The current point does
not need to be in the actual text portion of the file. That is,
you are allowed to place the cursor, and insert text, anywhere
you want. Y automatically extends lines with spaces and/or adds
blank lines as necessary.

Color Attribute
This is the color used for the display when you are editing the
file.

Tab Stop
This is the number of columns between tabs for the file. Y uses
spaces for tabs. That is, spaces are inserted whenever a tab
character is encountered in a file during loading or when the tab
key is pressed during editing.

Be aware that when Y is reading a file from the disk, it will
always expand tabs as if the tab stop was set to 8. Similarly,
when Y writes a file to disk, it will entabify the file for a tab
stop setting of 8. This is because eight is the size used by MS-
DOS. The tab stop attribute for a file is used when you press the
tab key while editing that file.

Block Definition
This attribute defines whether or not block mode is on for the
file and if so, the starting line of the block. The ending point
of the block is always on the line containing the current point.
Blocks are totally line oriented; it is not possible to split a
line with a block or to form a block from part of a line.

In the current version of Y, this attribute is not saved in
FILELIST.YFY.

Insert/Replace Mode
If the file is in replace mode, text that you enter will
overwrite existing text. The cursor is shown as a "big block" to
indicate that this mode is active. Insert mode is the default.

Note that the commands which destroy characters and move the
cursor while in insert mode will just move the cursor while in
replace mode. For example, the {Backspace} command works in
replace mode much the same way as the {Cursor_Left} command.
Commands which destroy characters without moving the cursor, such
as {Delete_Char} and {Delete_To_EOL} will destroy characters in
both modes, however.


Keyboard Handler
================

The keyboard handler is a module of Y which performs the work of
reading key strokes. It is possible to send commands to the keyboard

6





handler without the rest of the program knowing it. These commands
always start with a control character. All of these keyboard commands
are described below.

^R - All Y commands can be prefixed with a repeat count. This is done
by first typing ^R followed by the number of times you wish the
command to repeat. When a command key (or letter) is then
struck, that command (or letter) is repeated as specified. Note
that when the repeat count is being entered, there is no
indication of that fact on the screen.

If you wish to repeat a digit character, you must prefix the
digit with ^Q (see below) to distinguish it from the count.

^K - This command allows you to define a keyboard macro. After typing
^K, Y will remember all your keystrokes until you type a closing
^K. These keystrokes can then be played back using ^E (see
below). Y will remember all types of keystrokes; letter keys,
function keys, etc will all be recorded.

The keyboard macro can contain up to 256 keystrokes; Y will warn
you if you try to exceed this limit.

^E - This command plays back (ie executes) a previously recorded
keyboard macro. You will see an error message if you try to play
back a macro without having defined one via the ^K command. You
will also see an error message if you try to use this command
while recording a keyboard macro. Keyboard macros cannot be
recursive.

^Q - This command allows you to "quote" a keystroke. Whatever key is
entered after this command will be placed literally into the
file. For example, the sequence ^Q^[ will place a ^[ character
(an ESC) into the file. This command works for all keys, however
it must be used to enter ^E, ^I (TAB), ^J (LF), ^K, ^M (CR), ^Q,
^R, or ^[ (ESC) characters since those characters are normally
taken to be commands.

Note that Y will convert any ^J characters which appear in your
file into a CR/LF pair when the file is written to disk. Thus
forcing a ^J into the file will produce a result similar to
striking the RETURN key.

It is possible to use the ^R sequence together with the keyboard
macro. For example, a keyboard macro which contained the sequence
"^R1000+" (which prints one thousands '+' characters) is legal. In
particular, only six keystrokes of the 256 allowed are used rather
than overflowing the macro buffer with '+' characters.

It is possible to repeat the execution of the keyboard macro. For
example, a sequence like "^R10^E", repeats the keyboard macro ten
times. There is no problem repeating a keyboard macro which contains a

7





repeat sequence.

It is possible to repeatedly generate a quoted keystroke or to place
quoted keystrokes into the macro buffer. For example the sequence
"^R10^Q^[" places 10 ESCape characters into the active file. Note also
that something like "^R10^Q1" prints 10 '1' digits rather than
repeating the next keystroke 101 times.

Only one keyboard macro can be defined at a time. When you start to
define another keyboard macro, the previous macro, if any, is
forgotten.


Parameter Handler
=================

The parameter handler is the module of Y which is responsible for
reading parameters for the commands that require them (for example
file names, search patterns, etc). The parameter handler will open a
box in the center of the screen into which you type the parameter.

The parameter handler offers several features. These feature apply to
any command that takes a parameter.

Each input box maintains a list of the last eight parameters that were
entered into that box (some of the commands share input boxes).
Whenever the parameter handler displays an input box, the most recent
entry, if any, will be shown by default. You can simply type RETURN to
accept that entry at once. Alternatively, you may use the up and down
arrow keys to scroll through the list of previous entries. The up
arrow key scrolls back in time, while the down arrow key scrolls
forward in time.

If the first key you type when viewing a parameter is a printable
character, the parameter handler will erase whatever it's showing you
and start accepting your keystrokes. If the first key you type is not
a printable character, the parameter handler assumes you are trying to
edit what it is showing you.

Parameter editing works the same way editing works in the main file.
The home key, end key, and arrow keys (including Cntrl+Arrow keys)
work. Text can be inserted into the parameter at any time by just
typing. The INS key can be used to toggle parameter editing between
insert mode and replace mode (independently of the main file). The
RETURN key is used to accept the parameter. RETURN can be struck with
the cursor at any position.

You may enter parameters that are longer than the input box. The
parameter handler will scroll the text horizontally in the input box
as necessary. The parameter handler allows parameters with 64k
characters although most of the commands would not deal well with such
large parameters.

8






If you start editing a parameter and then decide to scroll through the
list of saved parameters with the up and down arrow keys, your edits
will be lost. You only commit to a parameter when you strike the
RETURN key.

When you do strike the RETURN key, the new parameter is put on the
head of the list associated with that input box. If there are already
eight items on the list, the last item is lost. If the new parameter
is the same as what is already at the head of the list, the list is
not changed.

The ESC key will abort whatever command invoked the parameter handler
and leave the list of saved parameters unchanged.

The parameter handler and keyboard handler are independent. Thus
typing "^R5{F1}" (where {F1} means the F1 key), will allow you to load
five files rather than try to load one file with a name given by four
F1 keystrokes. Furthermore, if {F1} is part of a keyboard macro, you
will be asked as the macro executes to enter a filename. You cannot
embed parameters inside the macro.


Commands
========

This section discusses all of Y's commands. In addition to the key
combination required to invoke it, all of the commands have names
which are enclosed in {...}. These names make talking about the
commands easier. In addition they will become important when (and if)
a macro language is added to Y.

The keystrokes used to invoke the commands are organized using the
following scheme:

Numeric keypad keys : Cursor movement.
Standard Function keys : Commonly used commands.
Alt+Function keys : Related to corresponding Fkey command.
Cntrl+Function keys : Other commands.
Shift+Function keys : Informational commands.
Alt+Letter keys : Uncommonly used commands.

In addition, function key commands are grouped into sets based on the
type of operation involved. For example, file manipulation is done
with F1-F4, bookmarks are handled with F5-F6, and external programs
are invoked with F10, Alt+F10, Cntrl+F10, or Shft+F10. The groupings
make the most sense on keyboards where the function keys are across
the top. They are not too bad on the older style keyboards, however.

Note that many of the commands refer to the "active file." This is the
file which is currently visible to the user of Y. In the current
version of Y, only the active file can be manipulated.

9







Text Creation and Destruction
-----------------------------

Printable {Print_Char}
When you strike any printable character (ie normal key), Y
inserts that character into the active file at the current point.
The current point is moved to the right. Insertions are allowed
anywhere -- even off the end of a line or off the end of the
file. Y extends the line and/or file as necessary.

If the active file is in replace mode (shown by the big block
cursor), the character under the cursor is replaced by the new
character and the current point is moved as described above.

Y will accept any characters, including control characters and
IBM extended ascii characters. The one exception is the null
character, ^@. Y uses this character internally at the end of
each line and it will become confused if you enter these
characters manually. The control characters which are used for
commands can be forced into the file by prefixing them with ^Q.

If block mode is active, the letter is inserted (or replaced) in
every line in the block at the same column position. This makes
it easy to manage tables using Y. You can also use it, for
example, to comment out a block of code quickly in languages that
have only single line comments. For example, in 8086 assembly
language, you can put a ';' at the start of every line by simply
forming a block and typing a single ';' at the start of one line.

For C/C++ files, the characters '{' and '}' are handled in a
special way. If the '{' is the last character on the line,
striking the RETURN key will cause an autoindent of one extra tab
stop. Also, if a '}' character is entered as the only character
on the current line, it is immediately outdented by one tab stop
to line up with an outer block. For example

int f()
{
/* Y indents to next level after {New_Line}. */
} /* Y outdents the '}' to match outer level block. */

This behavior does not occur if the file is in replace mode.

Delete {Delete_Char}
Deletes the character under the cursor. If the current point is
at or past the end of the line, this command joins the current
line with the next line. The cursor is not moved.

If block mode is active, this command deletes a character from
every line in the block. Line joining is not done.

10






This behavior is the same when the active file is in either
insert mode or replace mode. This is unusual. Most commands which
destroy text act differently when the file is in replace mode.

Backspace {Backspace}
Deletes the character to the left of the cursor. If the current
point is at the beginning of the line, this command joins the
current line with the previous line. The cursor moves to the
left.

If the active file is in replace mode, this command just moves
the current point. No character is deleted.

If block mode is active, this command deletes a character from
every line in the block.

Return {New_Line}
Inserts a new line after the line the current point is on. The
current point is moved to the start of the new line. If there
were characters on the original line to the right of the current
point, those characters become the part of the next line.

This command also does an autoindentation of the new line. Spaces
are added to move the current point under the first non blank
character of the line above the new line. If you did not want
this to occur you can undo the autoindentation with
Cntrl+Backspace.

If the active file is in replace mode, this command just moves
the current point (with autoindent), but no new line is created
and no text is moved.

C/C++ files are handled in a special way with regard to
{New_Line} and the '{' character. See {Print_Char} for more
information.

Cntrl+RETURN {Delete_To_EOL}
This command deletes from the current point to the end of the
line. The current point, and whatever is to the right of the
current point, is erased. If block mode is on, the command
deletes the tail of all lines in the block. The cursor is not
moved.

This behavior is the same when the active file is in either
insert mode or replace mode. This is unusual. Most commands which
destroy text act differently when the file is in replace mode.

Cntrl+Backspace {Delete_To_SOL}
This command deletes from the current point to the start of the
line. The current point, and whatever is to the right of the
current point, is moved over. If block mode is on, the command

11





deletes the first part of all lines in the block.

This command allows you to easily undo the autoindentation when
desired. If you strike the return key and get unwanted
autoindentation, just strike Cntrl+Backspace to remove it.

If the active file is in replace mode, this command just moves
the current point, but no text is deleted.

Insert {Toggle_Replace}
This command toggles the active file between insert mode and
replace mode. The cursor is shown as a big block for replace mode
and as a line for insert mode. Remember that each file loaded has
an independent mode flag. Thus you may be in insert mode for some
files and replace mode for others.


Cursor Movement
---------------

Right arrow {Cursor_Right}
Moves the current point to the right. The screen will scroll
horizontally if necessary.


Left arrow {Cursor_Left}
Moves the current point to the left. The screen will scroll
horizontally if necessary.


Cntrl+Right arrow {Word_Right}
Moves the current point to the start of the next word on the
current line (or the end of the current line if there are no more
words). Words are alphanumeric strings. Thus "Variable_Name"
contains two words. Also "23.14" contains two words.


Cntrl+Left arrow {Word_Left}
Moves the current point to the start of the previous word on the
current line (or the start of the current line if there are no
more words).


Up arrow {Cursor_Up}
Moves the current point up. The screen will scroll vertically if
necessary. The vertical scrolling is done 4 lines at a time.

In block mode, this command moves the current point as before and
changes the size of the block.




12





Down arrow {Cursor_Down}
The same story as with the up arrow.


Home {Start_Of_Line}
Moves the current point to the start of the current line.


End {End_Of_Line}
Moves the current point to the end of the current line.


Cntrl+Home {Top_Of_File}
Moves the current point to the top line of the file. The column
position of the current point is set to the start of the line.


Cntrl+End {End_Of_File}
Moves the current point to the first line just past the end of
the file. The column position of the current point is set to the
start of the line.


Cntrl+PgDn {Next_Procedure}
Moves the current point to the start of the next function or
procedure in the file. The screen is also adjusted so that the
cursor is on the second line from the top.

The exact method used to find the next procedure depends on the
extension of the active file (see Appendix 3 for details). Y
currently understands how to find procedures in Assembly language
(8086), C, C++, Pascal, Ada, and Modula-2 files. If you attempt
to find a procedure in a different file type, Y produces an error
message.

The methods used to find procedures are fairly simplistic and are
easily fooled. Thus, depending on the exact text in your file and
your style of programming, you may get either some spurious
cursor positionings or missed procedures. Completely correct
handling of this command is simply not worth the cost in terms of
program size and execution speed.


Cntrl+PgUp {Previous_Procedure}
Moves the current point to the start of the previous function or
procedure in the file. The screen is also adjusted so that the
cursor is on the second line from the top.


Standard Function Keys
----------------------


13





Several of the commands below involve reading and writing files. Y
follows several rules in that regard.

When a file is read from disk, tabs are converted to spaces assuming
that tab stops are every 8 characters (regardless of the tab stop
setting for the file type). While editing, Y does not normally deal
with tab characters. When a file is written to disk, trailing spaces
on each line are removed, and spaces at the start of each line are
converted back into tabs. In addition, all lines in the file are
terminated with a CR/LF pair as the file is written to disk.

These rules apply for all commands that manipulate disk files. Also,
these rules apply when blocks are being read or written as well.


F1 - {Find_File}
Use this command when you want to edit another file. You will be
prompted for a file name. If the file has already been loaded
into Y, you will be switched to it. Otherwise, Y tries to load
the file from disk. If Y fails, it assumes you want to edit a new
file.

When a file is loaded (or created) it goes into Y's list of
loaded files immediately after the active file. Thus using the
{Previous_File} command (Alt+F3) allows you to return to the file
you were working with immediately before invoking this command.

Wildcards may be used when specifying the file name. In that
case, all matching files are loaded. If there are no matching
files, Y will produce an error message.

If the new file is one which you have previously loaded during
the current editing session (but removed), or if it was described
in FILELIST.YFY, the old attributes of the file will be restored.


F2 - {Save_File}
This command writes the currently active file to disk. You don't
normally need to use this command as Y will write files to disk
automatically in most cases.

In block mode, you will be prompted for a file name. Y will write
only the lines specified in the block to the file.


F3 - {Next_File}
This command switches you to the next file in Y's list of loaded
files. By repeated invocations of this command, you can cycle
over all the files in the editor.




14





F4 - {Remove_File}
This command deletes the active file from Y's memory. If the file
has been changed, it is saved first. If the save fails, the
removal is aborted.

This command also remembers the attributes of the removed file so
that if you reload the file using the {Find_File} command, those
attributes can be restored. If you exit the editor with Alt+Y,
the attributes of all removed files will be saved in FILELIST.YFY
along with the attributes of the actively loaded files.


F5 - {Block_Toggle}
This command toggles block mode. Blocks are totally line
oriented; you cannot divide a line with a block. At least one
line will be in the block. Blocks are shown in reverse video on
the screen. Many of the commands act differently if block mode is
active.

The ESC key will shut off block mode and can be used as a
natural alternative to F5 in many cases.


F6 - {Cut}
This command deletes the current line. The entire line is deleted
regardless of the cursor position. The line is saved in a special
clipboard buffer for a later Paste command.

If block mode is active, the entire block is deleted and saved
in the clipboard buffer.

Note that the clipboard can only hold one deletion at a time.
Each time the Cut command is used, the old clipboard contents are
lost.


F7 - {Paste}
This command inserts whatever is currently in the clipboard
buffer into the active file above the cursor. Since the contents
of the clipboard buffer are line oriented (from the Cut command),
the insertion is also line oriented. In other words, the current
column position of the cursor is not considered.

Note that Cut and Paste allow for quick deletion, copy, and
movement of lines or blocks. Since the clipboard buffer is a
global entity, moving blocks from one file to another is trivial.

If block mode is on, the block is removed (forever) before the
insertion. The command thus acts more like a "Replace" command
in that case.



15





F8 - {Insert_File}
This command prompts for a file name and inserts that file above
the cursor in a manner similar to that of the Paste command.

If block mode is on, the block is removed (forever) before the
insertion.


F9 - {Goto_Line}
This command prompts for a line number and then moves the cursor
to the indicated line. The first line in the file is line 1.

Notice that you can use this command to form blocks between
specific line numbers. For example, if you wanted to form a block
between lines 100 and 200 (inclusive). You do

LINE NUMBER: 100
{ Toggle block mode }
LINE NUMBER: 200


F10- {External_Command}
This command prompts for a legal DOS command. The command can be
any string understood by COMMAND.COM. Batch files, I/O
redirection, and pipes are all legal. Y then saves any files that
have changed (assuming the external command may wish to reference
the files) and executes the external command. When the command is
finished, Y scans the disk to see if the external command
changed any of the files you are editing and, if so, refreshes
the versions being held in memory. Finally, Y allows you to read
the output of the command before returning you to the editor
screen.

This behavior is quite convenient. For example, suppose you are
editing a large program. You may, at some point try the external
command "make >errors.txt". When the command finishes, you can
load ERRORS.TXT into Y as another file. A little later, when you
want to try the make again, you simply type F10 and then RETURN
(Y remembers the last eight external commands you used). Not only
will Y save any changed files for you, it will also reload
ERRORS.TXT when the make command finishes.

If you strike the return key when prompted for a command, Y will
start a new copy of COMMAND.COM for you to use. This allows you
to enter as many commands as you like before returning to Y by
typing the "EXIT" command.

Be aware that Y uses date and time stamps to make its decisions
about which files to reload. If the external command changes the
date or time, Y could get confused.



16





Alt+Function Keys
-----------------

Alt+F1 {Refresh_File}
This command reads the disk again to bring a fresh copy of a file
into the editor. If the file has been changed, the changes will
be lost (you will be asked to confirm, however).

This command allows you to "start from scratch" if you badly
mangle a file. Be aware, however, that if you do anything which
causes Y to automatically save changes (remove the changed file
or execute an external program, for example), then this command
will just read the most recently saved version. This command will
not necessarily read the version of the file that existed when
you started Y.


Alt+F2 {Rename_File}
This command allows you to rename a file. It marks the file as
changed so that it will be saved under the new name when, for
example, you exit the editor.

If block mode is on, only the lines in the block will be retained
in the new file. The other lines are lost.

If a file with the new name already exists, either in the editor
or on disk, the text of the active file (or block) is inserted
into the existing file in the manner of the {File_Insert} command
(see below). This helps prevent accidental data loss.

If the new name has a new extension, Y adjusts its internal
records so that extension sensitive behavior is, of course,
changed. This operation requires that Y rebuild certain internal
data structures. Thus renaming large files may cause memory
overruns or surprising delays.


Alt+F3 {Previous_File}
This command switches you to the previous file in Y's list of
loaded files. By repeated invocations of this command, you can
cycle over all the files in the editor.


Alt+F4 {Kill_File}
This command removes the current file from the editor without
saving it if there were changes. You will be asked to confirm the
action if changes will be lost.

In block mode, only the lines in the block are removed. Nothing
is saved. The lines cannot be restored (as is possible with the
Cut command).


17






Alt+F6 {Copy_Block}
This command copies the currently active block (or line if there
is no block) to the clipboard for a later paste operation. This
command differs from "Cut Block" in that the source file is not
changed (and need not be resaved when Y is exited).

As with the Cut Block command, this command destroys the previous
contents of the clipboard.


Alt+F8 {File_Insert}
This command prompts you for a file name and inserts the current
file into the specified file. If the specified file does not
exist, Y assumes that you wish to create it. If the specified
file does exist, Y will load that file and insert the active file
above the first line in the specified file. If the specified file
is already loaded, Y will insert the active file above the
current line in the specified file.

If block mode is on, only the lines in the block will be
inserted. Furthermore, the block is deleted (forever) from the
active file.

In any case, the specified file becomes the active file.

The clipboard is not used. Material that has been saved on the
clipboard will remain after a {File_Insert} command.

This command is the fast way of chopping a block out of an
existing file and putting it into another file to edit. This
command abbreviates the operation of creating a new file, cutting
a block to the clipboard, switching to the new file, and then
pasting the clipboard into that file. Furthermore, it doesn't
change the clipboard.


Alt+F9 {Goto_Column}
This command allows you to jump to a specified column on the
current line. The first column is column 1.


Alt+F10 {External_Filter}
This command prompts for an external filter command. Y then
writes the active file to a temporary file named STDIN$.TMP and
invokes the specified filter command with " >STDOUT$.TMP" appended to the end of it. When the command
finishes, Y asks you if you wish replacement. If you answer
"yes," Y will replace the active file with STDOUT$.TMP. In any
case, Y will finally remove the two temporary files.

As usual, Y will save all changed files before invoking the

18





filter. Y will also reload any files that are changed by the
filter.

If block mode is on, only the block is written to STDIN$.TMP and
only the block is replaced with STDOUT$.TMP.

Y will abort the command if an error is encountered during the
write of STDIN$.TMP. Y depends on you to tell it if STDOUT$.TMP
is ok or not. If the filter encounters errors, respond with "no"
to Y's request for doing replacement.

This behavior allows you to use external filter programs,
possibly of your own making, to extend to abilities of Y. For
example, if you have a number of lines you wish sorted, simply
form a block out of them and invoke this command with the filter
"sort". Y will then use the external sort program to sort the
lines.


Cntrl+Function Keys
-------------------

Cntrl+F1 {Search_First}
This command will prompt you for a search string. It will then
scan the text of the active file from the cursor forward looking
for the first matching point in the file. Y will position the
cursor at the beginning of the match if there is one, or display
"Not found" if there is not.


Cntrl+F2 {Search_Next}
This command searches for the next occurrence of the string that
was previously entered via the {Search_First} command. Y will
position the cursor at the beginning of the next match if there
is one, or display "Not found" if there is not.


Cntrl+F3 {Search_Replace}
This command will prompt you for a search string and a replace
string. It will then scan the text of the active file from the
cursor forward looking for the first matching point in the file.
A message is then displayed asking if you wish to do the
replacement. You have several options:

'Y' YES. The default. Do replacement and continue.
'N' NO. Skip the replacement and continue.
'A' ALL. Do this replacement and all others.
ESC ESCAPE.

The 'A' option will do all replacements with no further queries.
Use this option cautiously.


19





When a search and replace session is over, Y will return the
cursor the point where it was when you invoked this command. This
allows you to do multiple search and replaces from the same point
without having bother with a bookmark.

If block mode is on, the search and replace operation will only
be done over the lines in the block. This will be true regardless
of the cursor position. That is, even if the cursor is on the
last line of the block or on the first line, but after the first
match, all matches in the block will be presented to you.


Cntrl+F5 {Set_Bookmark}
This command causes Y to remember the current file, cursor
position, and screen layout. You can later jump to this
"bookmark" position quickly -- even from another file. Only one
bookmark is allowed. Note that bookmarks are remembered based on
line number; if text is added above a remembered bookmark, the
bookmark will appear to move relative to the text. (I admit that
this isn't desirable, but it was easy, and it isn't a problem in
practice)

If the file containing the bookmark is removed, the bookmark is
forgotten.


Cntrl+F6 {Toggle_Bookmark}
This command exchanges the current point with that remembered in
the bookmark. Because this is an exchange, you can jump back to
your original position by simply typing Cntrl+F6 again. There is
no problem if the bookmark is in another file or in the same
file. You will an error message if the file which contained the
bookmark was removed, renamed, or if you've never set the
bookmark.


Cntrl+F10 {Redirect_From}
This command prompts for an external command. Y invokes the
command with the string ">STDOUT$.TMP" appended to the end of it.
When the command finishes, Y asks if you wish to do the
insertion. If you answer "yes," Y will insert STDOUT$.TMP into
the active file in a manner similar to that used by the
{Insert_File} command. Finally, Y will remove the temporary file.

As usual, Y will save all changed files before invoking the
command. Y will also refresh any files that are changed by the
command.

If block mode is on, the block is removed (forever) before any
insertion takes place.

This command makes it easy to imbed the output of a DOS command

20





into the file your are editing. It is particularly useful in
connection with special programing tools that can generate code
or code fragments.


Shift+Function Keys
-------------------

Shft+F1 {Help}
The on-line help system is self contained. Y does not require any
supporting files to use. The first help screen shown gives an
overview of help commands.


Shft+F2 {Editor_Info}
This command simply displays some facts about Y that may or may
not be interesting to you. Acknowledgements are also shown here.


Shft+F3 {Registration_Info}
This command shows text which explicitly grants permission to
make copies of Y and of this document. Also instructions for
obtaining the source code of Y, along with a disclaimer of
warranty are shown.


Shft+F10 {Redirect_To}
This command prompts for an external command. Y then writes the
active file to a temporary file named STDIN$.TMP and invokes the
specified command with " When the command finishes, you must strike a key to return to Y.
Finally, Y will remove the temporary file.

As usual, Y will save all changed files before invoking the
command. Y will also reload any files that are changed by the
command.

Y will abort the command if an error is encountered during the
write of STDIN$.TMP.

If block mode is on, only the specified block is written to
STDIN$.TMP. When the command finishes, block mode IS NOT turned
off. This allows several applications of this command to be
applied to the same block easily.

The behavior of this command allows you to use external programs
to analyze your text, but not change it. For example, regular
expression searches could be handled using GREP. As another
example, I have a brace checking program which accepts a file
through its standard input. Using this Y command, I can use that
program to check the brace matching for a whole file or for just
an individual function, etc.

21








Alt+Letter Keys
---------------

Alt+B {Background_Color}
This command allows you to change the background color of the
current file. Each time you invoke this command, the color cycles
to the next one in the list of possible colors.


Alt+F {Foreground_Color}
This command allows you to change the foreground color in a
manner similar to the {Background_Color} command.


Alt+Q {Quit}
This command quits the editor in the emergency mode. Files that
have been changed ARE NOT saved. If there have been changed
files, you are asked to confirm the action.


Alt+R {Reformat_Paragraph}
This command tidies lines in text paragraphs. If the first line
of the paragraph is indented at all, the indentation is adjusted
to 5 spaces. If the first line is not indented, it will remain
unindented. Long lines are wrapped to the next line and short
lines are filled. Extra lines are introduced as necessary.

The cursor can be anywhere in the paragraph when this command is
invoked. The entire paragraph is adjusted. Block mode does not
need to be on.

Paragraphs are block of text for which each line begins with a
letter, a digit, or certain punctuation marks. The first line of
the paragraph may begin with a space.

This command is very useful for editing comments.


Alt+T {Set_Tab}
This command allows you to set the distance between tab stops for
the active file.


Alt+X {Exit}
This command exits the editor. Files that have been changed are
saved. If one of the save operations fail, Y will try to do all
the other save operations and then abort the exit command. You
can use Quit (Alt+Q) if you really need to quit in this case.


22






Alt+Y {YExit}
This command exits the editor. It performs all the operations of
Alt+X but it additionally saves FILELIST.YFY to reflect Y's
current state. Note that FILELIST.YFY is actually saved before
any of the working files are saved. This is significant if you
are editing FILELIST.YFY as one of the working files.



APPENDIX 1: Limits
==================

Y suffers from the following numerical limits. A number of the limits
are only imposed by available memory. The current version of Y does
not attempt to swap material between memory and disk files or between
conventional memory and EMS memory.

Minimum memory required : About 128 KBytes.
Number of files loaded : Limited by memory.
Number of lines loaded : Limited by memory.
Number of bytes loaded : Limited by memory.
Length of each line : 64 KBytes minus small overhead.
Length of parameters : 64 KBytes minus small overhead.

Files loaded into Y require about twice the memory as their size on
the disk plus 5000 bytes. This is due to the 32 byte overhead Y incurs
on each line, the fact that Y expands tabs in the file into spaces,
and the data structures Y builds to support each file.

If you are using Y on a PC with 640 KBytes of RAM and a small number
of memory resident options, the maximum sized file you can load is
probably in the range of 200 KBytes. Alternatively, you can load
probably 50 to 60 extremely small files (ie one line batch files)
before running out of memory.


APPENDIX 2: Sorry, OUT OF MEMORY
================================

If Y runs out of memory it tries to do the following things

1. Tell you. In most cases, you will see an OUT OF MEMORY message
appear as soon as Y fails to allocate the memory it needs. The
message will contain some information about the consequences of
the lack of memory. For example, you may see, "Can't extract
entire block," if you attempt to cut a block with no memory left.

2. Not crash. Y should continue to run if it runs out of memory.
Most editing operations will, however, no longer work. In
addition, the input boxes used by the parameter handler will not
appear (thus any command which takes a parameter will be

23





disabled), external commands cannot be used, and files cannot be
saved.

On the other hand, you will still be able to page through the
text, view the help screens, delete text with the delete and
backspace keys, and, most importantly, remove files.

3. Avoid loss of data. If Y runs out of memory while in the middle
of an operation which normally deletes "original" data, it will
abort the operation. This prevents it from deleting data that it
was unable to copy. This situation arises, for example, when you
try to rename a file, cut a block, or reformat a paragraph.

If Y reports an out of memory error, you should immediately try to
free up several tens of kilobytes of memory (or more) by removing one
or more files via {Remove_File} (F4) or {Kill_File} (Alt+F4). Y should
resume normal operation (although you may not get back the ability to
execute external programs until you exit and restart the editor).

You may be able to do some limited editing after an out of memory
error even if you don't free up any memory. This is because Y requests
memory in different sized units depending on what it is doing. If a
request fails, Y reports an error even though there may be enough
memory left for more conservative requests. I DO NOT recommend trying
to edit under such circumstances! The more operations you ask Y to
attempt with little or no memory, the greater the likelihood that an
unknown bug will manifest itself. Y's behavior with no memory has not
been extensively tested!

If Y runs out of memory while you are typing text, the line you are
working on will vanish and be replaced on the screen with the blinking
text "*** ERROR OBJECT ***". These error object lines will not
automatically go away when Y gets more memory. Furthermore, most
attempts to edit error object lines will stimulate an out of memory
message -- even if Y has plenty of memory. They can be deleted,
however, with the {Cut} (F6) command. Although this behavior seems
rather odd, I felt that it was better than letting the line vanish
without a trace. For example, if Y runs out of memory while trying to
indent a large block, it's nice to be able review the damage.


APPENDIX 3: Format of FILELIST.YFY
==================================

FILELIST.YFY is used by Y to save information about the files you are
editing between editing sessions. This file is automatically written
by the editor when you exit with the Alt+Y command. It is
automatically read by the editor when you invoke Y with no arguments.
As a result you do not normally need to manipulate FILELIST.YFY
directly.

The information in this section is provided as a service for users who

24





are interested in using Y in exotic ways. For example, you might write
a program which outputs an appropriate FILELIST.YFY as a way of
jumping into Y from some kind of host environment. (Note, however,
that Y will accept a cursor position on the command line.)

FILELIST.YFY is a plain text file. The first line of the file is an
identity line which tells Y which version of the program wrote the
file. Y ignores FILELIST.YFY files which were written for an alien
version. The format of the first line is

Y Version MAJOR.MINOR

Each additional line describes one file. The order of the file
descriptions matches the order in which Y tries to load the files and
the order in which they will appear to the {Next_File} command. The
general form of each line is

NAME ACTIVE_FLAG ROW COLUMN OFFSET COLOR TAB_DISTANCE I/R_FLAG

The NAME is the name of the file. Names can contain fully qualified
paths, but they cannot contain wildcard characters.

ACTIVE_FLAG is one of the letters '-', '*', or 'x'. The '-' is a place
holder. The '*' means that the file was the active file at the time Y
was terminated. One and only one file will be marked with a '*'
character.

An ACTIVE_FLAG of 'x' means that the file was a deleted file. That is,
the file was not actually loaded into Y at the time Y was terminated,
but that it had at some time in the past been loaded into Y. Should
the file be reloaded into Y, the editor will restore the saved
attributes. Files with an ACTIVE_FLAG of 'x' always appear at the end
of FILELIST.YFY. They appear in no particular order.

ROW and COLUMN were the cursor coordinates in the file. The top row
and the left column are row zero and column zero respectively.

OFFSET is the distance below the top row on the screen to where the
cursor appeared. For example, an OFFSET of zero means that the cursor
was at the top of the screen, whereas an OFFSET of 22 means that
cursor was at the bottom of the screen.

COLOR is the color attribute used for the file. This number is in
decimal, but it reflects the color attribute values as used by the IBM
PC video cards in text mode. Note that any color value can be inserted
here even if a monochrome monitor is in use. Y will adjust the color
accordingly when it reads FILELIST.YFY.

TAB_DISTANCE is the number of columns between tab stops for the file.

I/R_FLAG is a '0' if the file was in insert mode and a '1' if the file
was in replace mode.

25






If you create your own FILELIST.YFY, be careful to avoid illegal
values. Y does little error checking on FILELIST.YFY since it assumes
that users do not mess with the file. Be particularly careful not to
create any blank lines in the file (including at the end of the file).
Note also that Y writes FILELIST.YFY before it saves changed files.
Thus if you use Y to edit FILELIST.YFY, your modified version is the
one which is ultimately saved.


APPENDIX 4: File Extensions
===========================

Y is sensitive the extension of the file with which it is working.
Some of the default file attributes are different for different types
of files. Similarly some of the commands word differently for
different types of files. In this appendix, I will list all of the
special extensions to which Y is sensitive, and note the
corresponding attributes for each.

Notice the simple minded approach usually used for searching for
procedures. I designed the searching algorithms to work well for the
way I program. If the commands don't work for you, I suggest that you
get the source code from me and taylor them to your style.
Alternatively, to get maximum benefit from the {Next_Procedure} and
{Previous_Procedure} commands, you could adjust your programming
style.

The following table shows all the special extensions that Y
understands and summarizes the effects of those extensions.

.ASM, .INC, .MAC
Language : 8086 Assembly Language.
Tab Stop : 8
Find Procedure :
Y searches for the string "PROC" or "proc". It ignores
matches which are followed by an alphanumeric. For example,
the strings "procedure" or "process" would be skipped.

Y also searches for the strings "MACRO", "macro", "STRUCT",
or "struct."


.C, .H, .CPP, .HPP, .CXX, .HXX
Language : C/C++
Tab Stop : 2
Find Procedure :
Starting at the beginning of the file, Y counts '{' and '}'
characters until it comes to the current line. Y remembers
the last time it passed a '{' with a brace count of zero or
it will go forward until it finds such a brace (depending on
which way you want to go). After locating the opening brace

26





for a function, Y backs up looking for the first line which
is not indented. Y assumes that this is the first line of
the function's header.

This procedure also finds file scoped struct definitions and
initialized arrays. This procedure is easily confused if
there is a mismatch in brace pairs or if there are
mismatched braces in comments, strings, or character
constants.


.PAS, .DEF, .MOD
Language : Pascal/Modula_2
Tab Stop : 2
Find Procedure :
Y searches for one of the strings "PROCEDURE", "FUNCTION",
or "MODULE". Notice that Y only searches for uppercase
strings. This avoids finding "procedure" inside comments. It
also means that the search may be ineffective in some Pascal
files.


.TXT, .DOC
Language : English Text
Tab Stop : 5
Find Procedure :
Not implemented. A future version of Y may attempt to locate
paragraphs.


.ADA, .PRC, .PKG, .LIB, .SEP, .GEN, .TSK, .FNC
Language : Ada
Tab Stop : 2
Find Procedure :
Y searches for one of the strings "PROCEDURE", "procedure",
"FUNCTION", "function", "PACKAGE", "package", "TASK",
"task", "ACCEPT", or "accept". Y ignores these strings if
they occur in comments. (But it will still be fooled if they
occur in a string literal).


.PCD
Language : Pseduo-Code
Tab Stop : 2

Find Procedure :
Y searches for one of the strings, "FUNCTION", "TYPE", or
"CLASS". Y ignores these strings if they occur in comments
where a comment is any text from a '#' character to the end
of the line.




27





(ANYTHING ELSE...)
Language : Unknown
Tab Stop : 8
Find Procedure :
Not implemented.


APPENDIX 5: Future Directions
=============================

There are several areas where Y could be enhanced. I expect that
future versions of the program will have some of these enhancements.
If you have any suggestions for enhancements not mentioned here,
contact me at the address listed in the introduction.

1. Block which exist within a line. Several VTC students have been

pestering me for the ability to define a block which covers only
part of a line.

2. Macro language. An ability to put Y commands into a macro file
would be useful. Although the ability to use external programs
reduces the need for a macro language, there are certain types of
actions for which it would be useful. In particular, it would be
useful for interactive operations which adapt to the specific
text in the active file.

3. Support for very large files. It may be nice to allow the editor
to deal with files that are too large to fit in memory. Such
files would be kept primarily on disk (or perhaps EMS memory),
with only a portion being swapped into memory as needed. This
could be used, in addition, to allow more memory for external
programs.

4. Undo. In accordance with Y's model (which involves no backup
files), Y does not support an undo ability. However, such an
ability could be very useful at times.

5. Mouse support. Scrolling, positioning the cursor, marking blocks,
etc, might all be done with a mouse. It's not clear to me that
this would be useful enough to warrant implementation.













28