Commands

How to use editor commands

You may wish to look up a particular command via the index.

The editor responds to a large set of editor commands. These commands perform tasks from moving the cursor, to copying blocks. Each command has a name and possibly a list of arguments that go with it. For example, the line_insert command needs to be supplied with the text for the new line but the character_left command simply moves the cursor left one space.

When any of the the 'non-special' keys (alphanumerics etc.) are pressed, the editor internally creates a character_type command and executes it.

Any command can be executed by pressing Esc and selecting the command from the 2 tier menu system. eg: 

user presses Esc      top level menu is brought up.
user selects line     line menu is brought up.
user selects insert   user has effectively selected
                      line_insert at this point, and now
                      line_insert prompts for the line.
user types Hello      Hello is inserted as a new line.

At any point the user can press Esc to abort the process.

Alternatively the command and its arguments can be typed in directly if the user selects COMMAND from the main menu. This is awkward since the user does need to know exactly what arguments are expected and what the correct spelling of the command required is. eg: 

user presses Esc                 top level menu is brought up.
user selects COMMAND             editor prompts for command.
user types line_insert "Hello"   Hello is inserted as a new line.

Also, when AE loads up, the first thing it does is read the initialisation file. Under DOS, OS/2 and Windows, it finds this by taking the full path of where it was loaded from and replacing the .EXE with .INI. eg: if c:\ae\ae.exe was loaded, the file c:\ae\ae.ini will be used to initialise with. Under UNIX, AE takes the executable filename and prepends . and appends rc, and then looks for this file in your home directory. eg: if ae was loaded, then .aerc will be searched for.

Each line not starting with a ; is executed in this way. This is used set up the initial key-bindings and language configurations.

The arguments can be of the types below :-

number
The command expects a non-negative number. Numbers are given in decimal, unless they start with &, in which case they are given in hex. eg: a line number or repeat count such as 5.
string
The command expects a string. eg: a filename or search pattern such as "grep.c". If environment variables are supported, and you want them expanded in the string, you can write $"$(TMP)/dummy".
character
The command expects a character. The ASCII code can be supplied instead if the menu system is not being used. Numbers are given in decimal, unless they start with &, in which case they are given in hex. eg: a character to insert such as 'A', or 65, or &41.
flag
The command expects either yes or no. eg: confirmation of choice of direction is forwards?
enter
This specifies when to enter folds or virtual folds. This can be never, if_open or always.

Quite often when a string argument is required, it is known in advance what the allowable replys are. So if you are supplying arguments interactively a menu will be given of allowable replys. An example of this is when you use the buffer_write command. The only allowable arguments are the names of the buffers, so these are supplied in a menu, rather than having the user type in the name.

If when not using the menu system to select commands you supply ? as an argument, you will be prompted for the argument interactively. eg: 

line_insert "Hello"   Inserts Hello.
line_insert ?         Prompts the user for a string
                      and then inserts it.

If you use the argument . as the argument that is intended to be a buffer name or language name, the current setting of buffer name or language name is used. eg: 

buffer_write .   Writes current buffer to disk.

It should be noted that the command names are all lower case and are all case sensitive.

Character commands

character_left moves the cursor one character left. This will wrap around at the left edge of the line. character_right moves the cursor one character right. This will wrap around at the right edge of the line.

character_insert char inserts the character specified by char at the current cursor position. character_overtype char overtypes the character specified by char at the current cursor position. character_type char either acts like character_insert or character_overtype depending on the current insert/overtype setting, as initialised in the language_create definition, and subsequently modified by use of the setup_insert command.

NOTE: It is not possible to insert/overtype/type before the tag part of a fold line.

Unfortunately, AE does treat certain awkward characters specially.

character_delete_left backspaces, deleting the character to the left of the cursor. character_delete_right deletes the character to the right of the cursor. character_delete_eol deletes the part of the current line, to the right of the cursor.

If the carriage return characters between lines are deleted, then the two lines concerned will be joined together, providing the second line is a text line.

The deleted material is placed on the deleted item stack.

character_tab types the a tab at the current cursor position. Whether this inserts or overtypes depends on the setting of the insert/overtype flag.

To do this it either inserts a ^I (character 9) into the text or the correct number of spaces to move to a column that is a multiple of the tab size. The tab setting is initialised for files recognised to be of a given language by the language_create command, and may be modified by the setup_tabs command.

String commands

string_insert str inserts the string str at the current cursor position. string_overtype str overtypes the string str at the current cursor position. string_type str either inserts str, or overtypes it, depending on the current insert/overtype setting, as initialised in the language_create definition, and subsequently modified by use of the setup_insert command.

Word commands

word_left and word_right move the cursor in the indicated ways. The scope of the commands is the current fold.

A word is defined to be a sequence of non white space characters. Words can also be delimeted by characters in the 'word seperators' part of a language definition, as defined by the language_create command.

Line commands

line_insert string inserts a new text line with string on it.

line_insert... string open_flag indent inserts a new fold line with the string as the tag. The tag is essentially just a peice of annotation describing whats in the fold. The open_flag dictates whether the fold is open or not, and the indent value specifies how much fold is indented from the current fold. The initial contents of the fold is nothing.

line_insert::: string open_flag indent inserts a new virtual fold line with the string as the tag. A virtual fold is essentially just a nesting 'link' to another file. The first part of the string, upto the first space, is used as the filename, and the rest of the string is just annotation. Environment variables may be referred to in the filename. As before, the open_flag dictates whether the fold is open or not, and the indent value specifies how much fold is indented from the current fold. eg: 

line_insert "Hello World"
line_insert "#include \"header.h\""
line_insert... "error handling" no 8
line_insert::: "header.h - enter this to edit the header file" no 0

line_delete deletes the current line, placing the deleted line on the deleted item stack.

line_yank takes a copy of the the current line and places it on the deleted item stack.

line_up and line_down move the cursor up and down within the current fold.

line_start and line_end move the cursor to the beginning and end of the current line. On DOS, OS/2 and Windows systems, it is usual for the initialisation file to have key bindings like 

key_bind "Home" "line_start"
key_bind "End"  "line_end"

line_goto linenumber goes to the line in the buffer specified by linenumber. Linenumber is a 'flat' line number in that it refers to a given line in the whole file, not just in the current fold.

You can use this command for going to lines with errors indicated by a compiler.

Any line number greater than the actual number of lines in the buffer is treated as the last line in the buffer. Furthermore line 0 is also the last line in the buffer.

line_split splits the current line where the cursor is.

It is essential that the configuration file has a line similar to the one below in order to make the editor usable :- 

key_bind "^M" "line_split"

Alternatively, if the IBM E/E3/EOS2/EPM-family-of-editors style of carriage return behaviour is desired, ^M may be defined something like 

key_bind "^M" "line_start line_down"

line_trans from to takes the current line and any character it finds in the 'from' string, it maps to the corresponding character in the 'to' string. Ranges of characters may be specified. The from and to strings must expand to the same length. eg: 

line_trans "{}" "()"     map curly brackets to round ones
line_trans "A-Z" "a-z"   map to lower case (- means range between)
line_trans "\-" "+"      map - to + (avoiding special meaning of -)

The command block_trans can do a similar mapping over a whole marked block.

line_exec takes the current line and feeds it to AE for execution. This line must be a text line, it can't be a fold, virtual fold or end of fold line.

An ideal use of this is in interactive key-binding. You could type on a line of its own in a buffer :- 

other_colours 7 7 112 112 112 7

Then you could line_exec it to see what colours you get. If the results are not to your tastes, you can edit the line and repeat.

This command has nothing to do with executing other sub-programs: for that see other_shell.

Page commands

page_up and page_down move the cursor up or down a page. It will not move out of the current fold. page_scroll_up and page_scroll_down shift the screen up or down a line, whilst keeping the cursor on the same line (unless it would have moved offscreen). They are intended to allow you to position the text exactly how you'd like it onscreen. They're much like the ^W and ^Z functions found on Wordstar, and indeed, the default initialisation file includes these key bindings.

Searching commands

search_for string case_flag regexp_flag enter_folds enter_virtual_folds forwards_flag number_matches confirm_flag searches for a given pattern. The search can be case sensitive or not. The pattern can be a straight string, or an Extended Regular Expression. Nested folds and nested virtual folds can be search always, never or if they are 'open'. The search can be repeated a number of times, with 0 meaning as many as possible. If the confirm_flag is yes, then the user gets to confirm each match found.

search_for sets the scope of the search to the current fold. That means, when it gets to the end of the current fold, the search will stop. If you search_again from outside this fold, a warning is given, and the scope may be reset to the new fold prior to searching again. eg: 

search_for ".*\.c" yes yes if_open if_open yes 5 no

search_replace string newstring case_flag regexp_flag enter_folds enter_virtual_folds forwards_flag number_matches confirm_flag is much like search_for, except that matches will be replaced by the new string. search_again repeats the last search_for or search_replace. The search continues using the scope and settings as set up by the earlier search_for or search_replace.

If the search pattern given to search_replace is a regular expression, the replacement pattern may use \N notation to refer to sub-expressions of the match in the replacement. A backslash can be given in the replacement string by escaping it with another backslash.

If you have moved out of the scope of searching since the original search command, this command will prompt to see if you wish to reset the scope of the search to the current fold and below. If you don't wish to reset the scope then the search will not proceed.

search_bracket performs bracket matching. If the cursor is on a character in the left list it searches right for the corresponding right list character and vice-versa.

Left list Right list
( )
[ ]
{ }
<>
` '

Recent versions of AE have default search modes, which are displayed in abbreviated form at the top right of the screen. The search_def_case, search_def_ere and search_def_forwards commands allow these to be toggled. If . is supplied as the appropriate arguments to search_for or search_replace, then it'll use the defaults. In this way it is possible to have one keystroke to set the mode and another to do the searching.

Recent versions of AE have a search_ignore command, which can be used to tell AE not to enter files or directories matching a regular expression. eg: 

search_ignore "cvs|CVS|\\.svn|\\.git"

Tagging commands

tag_line tags the current line, if its untagged, else untag it. Tags are displayed as highlighted letter T's on the right hand side of the screen.

tag_error causes AE to look to the right of the cursor on the current line for a filename and line-number. If it has a buffer with a file in of the given name, it places a tag in that buffer at the specified line. If there are 2 buffers with the matching name, then which is tagged is undefined.

This command is designed for use with the error output of NMAKE.EXE. eg: 

error file MAKE.LOG   source file LOOP.C

loop.c(3) missing "   main(int argc, char *argv [])
loop.c 4  EOF?        {
                      printf("Hello World);         T
                      {                             T

The tags are inserted where marked T.

The tag_goto forwards_flag command searches forwards or backwards for a tagged line. This command works globally, not just in the current fold.

By using these tag commands it is possible to place a tag where you are now, go and look at something else, and then rapidly zip back to where you were.

Also, it is possible to have one buffer with the error output of make, and by using tag_error, tags may be put in the source in another buffer, and then you can rapidly zip between (and fix) compiler errors.

Folding commands

fold_start moves the cursor to left edge of the top line of the current fold. fold_end moves the cursor to left edge of the bottom line of the current fold.

fold_open open_flag can be used to change the fold line under the cursor to be open or closed.

fold_in enters the fold line beneath the cursor and fold_out exits the current fold to return to the parent.

When entering a virtual fold, AE will attempt to create a new buffer, load in the file, and select the nested buffer. The directory of the current file can be inherited to the nested virtual file, as can the drive letter.

Currently In Virtual fold Resulting File
c:/docs/x.c y.c c:/docs/y.c
c:/docs/x.c d:y.c d:y.c
c:/docs/x.c /y.c c:/y.c
//m/s/d/f.extd2/f2.ext //m/s/d/d2/f.ext
c:/docs/x.c //m/s/f.ext //m/s/f.ext

On DOS, OS/2, Windows, and UNIX $(ENVIRONMENT_VARIABLE) strings are expanded too. eg: 

>>> $(INCLUDE)/sys/stat.h

Loads up c:/include/sys/stat.h if INCLUDE=C:\INCLUDE.

If the current fold is the top fold of a buffer and the buffer has a parent then the buffer will be optionally written, discarded and the parent will be selected.

If the virtual fold identifies a directory, then a buffer is created with a listing of the files within. The entries themselves are virtual folds, and so whole filesystems can be recursively traversed if desired. These machine generated buffers do not correspond to files and so are never written back when they are exited.

Block commands

block_mark_1 and block_mark_2 place the markers that specify the beginning and end of the 'block' within the current fold. Any line with line number greater or equal to mark 1, and less than mark 2 is considered marked. block_unmark removes both markers and thus cancels any current block marking.

block_to_mark_1 and block_to_mark_2 move the cursor to the first or second marker, if they are defined.

To create a fold, one way is to mark a block, and then use the block_fold tag open_flag indent command to create a fold with the block within it. The indent is specified relative to the fold you are in. The tag is the filename (upto the first white space), then optionally some other text. If the filename itself has spaces in it, these can be included by quoting them by preceeding them with a ' character.

If you are on a fold line, then block_unfold will unfold the fold so that the contents are now inline. The contents of the fold are marked as the current block.

If you have a block marked, then block_entab and block_detab can be used to move it left or right by a tab. The editor knows whether a press of the Tab key expands to a real ^I character, or a number of spaces, and it either preceeds each line in the block by this, or deletes this from the beginning of each line. Fold and virtual fold lines are merely further or less indented. Blank lines are not affected.

block_read filename reads a file to where the cursor is, and marks the file as the current block. eg: 

block_read $"$(HOME)/.cshrc"

Similarly, block_read filename append_flag writes (or appends) the current block to a file.

The editor attempts to deduce the language of the file from its filename. If this fails, it assumes the file is of the same language as the current buffer. ie: if you are editing a "C" file and you write a file fred.asm, the file will be written with assembler reserved comments.

block_filter command writes the current block to a temporary file 1. The command is executed with temporary file 1 as its standard input. The standard output is collected in temporary file 2. The marked block is deleted and replaced by the contents of temporary file 2. Both temporary files are then deleted. The reserved comments are written using those appropriate for the current buffer. eg: 

block_filter "grep the"

The commands are executed via the "C" system() call. Therefore under DOS, COMMAND.COM or some other command processor should be accessible by the COMSPEC environment variable. On OS/2 CMD.EXE should be accessible. Under UNIX, the SHELL environment variable is honoured.

If AE is executed with the -r option, it is running in 'restricted' mode, and so will not shell out.

NOTE: Fold information is also passed through the filter command. Therefore if you feed such data through a command like sort the resulting data may not form a correctly folded file.

The argument foldFile before sortFile after sort 
{{{ this fold
contents
}}}

/*...sthis fold:0:*/
contents
/*...e*/

contents
/*...e*/
/*...sthis fold:0:*/

Note that the resulting file has its end reserved comment before its start! If you passed the above file through an "uppercaseifier" then you would find that the reserved comments would be "uppercaseified" as well. In the reserved comment ...s implies closed fold, ...S would imply open. Therfore such a command would, as a side effect, open all nested folds!

Moral: only use block_filter on text, unless you know the program knows about folding.

NOTE: On UNIX and other environments, the commands you can give will vary and indeed on some machines, this feature may not be available at all.

If the -r command line option is given to AE at startup, then the editor is said to be running in restricted mode, and it will not allow the block_filter command (or the other_shell command) to operate.

block_delete deletes the current block and places it on the deleted item stack.

block_yank takes a copy of the current block and places it on the deleted item stack.

block_trans from to takes the current block and any character it finds in the 'from' string, it maps to the corresponding character in the 'to' string. Ranges of characters may be specified. The from and to strings must expand to the same length. See line_trans for examples.

Buffer commands

buffer_create filename read_flag select_flag creates a new buffer with a given name, and optionally reads the file with that name into the buffer. Also, the buffer may be selected. buffer_delete name deletes the buffer with the given name. You can't delete the current buffer.

buffer_select name selects the buffer for editing.

buffer_rename oldname newname renames a buffer. When the buffer is saved, it will be saved under the new filename. If a buffer has a blank name, it will not be saved.

buffer_read name reads the contents of the named file into the buffer with that name.

buffer_write name append_flag writes (or appends) the contents of the named buffer to the file with that name.

Language commands

The language_create language_name rc_start rc_end filename_regexp character_visibility insert_mode_flag tab_size word_seperators command is used to create a language definition.

AE uses a set of language definitions so that it can deduce how to store the folding information in the file without affecting the compilability of the file. It does this by inserting comments in the file. If we look at a typical "C" language definition :- 

language_create "c" "/*..." "*/" ".*\\.(c|h)" no yes yes 0 "_"

We can see that :-

  1. The language is called c.
  2. "C" comments start with /* and end with */. The ... is added to ensure real comments are not confused with comments added by the editor. This assumes that the user never starts a comment with ... This has been found to be a reasonable assumption (to date!)
  3. Files *.c and *.h are "C" files. Note that they are specified as an Extended Regular Expression and it is in lower case. Note also the escaping of the backslashes in the string.
  4. The character_visibility flag is initially set off, the autoindent_flag is initially set on, the insert_mode is initially set on, and the tab_size setting is initially 0. When a buffer is created of this language, then the editing setup is set initially as specified, but these may be later overridden using the setup_visible, setup_autoindent, setup_insert, and setup_tabs commands.
  5. The character _ (as well as white space is used to split up words. This information is used by word_left and word_right.

The actual "C" language definition, as found in the initialisation file, is more comprehensive than this.

To delete a language, use the language_delete name command. This will fail if any buffer exists which is of the specified language.

The language_select name command may be used to change the language of the current buffer.

Finally, language_rename oldname newname allows you to change the name of a language.

Setup commands

When a buffer is created, its editing setup is taken from the values specified in the language_create definition, but they can be changed using the following commands.

setup_visible toggles the state of the character_visibility flag in the current buffer. This flag determines whether spaces and tabs are displayed normally, or by showing other characters instead. Under DOS, OS/2 and Windows, little dots and arrow-heads are used. It can also cause control characters to be shown in ^X form, and other characters in <HH> form (where HH are hex digits).

setup_autoindent toggles the state of the the autoindent_flag. With this flag on, when Enter is pressed (which usually is bound to the line_split command), the new line is indented to the same level as the line above.

setup_insert toggles the state of the insert_mode flag. This flag is honoured by the character_type and string_type commands.

setup_tabs modifies the current tab_size setting. This affects the behaviour of the character_tab command, which the Tab key is usually bound to. It also affects the behaviour of the block_entab and block_detab commands. A small non-zero tab_size means, that tabbing should insert spaces until we are at the column which is the next multiple of the tab_size. The value 0 means insert a real ^I tab character, or a 'hard tab'. A 'hard tab' behaves like it has a tab_size of 8, although it is only the one character.

Keyboard commands

The key_prefix key command allows you to designate a special key, such as a control key or function key, as a 'prefix'.

You can bind a sequence of commands to occur when someone presses either a single key, or a prefix key followed by another key.

Bindings are specified using the key_bind keys commands command. eg: 

key_bind "^E" line_up"
key_prefix "^K"
key_bind "^K ^V" "block_delete other_undelete"
key_bind "^K ^Y" "block_delete"

See how the use of prefixing allows you to group similar operations under a common prefix key. In the example, it can be said that block commands all start with ^K.

Other commands

There is a whole bunch of commands which do things that can't easily be grouped under any of the other headings.

other_shell oscommand shell's out to the operating system and executes the given operating system command. Under DOS, this is done by invoking COMMAND.COM, so the COMSPEC environment variable should be set up correctly. Under OS/2, CMD.EXE should be available.

Under UNIX, the SHELL environment variable is honoured.

If the -r command line option is given to AE at startup, then the editor is said to be running in restricted mode, and it will not allow the other_shell command (or the block_filter command) to operate. eg: 

other_shell "dir/w"    lists files under DOS, OS/2 or Windows
other_shell "ls -al"   lists files under UNIX
other_shell ""         empty command => interactive shell

Support for other_shell and block_filter may not be present on every platform AE is supported on.

In some environments, your screen can become corrupted. For example, under UNIX, if you have messages turned on, someone else can write directly to your screen. You can use other_redraw to redraw your screen anew. Other possible offenders might include badly written TSRs under DOS.

To leave the editor, you can use the other_exit sure_flag command. This command prompts you to see if you are sure you wish to exit the editor. It then examines its list of buffers and for each buffer that has been modified and not written to disk, it prompts you as to whether you wish to save before exiting. Then it closes down and returns to the calling program.

A rather more ruthless form of other_exit is the other_abort sure_flag command which does not prompt about any unsaved work, and simply discards any changes.

The editor maintains a thing called the deleted item stack which holds the 100 (or so) most recently deleted items. other_undelete takes the most recently deleted item off of the stack and inserts it into the current buffer. other_put takes a copy of the most recently deleted item off of the stack and inserts it into the current buffer.

Clearly such a stack containing possibly large amounts of deleted material may consume large amounts of memory. If this is a problem (AE complains "out of memory"), then the other_squeeze command can be used to free up all the items on the deleted stack. Although this sounds usefull, its probably only ever likely to be used by someone using AE in the space constrained 16 bit DOS environment.

Different platforms support different degrees of sophistication in their handling of the terminal. Some support lots of colours and screen modes, others are more basic, as documented in the platforms documentation.

The other_colours text fold status mtext mfold mstatus command allows you to set the colours used in an AE editing session. The 6 colours are the "text line", "fold line", "status line", "marked text line", "marked fold line" and "marked status line" colours. Each colour is represented by a number, and the meaning of these numbers varys from platform to platform. Luckily, DOS, OS/2, Windows, and UNIX share close to the same colour meanings.

The other_mode width height allows you to try to set the screen into a given screen mode. Under DOS and OS/2, a wide variety of screen modes may be requested, and even those offered by various Super VGA cards may be used.

The other_backups backups allows you to enable (the default) or disable making backups of the old files when new ones are written.

Conditional execution

When AE processes its initialisation file, it can skip certain commands depending upon the platform the editor is running on. This is acheived by dollar directives, like in the following :- 

$U
key_bind "F11" "block_write \"/tmp/ae1.cut\""
$P
key_bind "F11" "block_write \"c:/tmp/ae1.cut\""
$*

$U, means execute the following lines if on a type of UNIX. $P means on a type of PC (ie: DOS, OS/2, Windows or NetWare). $E means EFI. $O is a sort of a catch all for any other type of machine. $W means Windows. $D means DOS. $2 means OS/2. $* means execute what follows on any type of machine. Letters can be combined, so $UO means UNIX or other (but not PC).

Commands Index

This allows you to rapidly find documentation the command you are interested in.