docs: cleanup completions doc to better fit 80 col terminals

job-suspend
sammyette 2023-02-07 17:42:16 -04:00
parent f2ee600c28
commit 2911257eb9
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
1 changed files with 41 additions and 29 deletions

View File

@ -1,44 +1,56 @@
Hilbish has a pretty good completion system. It has a nice looking menu,
with 2 types of menus: grid (like file completions) or list.
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.
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.
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:
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, and `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`.
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.
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.
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.
- `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>`
- `call(scope, query, ctx, fields)` -> table, prefix: call a completion
handler with `scope`, usually being in the form of `command.<name>`