# Completions

Tab completion for commands.

Completions for commands can be created with the `hilbish.complete` function. See the link for how to use it.

To create completions for a command is simple. The callback will be passed 3 parameters:

- `query` (string): The text that the user is currently trying to complete. This should be used to match entries.
- `ctx` (string): Contains the entire line. Use this if more text is needed to be parsed for context.
- `fields` (string): The `ctx` split up by spaces.

In most cases, the completer just uses `fields` to check the amount and `query` on what to match entries on.

In order to return your results, it has to go within a “completion group.” Then you return a table of completion groups and a prefix. The prefix will usually just be the `query`.

Hilbish allows one to mix completion menus of different types, so a grid menu and a list menu can be used and complete and display at the same time. A completion group is a table with these keys:

- `type` (string): type of completion menu, either `grid` or `list`.
- `items` (table): a list of items.

The requirements of the `items` table is different based on the `type`. If it is a `grid`, it can simply be a table of strings.

Otherwise if it is a `list` then each entry can either be a string or a table. Example:

     1local cg = {
     2	items = {
     3		'list item 1',
     4		['--command-flag-here'] = {'this does a thing', '--the-flag-alias'}
     5	},
     6	type = 'list'
     7}
     8local cg2 = {
     9	items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
    10	type = 'grid'
    11}
    12
    13return {cg, cg2}, prefix

Which looks like this:
There's a video missing here... Well here is the URL: https://safe.saya.moe/t4CiLK6dgPbD.mp4

## Completion Handler

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. This usually doesn’t need to be done though, unless you know what you’re doing.

The default completion handler provides 3 things: binaries (with a plain name requested to complete, those in $PATH), files, or command completions. 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:

    1-- line is the entire line as a string
    2-- pos is the position of the cursor.
    3function hilbish.completion.handler(line, pos)
    4	-- do things
    5end