docs: update hilbish.completion

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
+// #interface completion
-// handler(line, pos)
+// bins(query, ctx, fields) -> entries (table), prefix (string)
-// The handler function is the callback for tab completion in Hilbish.
+// Return binaries/executables based on the provided parameters.
-// You can check the completions doc for more info.
+// This function is meant to be used as a helper in a command completion handler.
-// --- @param line string
+// #param query string
-// --- @param pos string
+// #param ctx string
-func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// #param fields table
-	return c.Next(), nil
+/*
+#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
 	}
 
-// #interface completions
+	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 completion
 // call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
-// Calls a completer function. This is mainly used to call
+// Calls a completer function. This is mainly used to call a command completer, which will have a `name`
-// a command completer, which will have a `name` in the form
+// in the form of `command.name`, example: `command.git`.
-// of `command.name`, example: `command.git`.
+// You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.
-// You can check `doc completions` for info on the `completionGroups` return value.
+// #param name string
-// --- @param name string
+// #param query string
-// --- @param query string
+// #param ctx string
-// --- @param ctx string
+// #param fields table
-// --- @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.
+// Returns file matches based on the provided parameters.
-// --- @param query string
+// This function is meant to be used as a helper in a command completion handler.
-// --- @param ctx string
+// #param query string
-// --- @param fields table
+// #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,27 +320,31 @@ 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
+// #interface completion
-// bins(query, ctx, fields) -> entries (table), prefix (string)
+// handler(line, pos)
-// Returns binary/executale completion candidates based on the provided query.
+// This function contains the general completion handler for Hilbish. This function handles
-// --- @param query string
+// completion of everything, which includes calling other command handlers, binaries, and files.
-// --- @param ctx string
+// This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.
-// --- @param fields table
+// #param line string The current Hilbish command line
-func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// #param pos number Numerical position of the cursor
-	query, ctx, fds, err := getCompleteParams(t, c)
+/*
-	if err != nil {
+#example
-		return nil, err
+-- 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
+#example
+*/
+func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+	return c.Next(), nil
 }
 
-	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
-}
 
 func getCompleteParams(t *rt.Thread, c *rt.GoCont) (string, string, []string, error) {
 	if err := c.CheckNArgs(3); err != nil {

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
+|||
+|----|----|
+|<a href="#completion.call">call(name, query, ctx, fields) -> completionGroups (table), prefix (string)</a>|Calls a completer function. This is mainly used to call a command completer, which will have a `name`|
+|<a href="#completion.handler">handler(line, pos)</a>|This function contains the general completion handler for Hilbish. This function handles|
+|<a href="#completion.bins">bins(query, ctx, fields) -> entries (table), prefix (string)</a>|Return binaries/executables based on the provided parameters.|
+|<a href="#completion.files">files(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns file matches based on the provided parameters.|
+
+<hr><div id='completion.call'>
+<h4 class='heading'>
+hilbish.completion.call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
+<a href="#completion.call" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+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`**  
+
+
+</div>
+
+<hr><div id='completion.handler'>
+<h4 class='heading'>
+hilbish.completion.handler(line, pos)
+<a href="#completion.handler" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+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
+````
+</div>
+
+<hr><div id='completion.bins'>
+<h4 class='heading'>
+hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string)
+<a href="#completion.bins" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+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)
+````
+</div>
+
+<hr><div id='completion.files'>
+<h4 class='heading'>
+hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string)
+<a href="#completion.files" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+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`**  
+
+
+</div>
+

docs/api/hilbish/hilbish.completions.md

@@ -1,76 +0,0 @@
----
-title: Module hilbish.completions
-description: tab completions
-layout: doc
-menu:
-  docs:
-    parent: "API"
----
-
-## Introduction
-The completions interface deals with tab completions.
-
-## Functions
-|||
-|----|----|
-|<a href="#completions.call">call(name, query, ctx, fields) -> completionGroups (table), prefix (string)</a>|Calls a completer function. This is mainly used to call|
-|<a href="#completions.handler">handler(line, pos)</a>|The handler function is the callback for tab completion in Hilbish.|
-|<a href="#completions.bins">bins(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns binary/executale completion candidates based on the provided query.|
-|<a href="#completions.files">files(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns file completion candidates based on the provided query.|
-
-<hr><div id='completions.call'>
-<h4 class='heading'>
-hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
-<a href="#completions.call" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-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.  
-</div>
-
-<hr><div id='completions.handler'>
-<h4 class='heading'>
-hilbish.completions.handler(line, pos)
-<a href="#completions.handler" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-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.  
-</div>
-
-<hr><div id='completions.bins'>
-<h4 class='heading'>
-hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string)
-<a href="#completions.bins" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Returns binary/executale completion candidates based on the provided query.  
-#### Parameters
-This function has no parameters.  
-</div>
-
-<hr><div id='completions.files'>
-<h4 class='heading'>
-hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string)
-<a href="#completions.files" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Returns file completion candidates based on the provided query.  
-#### Parameters
-This function has no parameters.  
-</div>
-

emmyLuaDocs/hilbish.lua

@@ -14,21 +14,17 @@ function hilbish.aliases.add(alias, cmd) end
 --- @param cb function
 function hilbish.runner.setMode(cb) end
 
---- Calls a completer function. This is mainly used to call
+--- Calls a completer function. This is mainly used to call a command completer, which will have a `name`
---- a command completer, which will have a `name` in the form
+--- in the form of `command.name`, example: `command.git`.
---- of `command.name`, example: `command.git`.
+--- You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.
---- You can check `doc completions` for info on the `completionGroups` return value.
+function hilbish.completion.call(name, query, ctx, fields) end
---- @param name string
---- @param query string
---- @param ctx string
---- @param fields table
-function hilbish.completions.call(name, query, ctx, fields) end
 
---- The handler function is the callback for tab completion in Hilbish.
+--- This function contains the general completion handler for Hilbish. This function handles
---- You can check the completions doc for more info.
+--- completion of everything, which includes calling other command handlers, binaries, and files.
---- @param line string
+--- This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.
---- @param pos string
+--- 
-function hilbish.completions.handler(line, pos) end
+--- 
+function hilbish.completion.handler(line, pos) end
 
 --- Returns the current input line.
 function hilbish.editor.getLine() end
@@ -172,17 +168,15 @@ function hilbish.which(name) end
 --- Puts a job in the background. This acts the same as initially running a job.
 function hilbish.jobs:background() end
 
---- Returns binary/executale completion candidates based on the provided query.
+--- Return binaries/executables based on the provided parameters.
---- @param query string
+--- This function is meant to be used as a helper in a command completion handler.
---- @param ctx string
+--- 
---- @param fields table
+--- 
-function hilbish.completions.bins(query, ctx, fields) end
+function hilbish.completion.bins(query, ctx, fields) end
 
---- Returns file completion candidates based on the provided query.
+--- Returns file matches based on the provided parameters.
---- @param query string
+--- This function is meant to be used as a helper in a command completion handler.
---- @param ctx string
+function hilbish.completion.files(query, ctx, fields) end
---- @param fields table
-function hilbish.completions.files(query, ctx, fields) end
 
 --- Puts a job in the foreground. This will cause it to run like it was
 --- executed normally and wait for it to complete.