chore: reorder hilbish.completion functions

api.go

@@ -336,9 +336,19 @@ func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // alias(cmd, orig)
-// Sets an alias of `cmd` to `orig`
-// --- @param cmd string
-// --- @param orig string
+// Sets an alias, with a name of `cmd` to another command.
+// #param cmd string Name of the alias
+// #param orig string Command that will be aliased
+/*
+#example
+-- With this, "ga file" will turn into "git add file"
+hilbish.alias('ga', 'git add')
+
+-- Numbered substitutions are supported here!
+hilbish.alias('dircount', 'ls %1 | wc -l')
+-- "dircount ~" would count how many files are in ~ (home directory).
+#example
+*/
 func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -358,8 +368,20 @@ func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // appendPath(dir)
-// Appends `dir` to $PATH
-// --- @param dir string|table
+// Appends the provided dir to the command path (`$PATH`)
+// #param dir string|table Directory (or directories) to append to path
+/*
+#example
+hilbish.appendPath '~/go/bin'
+-- Will add ~/go/bin to the command path.
+
+-- Or do multiple:
+hilbush.appendPath {
+	'~/go/bin',
+	'~/.local/bin'
+}
+#example
+*/
 func hlappendPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

complete.go

@@ -188,15 +188,15 @@ 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},
-		"handler": {completionHandler, 2, false},
+		"bins": {hcmpBins, 3, false},
+		"call": {hcmpCall, 4, false},
+		"files": {hcmpFiles, 3, false},
+		"handler": {hcmpHandler, 2, false},
 	}
 
 	mod := rt.NewTable()
@@ -205,27 +205,59 @@ 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 hcmpBins(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
-func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// 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 hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(4); err != nil {
 		return nil, err
 	}
@@ -265,13 +297,14 @@ 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
-func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// 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 hcmpFiles(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	query, ctx, fds, err := getCompleteParams(t, c)
 	if err != nil {
 		return nil, err
@@ -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 hcmpHandler(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

docs/api/_index.md

@@ -1,7 +1,7 @@
 ---
 title: API
 layout: doc
-weight: -50
+weight: -100
 menu: docs
 ---
 

docs/api/hilbish/_index.md

@@ -14,8 +14,8 @@ interfaces and functions which directly relate to shell functionality.
 ## Functions
 |||
 |----|----|
-|<a href="#alias">alias(cmd, orig)</a>|Sets an alias of `cmd` to `orig`|
-|<a href="#appendPath">appendPath(dir)</a>|Appends `dir` to $PATH|
+|<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
+|<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
 |<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for `scope`.|
 |<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
 |<a href="#exec">exec(cmd)</a>|Replaces running hilbish with `cmd`|
@@ -54,9 +54,25 @@ hilbish.alias(cmd, orig)
 </a>
 </h4>
 
-Sets an alias of `cmd` to `orig`  
+Sets an alias, with a name of `cmd` to another command.  
+  
+  
 #### Parameters
-This function has no parameters.  
+`string` **`cmd`**  
+Name of the alias
+
+`string` **`orig`**  
+Command that will be aliased
+
+#### Example
+```lua
+-- With this, "ga file" will turn into "git add file"
+hilbish.alias('ga', 'git add')
+
+-- Numbered substitutions are supported here!
+hilbish.alias('dircount', 'ls %1 | wc -l')
+-- "dircount ~" would count how many files are in ~ (home directory).
+````
 </div>
 
 <hr><div id='appendPath'>
@@ -67,9 +83,24 @@ hilbish.appendPath(dir)
 </a>
 </h4>
 
-Appends `dir` to $PATH  
+Appends the provided dir to the command path (`$PATH`)  
+  
+  
 #### Parameters
-This function has no parameters.  
+`string|table` **`dir`**  
+Directory (or directories) to append to path
+
+#### Example
+```lua
+hilbish.appendPath '~/go/bin'
+-- Will add ~/go/bin to the command path.
+
+-- Or do multiple:
+hilbush.appendPath {
+	'~/go/bin',
+	'~/.local/bin'
+}
+````
 </div>
 
 <hr><div id='complete'>

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.bins">bins(query, ctx, fields) -> entries (table), prefix (string)</a>|Return binaries/executables based on the provided parameters.|
+|<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.files">files(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns file matches based on the provided parameters.|
+|<a href="#completion.handler">handler(line, pos)</a>|This function contains the general completion handler for Hilbish. This function handles|
+
+<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.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.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>
+
+<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>
+

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>
-

docs/completions.md

@@ -1,3 +1,12 @@
+---
+title: Completions
+description: Tab completion for commands.
+layout: doc
+menu: 
+  docs:
+    parent: "Features"
+---
+
 Hilbish has a pretty good completion system. It has a nice looking
 menu, with 2 types of menus: grid (like file completions) or
 list.

docs/jobs.md

@@ -1,3 +1,12 @@
+---
+title: Jobs
+description: Controls for background commands in Hilbish.
+layout: doc
+menu: 
+  docs:
+    parent: "Features"
+---
+
 Hilbish has pretty standard job control. It's missing one or two things,
 but works well. One thing which is different from other shells
 (besides Hilbish) itself is the API for jobs, and of course it's in Lua.

docs/lunacolors.md

@@ -1,3 +1,10 @@
+---
+title: Lunacolors
+layout: doc
+weight: -60
+menu: docs
+---
+
 Lunacolors is an ANSI color/styling library for Lua. It is included
 by default in standard Hilbish distributions to provide easy styling
 for things like prompts and text.

docs/nature/_index.md

@@ -1,3 +1,10 @@
+---
+title: Nature
+layout: doc
+weight: -90
+menu: docs
+---
+
 A bit after creation, we have the outside nature. Little plants, seeds,
 growing to their final phase: a full plant. A lot of Hilbish itself is
 written in Go, but there are parts made in Lua, being most builtins

docs/vim-mode/_index.md

@@ -1,3 +1,10 @@
+---
+title: Vim Mode
+layout: doc
+weight: -90
+menu: docs
+---
+
 Hilbish has a Vim binding input mode accessible for use.
 It can be enabled with the `hilbish.inputMode` function (check `doc hilbish`).
 

docs/vim-mode/actions.md

@@ -1,3 +1,12 @@
+---
+title: Actions
+layout: doc
+weight: -80
+menu: 
+  docs:
+    parent: "Vim Mode"
+---
+
 Vim actions are essentially just when a user uses a Vim keybind.
 Things like yanking and pasting are Vim actions.
 This is not an "offical Vim thing," just a Hilbish thing.

emmyLuaDocs/hilbish.lua

@@ -14,22 +14,6 @@ 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
---- 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
-function hilbish.completions.call(name, query, ctx, fields) end
-
---- 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
-function hilbish.completions.handler(line, pos) end
-
 --- Returns the current input line.
 function hilbish.editor.getLine() end
 
@@ -49,13 +33,36 @@ function hilbish.editor.getChar() end
 --- @param text string
 function hilbish.editor.setVimRegister(register, text) end
 
---- Sets an alias of `cmd` to `orig`
---- @param cmd string
---- @param orig string
+--- Return binaries/executables based on the provided parameters.
+--- This function is meant to be used as a helper in a command completion handler.
+--- 
+--- 
+function hilbish.completion.bins(query, ctx, fields) end
+
+--- 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.
+function hilbish.completion.call(name, query, ctx, fields) end
+
+--- Returns file matches based on the provided parameters.
+--- This function is meant to be used as a helper in a command completion handler.
+function hilbish.completion.files(query, ctx, fields) end
+
+--- 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.
+--- 
+--- 
+function hilbish.completion.handler(line, pos) end
+
+--- Sets an alias, with a name of `cmd` to another command.
+--- 
+--- 
 function hilbish.alias(cmd, orig) end
 
---- Appends `dir` to $PATH
---- @param dir string|table
+--- Appends the provided dir to the command path (`$PATH`)
+--- 
+--- 
 function hilbish.appendPath(dir) end
 
 --- Registers a completion handler for `scope`.
@@ -171,18 +178,6 @@ 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.
---- @param query string
---- @param ctx string
---- @param fields table
-function hilbish.completions.bins(query, ctx, fields) end
-
---- Returns file completion candidates based on the provided query.
---- @param query string
---- @param ctx string
---- @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.
 function hilbish.jobs:foreground() end