mirror of https://github.com/Hilbis/Hilbish
66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
---
|
|
title: Completions
|
|
description: Tab completion for commands.
|
|
layout: doc
|
|
menu:
|
|
docs:
|
|
parent: "Features"
|
|
---
|
|
|
|
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>`
|