From 2911257eb98897f79190dfe808486180bdbbaa69 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 7 Feb 2023 17:42:16 -0400 Subject: [PATCH] docs: cleanup completions doc to better fit 80 col terminals --- docs/completions.md | 70 ++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/docs/completions.md b/docs/completions.md index 1354dc0..c2de27a 100644 --- a/docs/completions.md +++ b/docs/completions.md @@ -1,44 +1,56 @@ -Hilbish has a pretty good completion system. It has a nice looking menu, -with 2 types of menus: grid (like file completions) or list. +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. +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. +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: +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`. + +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. +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. +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. +- `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.` +- `call(scope, query, ctx, fields)` -> table, prefix: call a completion +handler with `scope`, usually being in the form of `command.`