api.go

@@ -336,19 +336,9 @@ func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // alias(cmd, orig)
-// Sets an alias, with a name of `cmd` to another command.
+// Sets an alias of `cmd` to `orig`
-// #param cmd string Name of the alias
+// --- @param cmd string
-// #param orig string Command that will be aliased
+// --- @param orig string
-/*
-#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
@@ -368,20 +358,8 @@ func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // appendPath(dir)
-// Appends the provided dir to the command path (`$PATH`)
+// Appends `dir` to $PATH
-// #param dir string|table Directory (or directories) to append to path
+// --- @param dir string|table
-/*
-#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 completion
+// #interface completions
 // tab completions
 // The completions interface deals with tab completions.
 func completionLoader(rtm *rt.Runtime) *rt.Table {
 	exports := map[string]util.LuaExport{
-		"bins": {hcmpBins, 3, false},
+		"files": {luaFileComplete, 3, false},
-		"call": {hcmpCall, 4, false},
+		"bins": {luaBinaryComplete, 3, false},
-		"files": {hcmpFiles, 3, false},
+		"call": {callLuaCompleter, 4, false},
-		"handler": {hcmpHandler, 2, false},
+		"handler": {completionHandler, 2, false},
 	}
 
 	mod := rt.NewTable()
@@ -205,59 +205,27 @@ func completionLoader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
-// #interface completion
+// #interface completions
-// bins(query, ctx, fields) -> entries (table), prefix (string)
+// handler(line, pos)
-// Return binaries/executables based on the provided parameters.
+// The handler function is the callback for tab completion in Hilbish.
-// This function is meant to be used as a helper in a command completion handler.
+// You can check the completions doc for more info.
-// #param query string
+// --- @param line string
-// #param ctx string
+// --- @param pos string
-// #param fields table
+func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-/*
+	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 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`
+// Calls a completer function. This is mainly used to call
-// in the form of `command.name`, example: `command.git`.
+// a command completer, which will have a `name` in the form
-// You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.
+// of `command.name`, example: `command.git`.
-// #param name string
+// You can check `doc completions` for info on the `completionGroups` return value.
-// #param query string
+// --- @param name string
-// #param ctx string
+// --- @param query string
-// #param fields table
+// --- @param ctx string
-func hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// --- @param fields table
+func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(4); err != nil {
 		return nil, err
 	}
@@ -297,14 +265,13 @@ func hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return cont, nil
 }
 
-// #interface completion
+// #interface completions
 // files(query, ctx, fields) -> entries (table), prefix (string)
-// Returns file matches based on the provided parameters.
+// Returns file completion candidates based on the provided query.
-// This function is meant to be used as a helper in a command completion handler.
+// --- @param query string
-// #param query string
+// --- @param ctx string
-// #param ctx string
+// --- @param fields table
-// #param fields table
+func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-func hcmpFiles(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	query, ctx, fds, err := getCompleteParams(t, c)
 	if err != nil {
 		return nil, err
@@ -320,32 +287,28 @@ func hcmpFiles(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
 }
 
-// #interface completion
+// #interface completions
-// handler(line, pos)
+// bins(query, ctx, fields) -> entries (table), prefix (string)
-// This function contains the general completion handler for Hilbish. This function handles
+// Returns binary/executale completion candidates based on the provided query.
-// completion of everything, which includes calling other command handlers, binaries, and files.
+// --- @param query string
-// This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.
+// --- @param ctx string
-// #param line string The current Hilbish command line
+// --- @param fields table
-// #param pos number Numerical position of the cursor
+func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-/*
+	query, ctx, fds, err := getCompleteParams(t, c)
-#example
+	if err != nil {
--- stripped down version of the default implementation
+		return nil, err
-function hilbish.completion.handler(line, pos)
+	}
-	local query = fields[#fields]
 
-	if #fields == 1 then
+	completions, pfx := binaryComplete(query, ctx, fds)
-		-- call bins handler here
+	luaComps := rt.NewTable()
-	else
+
-		-- call command completer or files completer here
+	for i, comp := range completions {
-	end
+		luaComps.Set(rt.IntValue(int64(i + 1)), rt.StringValue(comp))
-end
+	}
-#example
+
-*/
+	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
-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: -100
+weight: -50
 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, with a name of `cmd` to another command.|
+|<a href="#alias">alias(cmd, orig)</a>|Sets an alias of `cmd` to `orig`|
-|<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
+|<a href="#appendPath">appendPath(dir)</a>|Appends `dir` to $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,25 +54,9 @@ hilbish.alias(cmd, orig)
 </a>
 </h4>
 
-Sets an alias, with a name of `cmd` to another command.  
+Sets an alias of `cmd` to `orig`  
-  
-  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-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'>
@@ -83,24 +67,9 @@ hilbish.appendPath(dir)
 </a>
 </h4>
 
-Appends the provided dir to the command path (`$PATH`)  
+Appends `dir` to $PATH  
-  
-  
 #### Parameters
-`string|table` **`dir`**  
+This function has no parameters.  
-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

@@ -1,145 +0,0 @@
----
-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

@@ -0,0 +1,76 @@
+---
+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,12 +1,3 @@
----
-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,12 +1,3 @@
----
-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,10 +1,3 @@
----
-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,10 +1,3 @@
----
-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,10 +1,3 @@
----
-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,12 +1,3 @@
----
-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,6 +14,22 @@ 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
 
@@ -33,36 +49,13 @@ function hilbish.editor.getChar() end
 --- @param text string
 function hilbish.editor.setVimRegister(register, text) end
 
---- Return binaries/executables based on the provided parameters.
+--- Sets an alias of `cmd` to `orig`
---- This function is meant to be used as a helper in a command completion handler.
+--- @param cmd string
---- 
+--- @param orig string
---- 
-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 the provided dir to the command path (`$PATH`)
+--- Appends `dir` to $PATH
---- 
+--- @param dir string|table
---- 
 function hilbish.appendPath(dir) end
 
 --- Registers a completion handler for `scope`.
@@ -178,6 +171,18 @@ 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