20070115

1 files changed, 83 insertions, 0 deletions

diff --git a/man/2/complete b/man/2/complete
new file mode 100644
index 00000000..19fab2e5
--- /dev/null
+++ b/man/2/complete
@@ -0,0 +1,83 @@
+.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);
+.EX
+.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.