docs: clarify what a scope is

check if commander has an error before trying to get a return code

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 This is the changelog for the Hilbish shell made in Go and Lua.
 
+## [0.7.0] - 2021-11-22
+### Added
+- `hilbish.interactive` and `hilbish.login` properties to figure out if Hilbish is interactive or a login shell, respectively.
+- `hilbish.read` function to take input more elegantly than Lua's `io.read`
+- Tab Completion Enhancements
+  - A new tab complete API has been added. It is the single `complete` function which takes a "scope" (example: `command.<cmdname>`) and a callback which is
+  expected to return a table. Users can now add custom completions for specific commands.
+  An example is:
+  ```lua
+  complete('command.git', function()
+	return {
+		'add',
+		'version',
+		commit = {
+			'--message',
+			'--verbose',
+			'<file>'
+		}
+	}
+  end)
+  ```
+  For `git`, Hilbish will complete commands add, version and commit. For the commit subcommand, it will complete the flags and/or files which `<file>` is used to represent.
+  - Hilbish will now complete binaries in $PATH, or any executable to a path (like `./` or `../`)
+  - Files with spaces will be automatically put in quotes and completions will work for them now.
+- `prependPath` function (#81)
+- Signal hooks (#80)
+  - This allows scripts to add their own way of handling terminal resizes (if you'd need that) or Ctrl-C
+- Module properties (like `hilbish.ver`) are documented with the `doc` command.
+- Document bait hooks
+
+### Fixed
+- The prompt won't come up on terminal resize anymore.
+- `appendPath` should work properly on Windows.
+- A panic when a commander has an error has been fixed.
+
 ## [0.6.1] - 2021-10-21
 ### Fixed
 - Require paths now use the `dataDir` variable so there is no need to change it anymore unless you want to add more paths
@@ -249,6 +284,7 @@ This input for example will prompt for more input to complete:
 
 First "stable" release of Hilbish.
 
+[0.7.0]: https://github.com/Rosettea/Hilbish/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/Rosettea/Hilbish/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/Rosettea/Hilbish/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/Rosettea/Hilbish/compare/v0.5.0...v0.5.1

docs/hooks/command.txt

@@ -0,0 +1,7 @@
++ `command.exit` -> code, cmdStr > Thrown when a command exits.
+`code` is the exit code of the command, and `cmdStr` is the command that was run.
+
++ `command.not-found` -> cmdStr > Thrown when a command is not found.
+
++ `command.no-perm` -> cmdStr > Thrown when Hilbish attempts to execute a file but
+has no permission.

docs/hooks/index.txt

@@ -0,0 +1,8 @@
+Here is listed all scopes for bait hooks. If a hook is related to a command,
+it will have the `command` scope, as example.
+
+Here is the format for a doc for a hook:
++ <hook name> -> <args> > <description>
+
+`<args>` just means the arguments of the hook. If a hook doc has the format
+of `arg...`, it means the hook can take/recieve any number of `arg`.

docs/hooks/signal.txt

@@ -0,0 +1,3 @@
++ `signal.sigint` > Sent when Hilbish receives SIGINT (used to Ctrl-C).
+
++ `signal.resize` > Sent when the terminal is resized.

golibs/bait/bait.go

@@ -20,15 +20,19 @@ func New() Bait {
 
 func (b *Bait) Loader(L *lua.LState) int {
 	mod := L.SetFuncs(L.NewTable(), map[string]lua.LGFunction{})
+
+	util.Document(L, mod,
+`Bait is the event emitter for Hilbish. Why name it bait?
+Because it throws hooks that you can catch (emits events
+that you can listen to) and because why not, fun naming
+is fun. This is what you will use if you want to listen
+in on hooks to know when certain things have happened,
+like when you've changed directory, a command has
+failed, etc. To find all available hooks, see doc hooks.`)
+
 	L.SetField(mod, "throw", luar.New(L, b.bthrow))
 	L.SetField(mod, "catch", luar.New(L, b.bcatch))
 
-	util.Document(L, mod, `Bait is the event emitter for Hilbish. Why name it bait?
-Because it throws hooks that you can catch
-(emits events that you can listen to) and because why not,
-fun naming is fun. This is what you will use if you want to
-listen in on hooks to know when certain things have happened,
-like when you've changed directory, a command has failed, etc.`)
 	L.Push(mod)
 
 	return 1

hilbish.go

@@ -32,13 +32,13 @@ func HilbishLoader(L *lua.LState) int {
 		username = strings.Split(username, "\\")[1] // for some reason Username includes the hostname on windows
 	}
 
-	L.SetField(mod, "ver", lua.LString(version))
-	L.SetField(mod, "user", lua.LString(username))
-	L.SetField(mod, "host", lua.LString(host))
-	L.SetField(mod, "home", lua.LString(homedir))
-	L.SetField(mod, "dataDir", lua.LString(dataDir))
-	L.SetField(mod, "interactive", lua.LBool(interactive))
-	L.SetField(mod, "login", lua.LBool(interactive))
+	util.SetField(L, mod, "ver", lua.LString(version), "Hilbish version")
+	util.SetField(L, mod, "user", lua.LString(username), "Username of user")
+	util.SetField(L, mod, "host", lua.LString(host), "Host name of the machine")
+	util.SetField(L, mod, "home", lua.LString(homedir), "Home directory of the user")
+	util.SetField(L, mod, "dataDir", lua.LString(dataDir), "Directory for Hilbish's data files")
+	util.SetField(L, mod, "interactive", lua.LBool(interactive), "If this is an interactive shell")
+	util.SetField(L, mod, "login", lua.LBool(interactive), "Whether this is a login shell")
 
 	xdg := L.NewTable()
 	L.SetField(xdg, "config", lua.LString(confDir))

lua.go

@@ -32,6 +32,7 @@ func LuaInit() {
 	l.SetGlobal("multiprompt", l.NewFunction(hshmlprompt))
 	l.SetGlobal("alias", l.NewFunction(hshalias))
 	l.SetGlobal("appendPath", l.NewFunction(hshappendPath))
+	l.SetGlobal("prependPath", l.NewFunction(hshprependPath))
 	l.SetGlobal("exec", l.NewFunction(hshexec))
 	l.SetGlobal("goro", luar.New(l, hshgoroutine))
 	l.SetGlobal("timeout", luar.New(l, hshtimeout))
@@ -58,6 +59,13 @@ func LuaInit() {
 	hooks = bait.New()
 	l.PreloadModule("bait", hooks.Loader)
 
+	// Add Ctrl-C handler
+	hooks.Em.On("signal.sigint", func() {
+		if !interactive {
+			os.Exit(0)
+		}
+	})
+
 	l.SetGlobal("complete", l.NewFunction(hshcomplete))
 
 	// Add more paths that Lua can require from
@@ -140,7 +148,7 @@ func hshappendPath(L *lua.LState) int {
 
 	// if dir isnt already in $PATH, add it
 	if !strings.Contains(pathenv, dir) {
-		os.Setenv("PATH", pathenv + ":" + dir)
+		os.Setenv("PATH", pathenv + string(os.PathListSeparator) + dir)
 	}
 
 	return 0
@@ -226,3 +234,18 @@ func hshcomplete(L *lua.LState) int {
 
 	return 0
 }
+
+// prependPath(dir)
+// Prepends `dir` to $PATH
+func hshprependPath(L *lua.LState) int {
+	dir := L.CheckString(1)
+	dir = strings.Replace(dir, "~", curuser.HomeDir, 1)
+	pathenv := os.Getenv("PATH")
+
+	// if dir isnt already in $PATH, add in
+	if !strings.Contains(pathenv, dir) {
+		os.Setenv("PATH", dir + string(os.PathListSeparator) + pathenv)
+	}
+
+	return 0
+}

main.go

@@ -265,13 +265,12 @@ func HandleSignals() {
 	for s := range c {
 		switch s {
 		case os.Interrupt:
+			hooks.Em.Emit("signals.sigint")
 			if !running {
-				if !interactive {
-					os.Exit(0)
-				}
 				lr.ClearInput()
 			}
 		case syscall.SIGWINCH:
+			hooks.Em.Emit("signals.resize")
 			if !running {
 				lr.Resize()
 			}

preload.lua

@@ -49,41 +49,90 @@ commander.register('doc', function(args)
 	local moddocPath = hilbish.dataDir .. '/docs/'
 	local globalDesc = [[
 These are the global Hilbish functions that are always available and not part of a module.]]
+	local modDocFormat = [[
+%s
+%s
+# Functions
+]]
+
 	if #args > 0 then
-		local mod = table.concat(args, ' '):gsub('^%s*(.-)%s*$', '%1')
+		local mod = args[1]
 
 		local f = io.open(moddocPath .. mod .. '.txt', 'rb')
+		local funcdocs = nil
 		if not f then
-			print('Could not find docs for module named ' .. mod .. '.')
-			return 1
+			-- assume subdir
+			-- dataDir/docs/<mod>/<mod>.txt
+			moddocPath = moddocPath .. mod .. '/'
+			local subdocName = args[2]
+			if not subdocName then
+				subdocName = 'index'
+			end
+			f = io.open(moddocPath .. subdocName .. '.txt', 'rb')
+			if not f then
+				print('No documentation found for ' .. mod .. '.')
+				return
+			end
+			funcdocs = f:read '*a'
+			local subdocs = table.map(fs.readdir(moddocPath), function(f)
+				return lunacolors.underline(lunacolors.blue(string.gsub(f, '.txt', '')))
+			end)
+			if subdocName == 'index' then
+				funcdocs = funcdocs .. '\nSubdocs: ' .. table.concat(subdocs, ', ')
+			end
 		end
 
-		local desc = (mod == 'global' and globalDesc or getmetatable(require(mod)).__doc)
-		local funcdocs = f:read '*a'
+		if not funcdocs then
+			funcdocs = f:read '*a'
+		end
+		local desc = ''
+		local ok = pcall(require, mod)
 		local backtickOccurence = 0
-		print(desc .. '\n\n' .. lunacolors.format(funcdocs:sub(1, #funcdocs - 1):gsub('`', function()
+		local formattedFuncs = lunacolors.format(funcdocs:sub(1, #funcdocs - 1):gsub('`', function()
 			backtickOccurence = backtickOccurence + 1
 			if backtickOccurence % 2 == 0 then
 				return '{reset}'
 			else
 				return '{underline}{green}'
 			end
-		end)))
+		end))
+
+		if mod == 'global' or ok then
+			local props = {}
+			local propstr = ''
+			local modDesc = globalDesc
+			if ok then
+				local modmt = getmetatable(require(mod))
+				modDesc = modmt.__doc
+				if modmt.__docProp then
+					-- not all modules have docs for properties
+					props = table.map(modmt.__docProp, function(v, k)
+						return lunacolors.underline(lunacolors.blue(k)) .. ' > ' .. v
+					end)
+				end
+			end
+			if #props > 0 then
+				propstr = '\n# Properties\n' .. table.concat(props, '\n') .. '\n'
+			end
+			desc = string.format(modDocFormat, modDesc, propstr)
+		end
+		print(desc .. formattedFuncs)
 		f:close()
 
 		return
 	end
 	local modules = table.map(fs.readdir(moddocPath), function(f)
-		return lunacolors.underline(lunacolors.blue(f:sub(1, -5)))
+		return lunacolors.underline(lunacolors.blue(string.gsub(f, '.txt', '')))
 	end)
 
 	io.write [[
 Welcome to Hilbish's doc tool! Here you can find documentation for builtin
 functions and other things.
 
-Usage: doc <module>
+Usage: doc <section> [subdoc]
+A section is a module or a literal section and a subdoc is a subsection for it.
 
-Available modules: ]]
+Available sections: ]]
 
 	print(table.concat(modules, ', '))
 

rl.go

@@ -8,9 +8,9 @@ package main
 // this is normal readline
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
-	"os"
 
 	"github.com/Rosettea/readline"
 	"github.com/yuin/gopher-lua"
@@ -25,12 +25,24 @@ func NewLineReader(prompt string) *LineReader {
 		var completions []string
 		// trim whitespace from ctx
 		ctx = strings.TrimLeft(ctx, " ")
-		fields := strings.Split(ctx, " ")
-
+		fields, ctx := splitInput(ctx)
 		if len(fields) == 0 {
 			return nil
 		}
 
+		for aliases[fields[0]] != "" {
+			alias := aliases[fields[0]]
+			ctx = alias + strings.TrimPrefix(ctx, fields[0])
+			fields = strings.Split(ctx, " ")
+
+			if aliases[fields[0]] == alias {
+				break
+			}
+			if aliases[fields[0]] != "" {
+				continue
+			}
+		}
+
 		if len(fields) == 1 {
 			prefixes := []string{"./", "../"}
 			for _, prefix := range prefixes {

shell.go

@@ -124,6 +124,13 @@ func execCommand(cmd string) error {
 				NRet:    1,
 				Protect: true,
 			}, luacmdArgs)
+			
+			if err != nil {
+				fmt.Fprintln(os.Stderr,
+					"Error in command:\n\n" + err.Error())
+				return interp.NewExitStatus(1)
+			}
+
 			luaexitcode := l.Get(-1)
 			var exitcode uint8 = 0
 
@@ -133,10 +140,6 @@ func execCommand(cmd string) error {
 				exitcode = uint8(code)
 			}
 
-			if err != nil {
-				fmt.Fprintln(os.Stderr,
-					"Error in command:\n\n" + err.Error())
-			}
 			cmdFinish(exitcode, argstring)
 			return interp.NewExitStatus(exitcode)
 		}

util/util.go

@@ -2,9 +2,31 @@ package util
 
 import "github.com/yuin/gopher-lua"
 
+// Document adds a documentation string to a module.
+// It is accessible via the __doc metatable.
 func Document(L *lua.LState, module lua.LValue, doc string) {
-	mt := L.NewTable()
+	mt := L.GetMetatable(module)
+	if mt == lua.LNil {
+		mt = L.NewTable()
+		L.SetMetatable(module, mt)
+	}
 	L.SetField(mt, "__doc", lua.LString(doc))
+}
+
+// SetField sets a field in a table, adding docs for it.
+// It is accessible via the __docProp metatable. It is a table of the names of the fields.
+func SetField(L *lua.LState, module lua.LValue, field string, value lua.LValue, doc string) {
+	mt := L.GetMetatable(module)
+	if mt == lua.LNil {
+		mt = L.NewTable()
+		docProp := L.NewTable()
+		L.SetField(mt, "__docProp", docProp)
 
 		L.SetMetatable(module, mt)
+	}
+	docProp := L.GetTable(mt, lua.LString("__docProp"))
+
+	L.SetField(docProp, field, lua.LString(doc))
+	L.SetField(module, field, value)
 }
+