HELP VEDFILECOMPLETE A.Sloman October 1990
Updated January 1995
LIB VEDFILECOMPLETE
A file-name completion program, that also works on patterns. When the
library is compiled it maps the procedure -vedfilecomplete- onto the
key sequence ESC F by default (See HELP * VEDKEYS). (Previously ESC 3
was used. This may still work if it has not been overwritten by a
terminal key binding.)
In January 1995 the procedure vedfilecomplete was modified to allow
selection to be made by typing a single character in the manner
described in the section: "Options in a separate VED file", below.
CONTENTS - (Use <ENTER> g to access required sections)
-- Making the program available
-- What vedfilecomplete does
-- Examples
-- What it does
-- Options on the status line
-- Options in a separate VED file
-- -- Selection by typing a character
-- -- Selection by re-invoking vedfilecomplete in the options file.
-- What you can do when the options file is created
-- If there is no text to left of cursor initially
-- Use on the statusline
-- Finding out what is in a directory
-- Using vedcomplete_display to control how options are displayed
-- Using vedcomplete_exclude to control display of backup files
-- WARNING: the options file can get out of date-- Making the program available --------------------------------------
As explained in HELP * VEDKEYS the "filecomplete" facility in VED is
mapped onto the key sequence
ESC F
This invokes the procedure vedfilecomplete. You may also find that it
works with the sequence ESC 3. You can, if you prefer, use vedsetkey or
vedset to map it onto a function key.
(See HELP * VEDSETKEY, * VEDSET, * INITIAL)
-- What vedfilecomplete does ------------------------------------------
This procedure enables you easily to find out which possible ways of
continuing a file name that you have begun to type in VED correspond to
files that actually exist. For example if you have a file whose name
starts with foo, and you cannot remember how it continues, type foo then
invoke -vedfilecomplete- and it will show you the options available. If
you select one of them it will complete the name for you.
At present it looks only for files on disk. It could be extended to
include files in the VED buffer, but * VEDFILESELECT (often ESC e)
already provides that facility.
It can also handle patterns. For instance if you know that the file you
want is a program file with extension ".p" and a name that includes
"foo" in the middle, but you can't remember the name then type:
*foo*.p and invoke -vedfilecomplete- to discover which files match that
pattern. You can then select the one you want and the name will replace
the pattern.
You can invoke -vedfilecomplete- whether typing on the command line, or
in a VED file.
If there are no characters to the left of the cursor, the set of options
you will get is the full set of filenames in your current directory.
You can specify other directories by giving path names, either absolute
or relative, including patterns.
On Unix systems the options displayed will indicate directory names
by appending "/" to the name.
Note VMS users can use Unix file name formats for convenience, as
sys_file_match will translate them. (See REF * sys_file_match)
By default vedfilecomplete will not display full path names, only the
file name part (including "version" information). You can make it
display the full path name by changing the procedure vedcomplete_display
as described below.
-- Examples -----------------------------------------------------------
Several examples are given below. In each case, try putting the VED
cursor to the right of the text indicated by the "^" symbol, then type
ESC F (or ESC 3) and see what happens. In some cases it will simply
complete the file name. In others it will give you some options for
completion, either on the status line, or in another VED file, as
described below. If the options have numbers or letters associated with
them, try selecting an option by typing the number or letter.
The first example will tell you about all files whose names start with
"a" in the current directory (if any). The second will tell you about
all files that include '.p' in their names (if there are any)
Example 1:
a
Put the VED cursor here ^ and type ESC F. NB the cursor must be
immediately to the right of the "a".
Example 2:
(ignore stuff) *.p
Put the VED cursor here ^ and type ESC F. Stuff preceding the first
space on left of the cursor is ignored.
Example 3:
$usepop/pop/lib/ved/vedfileco
here ^
or
$usepop/pop/lib/ved/vedfilewi
here ^
These two are likely to have unique completions.
Example 4:
$usepop/pop/lib/ved/ved*z*
here ^
This will have a small number of completions, given on the
status line. Select one by typing the number.
Example 5:
$usepop/pop/lib/
here ^
In this example you will be given several completion options
which are directory names. Choose one by typing the letter given,
then after the file name is extended type ESC F (or ESC 3) again
to be shown the files in the directory. Or first type a character
after the directory name, then do ESC F, to see which files start
with that character.
Example 6:
$usepop/pop/lib/ved/ved*z* (ignore stuff to right)
here ^
Text to the right of the point where vedfilecomplete is invoked
is ignored.
Example 7:
<---- To the left of this
here ^
If there is no text to the left of the cursor, then all the files
in the current directory will be listed.
-- What it does -------------------------------------------------------
The behaviour of -vedfilecomplete- when invoked with some text
immediately to the left of the VED cursor is as follows.
1. The sequence of characters to the left of the cursor is examined and
treated as an initial substring of a file specification. The start of
the sequence is delimited by a space or other non-printing character, or
by one of the quote characters (' or "). It may include "/" in Unix, or
"[" "]" in VMS. This string is called the "key-name" in what follows. It
may include pattern elements, e.g. "*" and "?".
2. All file names that start with the key-name or start with a name
matching the key-name pattern (if it contains pattern elements) are
found, and a list of strings representing those names is created. Which
of the matching files are included in this list can be further
constrained by use of the variable vedcomplete_exclude described below;
by default, Unix backup files -- those ending in "-" -- are excluded.
3.a. If there is exactly one such file, then the file name is completed,
unless it is the same as the key-name, in which case vedscreenbell() is
invoked.
3.b. If there are no such file names, then vedscreenbell() is invoked.
3.c. If there are two or more file names and they all share some
characters in common after the key-name, and the key-name is not a
"pattern", then those characters are inserted and vedfilecomplete is
run again, giving one of the following options.
3.d. If there are two or more such file names, and they all differ in
the next character after the key-name then the user is given a display
of the options available for extending the key-name. Exactly how much of
each matching path name is displayed is controlled by the variable
vedcomplete_display, described below.
The options are displayed on the status line or in a new temporary file,
depending on how many options there are.
-- Options on the status line -----------------------------------------
3.d.1. If the options can be displayed on the status line, in the manner
of -vedfileselect- they will be, labelled with numerals. If one of the
numerals is typed, then that option is used to complete the key-name. If
RETURN is pressed, it is left unchanged.
-- Options in a separate VED file -------------------------------------
3.d.2. If the set of options is too long to be displayed on the status
line, then a temporary file is created showing the options, arranged in
columns. Under unix, those that are directories are indicated with "/"
at the end. There may be a pause while the options are being inserted,
if there is a very long list.
-- -- Selection by typing a character
If there are few enough options to be indicated by a quick selection
character code, then each option is preceded by the code followed by a
")". The range of codes will depend on how many options there are. E.g.
if there are fewer than 10 the codes will be 1) 2), etc. If there are
fewer than 29, the codes will be a), b), etc. Otherwise a mixed
collection of characters will be used. NB case is significant.
For example the options file might look like this:
5 POSSIBLE COMPLETIONS FOR: ad
EITHER select option by typing code before ")" OR
Select name (chardown & ESC Tab) then Redo "COMPLETION" command (ESC 3)
1)addr 2)addup.p 3)adm/
4)advent_objectclass 5)advent_objectclass.p
If you then type "4" the name will be expanded to: advent_objectclass.
If no selection character is typed then the procedure exits leaving the
VED cursor in that file (the "options file"). It is then possible to
make a selection as follows.
-- -- Selection by re-invoking vedfilecomplete in the options file.
Where there are too many options to be identified by a selection code,
or when not all the codes are visible, the user has the further option
of moving the VED cursor onto the required option and then re-invoking
vedfilecomplete (i.e. type the same key sequence as before).
The display file will be removed, and the key-name in the original file
will be transformed into the full file name.
In order to help you select the require option with few keystrokes, the
variable -vedindentstep- is set to the column width in the options file.
That means that the VED function VEDTABRIGHT will move the cursor a
column at a time. (This is usually mapped onto ESC tab). However, you
can move the cursor any way you wish, including using the mouse if
available, before making your selection by re-invoking vedfilecomplete.
-- What you can do when the options file is created -------------------
Summary, when the options file listing possible expansions is presented,
the user has the following possibilities:
(a) Quit the options file and ignore it (using ENTER q, or ESC q)
(b) Select an option by typing its selection code (if there is one).
(c) Put the cursor on the required option and then re-invoke
vedfilecomplete.
(d) You can leave the options file temporarily, and come back to it
later and then do (c) (but not (b)).
NOTES:
(1) If the options file is left, and -vedfileselect- is invoked again,
then the options file may be overwritten in order to display a new
set of options.
(2) If you quit the original file in which you invoked -vedfileselect-
and then come back to the options file, attempting to make a
selection will produce an error message saying that the original
file is no longer in VED.
-- If there is no text to left of cursor initially --------------------
If there is a space to the left of the cursor, or if it is at the
beginning of a line (either on the command line or in a VED buffer),
then -vedfilecomplete- will still work, but the list of options will be
all the file names in the current directory.
-- Use on the statusline ----------------------------------------------
-vedfilecomplete- works whether it is invoked with the cursor on
the status line or in an ordinary VED buffer. For example if you
wish to edit a file whose name starts with "lib" and you can't remember
how it continues do
ENTER ved lib
Then press ESC 3, and select the appropriate completion. You may need to
do it more than once, e.g. if the file is in a sub-directory.
Some of the error messages will not be readable if you invoke
-vedfileselect- while on the status line. However, they should be easy
enough to guess: you have probably typed a number that does not
correspond to an option available. Simply re-invoke -vedfilecomplete-
again and try another key.
-- Finding out what is in a directory ---------------------------------
If you want to find all the files in a particular directory, then
type the directory pathname and, in Unix a final "/". Then
-vedfilecomplete- will present you with a list of the files in the
directory. You can also use this to go UP the directory tree. E.g.
to get names of files in the directory above the current directory,
do (in Unix)
../
for two levels up do
../../
etc.
-- Using vedcomplete_display to control how options are displayed -----
The user-definable -vedcomplete_display- is used to select the portion
of the pathname to be displayed in the options file or on the status
line. Its default value is -sys_fname_namev - which displays only the
file name part and version part if present, of the path name. (It is
defined in REF * SYSUTIL).
If you always want the full path name to be displayed you can assign
identfn to vedcomplete_display, e.g. in your vedinit.p
vars procedure vedcomplete_display = identfn;
It is easy to define different procedures that all use vedfilecomplete,
but which locally assign different procedures to vedcomplete_display.
These can then be used to give different ways of displaying the options.
-- Using vedcomplete_exclude to control display of backup files -------
[UNIX ONLY]
The user-assignable variable vedcomplete_exclude holds a list containing
strings or procedures indicating that filenames ending in those strings
should be excluded.
If S is a string in the list and a filename ends with S then that
file name will not be included. By default the list contains only the
string '-', so that VED backup files are not displayed.
If P is a procedure in the list or a procedure whose name is in the
list, then if P applied to the file name yields a non-false result then
the file name will NOT be displayed.
If you always wish to be able to see all files that "complete" the given
string, including VED backup files, then in your vedinit.p file do
vars vedcomplete_exclude = [];
See HELP * INITIAL
It is possible to define procedures corresponding to different versions
of vedfilecomplete, which exclude different things, by using different
versions of vedcomplete_exclude locally.
-- WARNING: the options file can get out of date ----------------------
If you temporarily leave the file displaying the options, and edit the
original file and then return to the options file, selecting the option
may produce odd results, as it assumes that the line and column number
immediately to the right of the key-name has not changed. If any lines
or characters have been inserted or deleted prior to that location (in
the original file) then the the "completion" will go in the wrong place.
Similarly, if you edit the options file, and then try to use it to
make a selection you may get wrong results, because it uses the column
and row position of the cursor to calculate which selection was chosen,
rather than the actual contents of the file.
In order to show options as compactly as possible, the options file
does not display full path names, since normally the leading path name
is the same for all options, and only the file name at the end differs.
However, if a path-name pattern is used with "*" or "?" in the directory
part, then there may be more than one directory matching. This will
not be evident in the options file and two or more options may look
the same. If this is a problem use ved_dired, which displays full path
names corresponding to patterns. (See HELP * DIRED).
--- C.all/help/vedfilecomplete
--- Copyright University of Sussex 1995. All rights reserved. ----------