sammyette
/
Hilbish
mirror of https://github.com/Hilbis/Hilbish
2
2
Fork 0
Code Issues Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs/completions.md
View File

@ -1,44 +1,56 @@
Hilbish has a pretty good completion system. It has a nice looking menu, Hilbish has a pretty good completion system. It has a nice looking
with 2 types of menus: grid (like file completions) or list. 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. Like most parts of Hilbish, it's made to be extensible and
The default handler for completions in general can be overwritten to provide customizable. The default handler for completions in general can
more advanced completions if needed. be overwritten to provide more advanced completions if needed.
# Completion Handler # Completion Handler
By default, it provides 3 things: for the first argument, binaries (with a By default, it provides 3 things: for the first argument,
plain name requested to complete, those in $PATH), files, or command binaries (with a plain name requested to complete, those in
completions. With the default completion handler, it will try to run a $PATH), files, or command completions. With the default
handler for the command or fallback to file completions. 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` To overwrite it, just assign a function to
like so: `hilbish.completion.handler` like so:
function hilbish.completion.handler(line, pos) function hilbish.completion.handler(line, pos)
-- do things -- do things
end 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, It is passed 2 arguments, the entire line, and the current
and fields. The `query`, which what the user is currently trying to complete, cursor position. The functions in the completion interface
`ctx`, being just the entire line, and `fields` being a table of arguments. take 3 arguments: query, ctx, and fields.
It's just `ctx` split up, delimited by spaces.
It's expected to return 2 things: a table of completion groups, and a prefix. - The `query`, which what the user is currently trying to complete
A completion group is defined as a table with 2 keys: `items` and `type`. - `ctx`, being just the entire line
The `items` field is just a table of items to use for completions. - `fields` being a table of arguments. It's just `ctx` split up,
The `type` is for the completion menu type, being either `grid` or `list`. 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 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 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 item does not match the prefix, it will be replaced and fixed
in the line. It is case sensitive. properly in the line. It is case sensitive.
If you want to overwrite the functionality of the general completion handler, If you want to overwrite the functionality of the general completion
or make your command completion have files as well (and filter them), handler, or make your command completion have files as well
then there is the `files` function, which is mentioned below. (and filter them), then there is the `files` function, which is
mentioned below.
# Completion Interface # Completion Interface
## Functions ## Functions
- `files(query, ctx, fields)` -> table, prefix: get file completions, based - `files(query, ctx, fields)` -> table, prefix: get file completions,
on the user's query. based on the user's query.
- `bins(query, ctx, fields)` -> table, prefix: get binary/executable - `bins(query, ctx, fields)` -> table, prefix: get binary/executable
completions, based on user query. completions, based on user query.
- `call(scope, query, ctx, fields)` -> table, prefix: call a completion handler - `call(scope, query, ctx, fields)` -> table, prefix: call a completion
with `scope`, usually being in the form of `command.<name>` handler with `scope`, usually being in the form of `command.<name>`