COMPLETE(3)

💅 COMPLETE(3) — like, the file name completion page, bestie

okay so this is complete and freecompletion from the Library Functions Manual, and it's literally the entire personality of tab-completion in plan9-land. come on. let's get into it 🎀

✨ NAME ✨

complete, freecompletion — file name completion, aka the moment your shell guesses what you meant and honestly? it ate 💅

🌸 SYNOPSIS 🌸

#include <u.h>
#include <libc.h>
#include <complete.h>

typedef struct CompletionCompletion;
struct Completion{
    uchar advance;
    uchar complete;
    char *string;
    int nmatch;
    int nfile;
    char **filename;
};

Completion* complete(char *dir, char *s);

void freecompletion(Completion *c);

yes bestie, that first typedef really does say struct CompletionCompletion with no space. that's not a typo on my end, that's just how it is. copy it exactly, don't @ me 😭

🦋 DESCRIPTION 🦋

so complete is, like, the main character here — it implements file name completion fr fr. you hand it a directory dir and a string s, and it comes back with a whole analysis of the file names sitting in that directory that begin with the string s. vibe check complete ✅

the fields nmatch and nfile get set to the number of files that match the prefix, and filename gets filled in with their names. and heads up 👀 — if the file that's named is a directory, a slash character gets appended to it. slay.

if no files match the string, then nmatch will be zero... but complete doesn't just give up 💀 it returns the full set of files in the directory, with nfile set to their number. so you always get something, icon behavior.

now the flags, because this is where it gets good:

• advance — reports whether the string s can be extended without changing the set of files that match. if it's true, string will be set to the extension — meaning the caller can append the value of string to s to extend the embryonic file name unambiguously. no cap, that's the whole point 🫶
• complete — reports whether the extended file name uniquely identifies a file. if it's true, 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. the way that detail matters 💖

and freecompletion? that's the cleanup crew 🧹 it frees a Completion structure and its contents. always free your structs bestie, that's the rule.

also, fun fact for the rio/acme girlies: in rio(1) and acme(1), file name completion is triggered by a control-F character or an Insert character. iconic keybind tbh 👑

🎀 SOURCE 🎀

/src/libcomplete

🌈 SEE ALSO 🌈

• rio(1)
• acme(1)

💜 DIAGNOSTICS 💜

if the directory is unreadable, or there's just, like, some other error going on? complete returns a null pointer and sets errstr. so check that pointer, bestie, please 🙈

💀 BUGS 💀

the behavior of file name completion should be controlled by the plumber. yeah. that's the bug. that's it. it's giving "known issue, no notes" 😭

okay that's the whole page, and honestly? it's lowkey iconic. this was COMPLETE(3) from the Library Functions Manual, and ngl that footer being just COMPLETE(3) again is so on brand — no date, no version, just the vibe. periodt ✨🦋💖