# Module hilbish.completion

tab completions

### Introduction

The completions interface deals with tab completions.

### Functions

bins(query, ctx, fields) -> entries (table), prefix (string) | Return binaries/executables based on the provided parameters.
call(name, query, ctx, fields) -> completionGroups (table), prefix (string) | Calls a completer function. This is mainly used to call a command completer, which will have a `name`
files(query, ctx, fields) -> entries (table), prefix (string) | Returns file matches based on the provided parameters.
handler(line, pos) | This function contains the general completion handler for Hilbish. This function handles

#### hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string)

Return binaries/executables based on the provided parameters.
This function is meant to be used as a helper in a command completion handler.

##### Parameters

`string` `query`

`string` `ctx`

`table` `fields`

##### Example

     1-- an extremely simple completer for sudo.
     2hilbish.complete('command.sudo', function(query, ctx, fields)
     3	table.remove(fields, 1)
     4	if #fields[1] then
     5		-- return commands because sudo runs a command as root..!
     6
     7		local entries, pfx = hilbish.completion.bins(query, ctx, fields)
     8		return {
     9			type = 'grid',
    10			items = entries
    11		}, pfx
    12	end
    13
    14	-- ... else suggest files or anything else ..
    15end)

#### hilbish.completion.call(name, query, ctx, fields) -> completionGroups (table), prefix (string)

Calls a completer function. This is mainly used to call a command completer, which will have a `name`
in the form of `command.name`, example: `command.git`.
You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.

##### Parameters

`string` `name`

`string` `query`

`string` `ctx`

`table` `fields`

#### hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string)

Returns file matches based on the provided parameters.
This function is meant to be used as a helper in a command completion handler.

##### Parameters

`string` `query`

`string` `ctx`

`table` `fields`

#### hilbish.completion.handler(line, pos)

This function contains the general completion handler for Hilbish. This function handles
completion of everything, which includes calling other command handlers, binaries, and files.
This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.

##### Parameters

`string` `line`
The current Hilbish command line

`number` `pos`
Numerical position of the cursor

##### Example

     1-- stripped down version of the default implementation
     2function hilbish.completion.handler(line, pos)
     3	local query = fields[#fields]
     4
     5	if #fields == 1 then
     6		-- call bins handler here
     7	else
     8		-- call command completer or files completer here
     9	end
    10end