Completion Subroutines

There are several EEL subroutines defined in complete.e that get a line of input from the user, allowing normal editing. Most of them offer some sort of completion as well. They also provide a command history.

Each function takes two or three arguments. The first argument is an array of characters in which to store the result. The second argument is a prompt string to print in the echo area. The third argument, if there is one, is the default string. Depending on the setting of the insert-default-response variable, Epsilon may insert this string after the prompt, highlighted, or it may be available by pressing Ctrl-r or Ctrl-s.

Some functions will substitute the default string if you press <Enter> without typing any response. These functions display the default to you inside square brackets [ ] (whenever they don't actually pre-type the default after the prompt). The prompt that you must provide to these functions shouldn't include the square brackets, or the colon and space that typically ends an Epsilon prompt. The function will add these on before it displays the prompt. If there should be no default, use the empty string "".

get_file(char *res, char *pr, char *def) get_file_dir(char *res, char *pr)
The get_file( ) and get_file_dir( ) subroutines provide file name completion. When the get_file( ) subroutine constructs its prompt, it begins with the prompt string pr, then appends a colon ":" and a space. (If insert-default-response is zero, it also includes the default value in the prompt, inside square brackets.) If the user presses <Enter> without typing any response, get_file( ) copies the default def to the response string res.

The get_file_dir( ) subroutine provides the directory part of the current file name, inserted as part of a default response or available via Ctrl-s or Ctrl-r (see the description of the prompt-with-buffer-directory variable), but it doesn't display that as part of the prompt. It uses the prompt pr as is. It doesn't substitute any default if the user enters no file name. Both get_file( ) and get_file_dir( ) call absolute( ) on the name of the file before returning (see Manipulating File Names).

get_buf(char *res, char *pr, char *def)
The get_buf( ) subroutine completes on the name of a buffer. To construct its prompt, the subroutine begins with the prompt string pr, then adds the default def inside square brackets [ ], and then appends a colon ":" and a space.

get_any(char *res, char *pr, char *def) get_cmd(char *res, char *pr, char *def) get_macname(char *res, char *pr, char *def) get_func(char *res, char *pr, char *def) get_var(char *res, char *pr, char *def, int flags)
Epsilon locates commands, subroutines, and variables by looking them up in its name table. See The Name Table for details. The subroutines that complete on commands, variables and so forth all look in the same table, but restrict their attention to particular types of name table entries. For example, the get_macname( ) subroutine ignores all name table entries except those for keyboard macros. In the following table, • indicates that the subroutine allows entries of that type.

   Command   Subr.   Kbd. Macro   Key Table   Variable

get_any( )   •   •   •   •   •

get_cmd( )   •      •

get_func( )   •   •

get_macname( )         •

get_var( )               •

These subroutines all substitute the default string if you just press <Enter> without entering anything. They also display the default inside square brackets [ ] after the prompt you provide (if insert-default-response is zero), and then append a colon ":" and a space.

The get_var( ) subroutine takes an additional, fourth parameter. It contains a set of flags to pass to the comp_read( ) subroutine, as listed below.

int get_command_index(char *pr)
The get_command_index( ) subroutine defined in control.e calls the get_cmd( ) subroutine to ask the user for the name of a command. It then checks to see if the command exists, and reports an error if it doesn't. (When checking, it allows subroutines and macros as well as actual commands.) If the function name checks out, get_command_index( ) returns its name table index.

Previous Up Next
Window Events Primitives and EEL Subroutines Completion Internals