Concepts

Understanding the concepts helps you understand AE.

Characters and Keys

A character is an 8-bit ASCII value which is storable in a typical text file. This editor can handle all characters with the exception of NUL (ASCII 0). This is because the editor is written in "C" and uses the standard string library.

Characters may be entered into the text by the character_type and related commands.

A key is a button on the computer keyboard that can be pressed. Keys are divided into those that are special and those that are not.

Special keys include F1, ^G and Home and may be bound to editor commands using key_bind.

Non-special keys such as A and % are implicitly bound to type themselves into the text when pressed.

Awkward Characters

It is not possible to insert an ASCII NUL (character 0) as this is used internally within the editor.

It is dangerous to insert the ASCII EOF character (^Z) into the file, since although AE can handle it, when the file is written and subsequently re-read, the reading will stop at the ^Z, thus truncating the file.

Lines and Folds

A line in AE can be upto 2000 characters long. On older 16 bit platforms, this limit is reduced to 500 characters.

A line can be of 4 main types :-

Line typeDescription
TextA list of characters
FoldA tagged list of lines, shown as :- 
... tag
or :- 
{{{ tag
contents of fold
more contents
... tag of sub-fold
last line of fold
}}}
Virtual FoldA link to another file with a tag, shown as :- 
::: filename tag
or :- 
>>> filename tag
The first word after the ::: or >>> is the filename, the rest of the line is the tag.
TerminatorThe last line in a fold is shown like this :- 
^

With the fold and virtual fold, the ..., {{{, ::: and >>> parts are not part of the line but merely indicate the line type. This explains why these parts cannot be edited. Searching will ignore these first little bits and the left-anchor in regular expressions will match the text after them.

If you press space or tab before or on these parts, the whole fold or virtual fold is indented, and can also be un-indented by deleting the imaginary characters before the ... etc..

Before indentAfter indent 
~
~
if ((fp=fopen("x","r"))==NULL)
{{{ die
{
... closedown
fputs("arrggh!\n", stderr);
exit(1);
}
}}}
c = getc(fp);
^
~
~

~
~
if ((fp=fopen("x","r"))==NULL)
        {{{ die
        {
        ... closedown
        fputs("arrggh!\n", stderr);
        exit(1);
        }
        }}}
c = getc(fp);
^
~
~

When in one fold, sub-folds are treated as if they were one line, always!

Folds and virtual folds can be open or closed, hence the 2 forms of display for each. Open folds are displayed along with their contents (like in the 'die' fold above), whereas closed folds are simply shown as ... tag (like the 'closedown' fold above).

Virtual folds are never displayed along with their contents since the contents are held in another file, which may not be being edited. This does not make the open/closed status redundant as the searching commands may be made to search just open virtual folds.

By the use of virtual folds, it is possible to edit many files as easily as editing one.

Blocks

A block is a list of lines within a fold. Blocks may not start in one fold and end in another. This is because start and end markers are maintained seperately for each fold. Therefore, there may be different marked blocks in each fold.

The block is set by the use of block_mark_1 and block_mark_2 commands and is defined to be the lines after the first mark and before the second mark.

Blocks may be yanked, put, copied and deleted just like lines can.

Blocks may even be written and read from external files, and even passed as the stdin of DOS, OS/2, Windows or UNIX commands, to give new output blocks.

Yank and Put

All the deleting, undeleting and copying in this editor is acheived by the use of the 'Yank and Put' paradigm, as in UNIX vi.

For the datatypes character, line, and block there are commands to delete them. When they are deleted, they are put on a deleted item stack. eg: 

character_delete_left
line_delete
block_delete

This means they can be retrieved by the use of an undelete function.

Alternatively lines and blocks may be yanked. This makes a copy and puts the copy on the deleted stack. These copies may be retrieved by an undelete function. eg: 

line_yank
block_yank

Deleted items can be undeleted by the other_undelete function. This pops the most recently deleted item from the deleted item stack and attempts to replace it in the current buffer.

Alternatively the item on the top of the stack may be duplicated and the duplicated item will be inserted into the current buffer. This is done with the other_put command.

Deleted Item Stack

Deleted material is not lost forever, as it is put on the deleted item stack maintained by the editor. Items on this stack may be recovered using the other_undelete and other_put commands.

Upto 100 of the most recent deletes remain on the stack, until they are undeleted, or the user deliberately decides to discard them up using other_squeeze. This might be done in low memory situations on memory constrained machines, such as those afflicted by the 16 bit DOS 640Kb memory barrier.

Reserved comments

AE can edit files of many programming languages. Practically any language that has a comment structure is fold-able. This is because the editor saves the fold structure of the file inside 'reserved comments' in the file.

A 'reserved comment' is a form of comment that is reserved for use by AE only. The user is not permitted to enter a comment of this form into a file.

Here are some examples of wise choices of reserved comment :-

Language Comment start Comment end Reserved comment startReserved comment end
C /* *//*... */
Assembler;   ;...  
Batch rem  rem...  
Make #   #...  
Pascal { } {... }

Note that the reserved comment starts are the comment starts plus .... This is an unlikely start of a comment entered by the user and so this is usually used to distinguish reserved comments and user supplied comments.

It is recommended that you append ... to the comment start to give a reserved comment start whenever you add a language definition, to ensure compatiblity with everyone else. Furthermore, it is also wise not to change any definitions that come in the standard initialisation file ae.ini.

An example of a reserved comment, as you might see it if you were to type the file or edit it with a flat editor (Pascal) :- 

{...sUpdateScreen:0:}

To be precise, a reserved comment is recognised as a line starting with the reserved comment start.

The reserved comments are set up for each language in the initialisation file ae.ini by language_create command. eg: 

language_create "ada" "--..." "" ".*\\.ada" no yes yes 2 "_."

Buffers and Files

A file is named a list of characters stored on some form of secondary storage.

A buffer is a structure in AE which has a name (usually a filename), and a language. A buffer holds a list of lines and is effectively equivelent to a fold. Some of these lines can be folds and virtual folds and so the buffer can hold a lot more than is visible at first sight.

There are mechanisms for creating and deleting buffers, along with reading files into and out of them (ie: buffer_read and buffer_write).

Because a buffer has a language associated with it, the editing characteristics of one buffer may differ from another.

The language of a buffer is derived when the buffer is created from the filename the buffer is given. It does this by the use of a list of language definitions specified (usually) in the configuration file.

Files can be read into a buffer using block_read and parts of a buffer may be written to a file using block_write.

The editor stores folding information is reserved comments. These vary from language to language, and are set up by language_create. Because the folding information is stored in comments, any compilers and assemblers will ignore it. This eliminates the need for a 'folded file' to 'compilable file' conversion process.