sxcli.dev█Simple Extensible CLI█
You are viewing an archived snapshot (v0.2.0). Switch to the current version →

sxcli.dev/completion/engine

go
go
import "sxcli.dev/completion/engine"

Package engine computes completion candidates for sxcli.dev/fw binaries from the core's Introspector. It is shell-agnostic: a shell adapter decodes its shell's transport into a Query, calls Complete, and encodes the Candidates in its shell's answer format. All completion logic lives here, exactly once.

This is the public API for third-party shell adapters (fish, PowerShell, elvish, …): implement the transport and the encoding, and the engine answers what completes — the bash and zsh packages in this module are the reference implementations. The generation policy for --script emission lives in the sibling script package.

Index#

type Candidate#

Candidate is one completion suggestion. Doc carries the one-line description (usage text, or the Metadata Doc when present); shells that render descriptions (zsh, fish) show it, bash ignores it.

go
go
type Candidate struct {
    Value string
    Kind  Kind
    Doc   string
}

func Complete#

go
go
func Complete(src Source, q Query) []Candidate

Complete returns the candidates for one query, already filtered by q.Current as a plain prefix. The single entry point: applet-name completion, argument names, declared value domains and the file/directory directives all come out of the same call — the adapter never decides what is being completed, only how to print it. The result is best-effort like the Introspector itself: on planning violations the schema falls back to registration-level truth, and an unanswerable query yields no candidates rather than an error a shell script cannot render anyway.

The target applet resolves like core dispatch: an explicit q.Applet wins, then single-applet mode, then a bare first word as the selector. With no target and no words the first word itself is being completed: public applet names.

type Kind#

Kind tells the adapter how to render a candidate — or hands the work back to the shell's native machinery.

go
go
type Kind int
go
go
const (
    // KindApplet is an applet id completing the first word.
    KindApplet Kind = iota
    // KindArg is an argument name; Value carries the dashes ("--log-level", "-c").
    KindArg
    // KindValue is a value from a declared domain: an Allowed value,
    // or a service id for fields declared HintServiceID.
    KindValue
    // KindFiles directs the adapter to emit the shell's native file
    // completion (declared via HintFile; Value and Doc are empty).
    KindFiles
    // KindDirs directs the adapter to emit the shell's native
    // directory completion (declared via HintDirectory).
    KindDirs
)

type Query#

Query is one completion request, already decoded from the shell's transport by the calling adapter.

go
go
type Query struct {
    // Applet is the target applet id; "" means the binary decides —
    // single-applet binaries have no selector word, and in
    // multi-applet binaries an empty Applet with an empty Words means
    // the first word itself is being completed.
    Applet string
    // Words are the complete words before the cursor, selector
    // excluded. The half-typed token at the cursor is NOT among them.
    Words []string
    // Current is the half-typed token at the cursor, "" at a fresh
    // word. It is only ever used as a filter prefix, never planned.
    Current string
}

type Source#

Source is the narrow view of the core's *fw.Introspector the engine consumes — the honest ledger of what this module needs from the framework. *fw.Introspector satisfies it implicitly; tests satisfy it with a fake.

go
go
type Source interface {
    // Applets returns the ids of the binary's public applets, in
    // registration order (Hidden and System applets are already
    // filtered by the core).
    Applets() []string
    // SingleApplet reports the applet that would run with no selector
    // word — dispatch-mode truth from the core's own dispatch rules.
    // The engine must not re-derive it from Applets: that listing is
    // public-only, while a Hidden non-System applet still counts for
    // the mode.
    SingleApplet() (string, bool)
    // Services returns the ids of every registered service — the
    // candidate pool for values declared HintServiceID (the core's
    // --disable and --enable).
    Services() []string
    // Arguments returns the closure-true argument schema the applet
    // would have if invoked with args — the words BEFORE the cursor:
    // a half-typed token passed as data would be planned as
    // configuration.
    Arguments(appletID string, args []string) ([]fw.ArgInfo, error)
}