docs: add more documentation for completions

api.go

@@ -497,9 +497,7 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // A `scope` is currently only expected to be `command.<cmd>`,
 // replacing <cmd> with the name of the command (for example `command.git`).
 // `cb` must be a function that returns a table of "completion groups."
-// A completion group is a table with the keys `items` and `type`.
-// `items` being a table of items and `type` being the display type, which is
-// `grid` (the normal file completion display) or `list` (with a description)
+// Check `doc completions` for more information.
 // --- @param scope string
 // --- @param cb function
 func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {

docs/completions.txt

@@ -0,0 +1,44 @@
+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, 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`.
+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>`