Hilbish/docs/completions.md

Hilbish has a pretty good completion system. It has a nice looking menu, with 2 types of menus: grid (like file completions) or list.

Like most parts of Hilbish, it's made to be extensible and customizable. The default handler for completions in general can be overwritten to provide more advanced completions if needed.

Completion Handler

By default, it provides 3 things: for the first argument, binaries (with a plain name requested to complete, those in $PATH), files, or command completions. With the default completion handler, it will try to run a handler for the command or fallback to file completions.

To overwrite it, just assign a function to hilbish.completion.handler like so: function hilbish.completion.handler(line, pos) -- do things end

It is passed 2 arguments, the entire line, and the current cursor position. The functions in the completion interface take 3 arguments: query, ctx, and fields.

• The query, which what the user is currently trying to complete
• ctx, being just the entire line
• fields being a table of arguments. It's just ctx split up, delimited by spaces.

It's expected to return 2 things: a table of completion groups, and a prefix. A completion group is defined as a table with 2 keys: items and type.

• The items field is just a table of items to use for completions.
• The type is for the completion menu type, being either grid or list.

The prefix is what all the completions start with. It should be empty if the user doesn't have a query. If the beginning of the completion item does not match the prefix, it will be replaced and fixed properly in the line. It is case sensitive.

If you want to overwrite the functionality of the general completion handler, or make your command completion have files as well (and filter them), then there is the files function, which is mentioned below.

Completion Interface

Functions

• files(query, ctx, fields) -> table, prefix: get file completions, based on the user's query.
• bins(query, ctx, fields) -> table, prefix: get binary/executable completions, based on user query.
• call(scope, query, ctx, fields) -> table, prefix: call a completion handler with scope, usually being in the form of command.<name>