term.input.completion

Overview

Completion engine with pluggable sources and candidate management.

Candidates are populated by the provider's search() method (e.g. filesystem paths, commands) and held in a single candidate layer alongside their metadata.

Source interface

Each completion source must export a new() constructor that returns a table implementing:

search(query, ...) — required; return array of candidate strings
update() — optional; refresh cached data (called on init and via completion:update())
close() — optional; release resources (called on unregister and via completion:close())

Metadata conventions

Metadata is a table indexed by candidate position (1-based). Common fields used by existing providers:

source (string) — identifies the completion source for TSS styling (e.g. "bin", "fs", "lua_symbol")

Shell-specific fields (handled by the shell provider's promote()):

replace_prompt (string) — replace entire line with this prefix plus the promoted candidate
exec_on_prom (bool) — execute immediately after promotion
trim_promotion (bool) — strip leading whitespace from candidate
reduce_spaces (bool) — collapse multiple spaces in candidate

Functions

Name	Signature
completion:flush	completion:flush()
completion:available	completion:available() -> `has_candidates`
completion:count	completion:count() -> `n`
completion:chosen_index	completion:chosen_index() -> `idx`
completion:set_chosen_index	completion:set_chosen_index(`idx`)
completion:meta_at	completion:meta_at(`idx`) -> `metadata`
completion:source	completion:source(`name`) -> `src`
completion:get	completion:get(`promoted`) -> `candidate`
completion:common_prefix	completion:common_prefix() -> `prefix`
completion:update	completion:update()
completion:register_source	completion:register_source(`name`, `src`)
completion:unregister_source	completion:unregister_source(`name`)
completion:close	completion:close()
completion:provide	completion:provide(`candidates`)
completion:set_meta	completion:set_meta(`metadata`)
new	new(`config`) -> `completion`, `err`

completion:flush()

Clear all candidates and reset selection

completion:available() -> has_candidates

Check whether candidates are available

completion:count() -> n

Return the number of candidates

completion:chosen_index() -> idx

Return the index of the currently selected candidate

completion:set_chosen_index(idx)

Set the index of the currently selected candidate

completion:meta_at(idx) -> metadata

Return metadata for the candidate at the given index

completion:source(name) -> src

Return a registered completion source by name

completion:get(promoted) -> candidate

Get the currently selected candidate string

When promoted is true, returns the raw candidate string. Otherwise returns the candidate styled for inline display. When config.tss was provided at construction, styling uses the theme-subscribed TSS keyed by the candidate's source metadata.

completion:common_prefix() -> prefix

Compute the longest common prefix across all candidates

completion:update()

Trigger update on all registered completion sources

completion:register_source(name, src)

completion:unregister_source(name)

Unregister a completion source, calling close() if available

completion:close()

Close all sources and clean up

completion:provide(candidates)

Replace the candidate list

completion:set_meta(metadata)

Replace the metadata table for candidates

new(config) -> completion, err

Create a new completion instance from a config table

The config table must contain:

path — module path for the completion search provider
sources — optional list of module paths for completion sources

Each source module must export a new() constructor.

Provider interface

The module at config.path must return a table with at least search and optionally the methods listed below. All provider methods are injected directly onto the completion object, so inside them self refers to the completion instance — giving access to self:source(), self:provide(), self:set_meta(), etc.

Required:

search(self, input, history, cursor_pos) -> bool Populate the candidate list for the given input line. Call self:provide() and self:set_meta() inside. When the input object has eol_only = false, a numeric cursor_pos is passed so the provider can complete at any position in the line.

Optional:

get(self, promoted) -> string Return the current candidate. When promoted is true, return raw text; otherwise return styled text for inline display. If absent a default implementation using a built-in TSS rule is used.
promote(self, candidate, metadata, line) -> {line=, action=} Apply candidate to line and return the resulting line. Set action = "execute" to trigger immediate execution. If absent, the default behaviour is to append the candidate to the line.
should_promote_full(self) -> bool Return true when the current candidate must skip common-prefix narrowing and be promoted in full (e.g. line-replacement completions).
should_auto_promote(self) -> bool Return true when ENTER should auto-promote the current candidate instead of submitting the line as-is.