ref: 75c92428225428c8fde2d015f010e608a0b12f1d
dir: purgatorio/man/2/complete
.TH COMPLETE 2
.SH NAME
complete \- file name completion
.SH SYNOPSIS
.EX
include "complete.m";
complete := load Complete Complete->PATH;
Completion: adt {
advance: int; # whether forward progress has been made
complete: int; # whether the completion now represents a file or directory
str: string; # string to advance, suffixed " " (file) or "/" (directory)
nmatch: int; # number of files that matched
filename: array of string; # their names
};
init: fn();
complete: fn(dir, s: string): (ref Completion, string);
.EE
.SH DESCRIPTION
.B Complete
implements file name completion.
.PP
.B Init
must be called before any other operation of the module.
.PP
Given a directory
.I dir
and a string
.IR s ,
.B complete
returns a tuple
.BI ( c,\ err ),
where
.I c
is an analysis of the file names in that directory that begin with the string
.IR s .
The field
.B nmatch
will be set to the number of files that match the prefix and
.B filename
will be filled in with their names.
If the file named is a directory, a slash character will be appended to it.
On an error,
.I c
is nil and
.I err
is a diagnostic string.
.PP
If no files match the string,
.B nmatch
will be zero, but
.I complete
will return the full set of files in the directory.
.PP
The flag
.B advance
reports whether the string
.I s
can be extended without changing the set of files that match. If true,
.B str
will be set to the extension; that is, the value of
.B str
may be appended to
.I s
by the caller to extend the embryonic file name unambiguously.
.PP
The flag
.B complete
reports whether the extended file name uniquely identifies a file.
If true,
.B str
will be suffixed with a blank, or a slash and a blank,
depending on whether the resulting file name identifies a plain file or a directory.
.SH SOURCE
.B /appl/lib/complete.b
.SH SEE ALSO
.IR names (2)
.SH DIAGNOSTICS
The
.I complete
function returns a nil reference and a diagnostic string
if the directory is unreadable or there is some other error.