diff --git a/complete.go b/complete.go
index 0c70e07..faf6371 100644
--- a/complete.go
+++ b/complete.go
@@ -188,14 +188,14 @@ func escapeFilename(fname string) string {
return escapeReplaer.Replace(fname)
}
-// #interface completions
+// #interface completion
// tab completions
// The completions interface deals with tab completions.
func completionLoader(rtm *rt.Runtime) *rt.Table {
exports := map[string]util.LuaExport{
- "files": {luaFileComplete, 3, false},
"bins": {luaBinaryComplete, 3, false},
"call": {callLuaCompleter, 4, false},
+ "files": {luaFileComplete, 3, false},
"handler": {completionHandler, 2, false},
}
@@ -205,26 +205,58 @@ func completionLoader(rtm *rt.Runtime) *rt.Table {
return mod
}
-// #interface completions
-// handler(line, pos)
-// The handler function is the callback for tab completion in Hilbish.
-// You can check the completions doc for more info.
-// --- @param line string
-// --- @param pos string
-func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
- return c.Next(), nil
+// #interface 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.
+// #param query string
+// #param ctx string
+// #param fields table
+/*
+#example
+-- an extremely simple completer for sudo.
+hilbish.complete('command.sudo', function(query, ctx, fields)
+ table.remove(fields, 1)
+ if #fields[1] then
+ -- return commands because sudo runs a command as root..!
+
+ local entries, pfx = hilbish.completion.bins(query, ctx, fields)
+ return {
+ type = 'grid',
+ items = entries
+ }, pfx
+ end
+
+ -- ... else suggest files or anything else ..
+end)
+#example
+*/
+func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+ query, ctx, fds, err := getCompleteParams(t, c)
+ if err != nil {
+ return nil, err
+ }
+
+ completions, pfx := binaryComplete(query, ctx, fds)
+ luaComps := rt.NewTable()
+
+ for i, comp := range completions {
+ luaComps.Set(rt.IntValue(int64(i + 1)), rt.StringValue(comp))
+ }
+
+ return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
}
-// #interface completions
+
+// #interface 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 `doc completions` for info on the `completionGroups` return value.
-// --- @param name string
-// --- @param query string
-// --- @param ctx string
-// --- @param fields table
+// 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.
+// #param name string
+// #param query string
+// #param ctx string
+// #param fields table
func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(4); err != nil {
return nil, err
@@ -265,12 +297,13 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return cont, nil
}
-// #interface completions
+// #interface completion
// files(query, ctx, fields) -> entries (table), prefix (string)
-// Returns file completion candidates based on the provided query.
-// --- @param query string
-// --- @param ctx string
-// --- @param fields table
+// Returns file matches based on the provided parameters.
+// This function is meant to be used as a helper in a command completion handler.
+// #param query string
+// #param ctx string
+// #param fields table
func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
query, ctx, fds, err := getCompleteParams(t, c)
if err != nil {
@@ -287,28 +320,32 @@ func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
}
-// #interface completions
-// bins(query, ctx, fields) -> entries (table), prefix (string)
-// Returns binary/executale completion candidates based on the provided query.
-// --- @param query string
-// --- @param ctx string
-// --- @param fields table
-func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
- query, ctx, fds, err := getCompleteParams(t, c)
- if err != nil {
- return nil, err
- }
+// #interface 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.
+// #param line string The current Hilbish command line
+// #param pos number Numerical position of the cursor
+/*
+#example
+-- stripped down version of the default implementation
+function hilbish.completion.handler(line, pos)
+ local query = fields[#fields]
- completions, pfx := binaryComplete(query, ctx, fds)
- luaComps := rt.NewTable()
-
- for i, comp := range completions {
- luaComps.Set(rt.IntValue(int64(i + 1)), rt.StringValue(comp))
- }
-
- return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
+ if #fields == 1 then
+ -- call bins handler here
+ else
+ -- call command completer or files completer here
+ end
+end
+#example
+*/
+func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+ return c.Next(), nil
}
+
func getCompleteParams(t *rt.Thread, c *rt.GoCont) (string, string, []string, error) {
if err := c.CheckNArgs(3); err != nil {
return "", "", []string{}, err
diff --git a/docs/api/hilbish/hilbish.completion.md b/docs/api/hilbish/hilbish.completion.md
new file mode 100644
index 0000000..cf2477b
--- /dev/null
+++ b/docs/api/hilbish/hilbish.completion.md
@@ -0,0 +1,145 @@
+---
+title: Module hilbish.completion
+description: tab completions
+layout: doc
+menu:
+ docs:
+ parent: "API"
+---
+
+## Introduction
+The completions interface deals with tab completions.
+
+## Functions
+|||
+|----|----|
+|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`|
+|handler(line, pos)|This function contains the general completion handler for Hilbish. This function handles|
+|bins(query, ctx, fields) -> entries (table), prefix (string)|Return binaries/executables based on the provided parameters.|
+|files(query, ctx, fields) -> entries (table), prefix (string)|Returns file matches based on the provided parameters.|
+
+
+
+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.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
+```lua
+-- stripped down version of the default implementation
+function hilbish.completion.handler(line, pos)
+ local query = fields[#fields]
+
+ if #fields == 1 then
+ -- call bins handler here
+ else
+ -- call command completer or files completer here
+ end
+end
+````
+
+
+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
+```lua
+-- an extremely simple completer for sudo.
+hilbish.complete('command.sudo', function(query, ctx, fields)
+ table.remove(fields, 1)
+ if #fields[1] then
+ -- return commands because sudo runs a command as root..!
+
+ local entries, pfx = hilbish.completion.bins(query, ctx, fields)
+ return {
+ type = 'grid',
+ items = entries
+ }, pfx
+ end
+
+ -- ... else suggest files or anything else ..
+end)
+````
+
+
+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.completions.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 `doc completions` for info on the `completionGroups` return value.
-#### Parameters
-This function has no parameters.
-
-
-hilbish.completions.handler(line, pos)
-
-
-
-
-
-The handler function is the callback for tab completion in Hilbish.
-You can check the completions doc for more info.
-#### Parameters
-This function has no parameters.
-
-
-hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string)
-
-
-
-
-
-Returns binary/executale completion candidates based on the provided query.
-#### Parameters
-This function has no parameters.
-
-
-hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string)
-
-
-
-
-
-Returns file completion candidates based on the provided query.
-#### Parameters
-This function has no parameters.
-