10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
106 lines
2.1 KiB
Groff
106 lines
2.1 KiB
Groff
.TH COMPLETE 3
|
|
.SH NAME
|
|
complete, freecompletion \- file name completion
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <complete.h>
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
.ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u
|
|
typedef struct Completion Completion;
|
|
struct Completion{
|
|
uchar advance;
|
|
uchar complete;
|
|
char *string;
|
|
int nmatch;
|
|
int nfile;
|
|
char **filename;
|
|
};
|
|
|
|
.fi
|
|
.PP
|
|
.B
|
|
.ta \w'\fLchar* 'u
|
|
|
|
.PP
|
|
.B
|
|
Completion* complete(char *dir, char *s);
|
|
.PP
|
|
.B
|
|
void freecompletion(Completion *c);
|
|
.SH DESCRIPTION
|
|
The
|
|
.I complete
|
|
function implements file name completion.
|
|
Given a directory
|
|
.I dir
|
|
and a string
|
|
.IR s ,
|
|
it returns an analysis of the file names in that directory that begin with the string
|
|
.IR s .
|
|
The fields
|
|
.B nmatch
|
|
and
|
|
.B nfile
|
|
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.
|
|
.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, with
|
|
.I nfile
|
|
set to their number.
|
|
.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 string
|
|
will be set to the extension; that is, the value of
|
|
.B string
|
|
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 string
|
|
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.
|
|
.PP
|
|
The
|
|
.I freecompletion
|
|
function frees a
|
|
.B Completion
|
|
structure and its contents.
|
|
.PP
|
|
In
|
|
.MR rio 1
|
|
and
|
|
.MR acme 1 ,
|
|
file name completion is triggered by a control-F character or an Insert character.
|
|
.SH SOURCE
|
|
.B \*9/src/libcomplete
|
|
.SH SEE ALSO
|
|
.MR rio 1 ,
|
|
.MR acme 1
|
|
.SH DIAGNOSTICS
|
|
The
|
|
.I complete
|
|
function returns a null pointer and sets
|
|
.I errstr
|
|
if the directory is unreadable or there is some other error.
|
|
.SH BUGS
|
|
The behavior of file name completion should be controlled by the plumber.
|