docs: add changelog for master

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Generate docs
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  gen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-go@v2
+      - name: Run docgen
+        run: go run cmd/docgen/docgen.go
+      - name: Commit new docs
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: "docs: [ci] generate new docs"
+          file_pattern: docs/ emmyLuaDocs/

CHANGELOG.md

@@ -1,6 +1,40 @@
 # 🎀 Changelog
 
-This is the changelog for the Hilbish shell made in Go and Lua.
+## Unreleased
+### Added
+- `catchOnce()` to bait - catches a hook once
+- `hilbish.aliases` interface - allows you to add, delete and list all aliases
+with Lua
+- `appendPath()` can now take a table of arguments for ease of use
+- Signal hooks `sigusr1` and `sigusr2`
+- Commands starting with a space won't be added to history
+
+### Fixed
+- Tab completion for executables
+- Stop interval (`interval()`) when an error occurs
+- Errors in bait hooks no longer cause a panic, and remove the handler for the hook as well
+- Formatting of home dir to ~
+- Check if Hilbish is in interactive before trying to use its handlers for signals
+- Global `args` table when running as script is no longer userdata
+- Home dir is now added to recent dirs (the case of cd with no arg)
+- `index` subdoc will no longer appear
+- Alias expansion with quotes
+
+### Changed
+- The minimal config is truly minimal now
+- (Possibly) **Breaking Change:** Change default SHLVL to 0 instead of 1
+- **Breaking Change:** ~/.hilbishrc.lua will no longer be run by default, it now
+only uses the paths mentioned below.
+- **Breaking Change:** Changed Hilbish's config path to something more suited
+according to the OS (`$XDG_CONFIG_HOME/hilbish/init.lua` on Linux,
+`~/Library/Application Support/hilbish/init.lua` on MacOs and
+(`%APPDATA%/hilbish/init.lua` on Windows). Previously on Unix-like it was 
+`$XDG_CONFIG_HOME/hilbish/hilbishrc.lua`
+- **Breaking Change:** The history path has been changed to a better suited path.
+On Linux, it is `$XDG_DATA_HOME/hilbish/.hilbish-history` and for others it is
+the config path.
+- **Breaking Change:** `hilbish.xdg` no longer exists, use `hilbish.userDir` instead,
+as it functions the same and is OS agnostic
 
 ## [0.7.1] - 2021-11-22
 ### Fixed

CONTRIBUTING.md

@@ -11,37 +11,38 @@ Use GitHub Issues to report any bugs or to request any features
 that may be useful to *anyone* else.
 
 Check [currently open issues](https://github.com/Rosettea/Hilbish/issues)
-and [closed ones](https://github.com/Rosettea/Hilbish/issues?q=is%3Aissue+is%3Aclosed) to make sure someone else hasn't already made the issue.
+and [closed ones](https://github.com/Rosettea/Hilbish/issues?q=is%3Aissue+is%3Aclosed)
+to make sure someone else hasn't already made the issue.
 
 For bug reports, be sure to include:
 - Hilbish Version (`hilbish -v`)
 - Ways to reproduce
 
 ## Code
-For any code contributions (Lua and/or Go), you should follow these
-rules:  
+For any code contributions (Lua and/or Go), you should follow these rules:  
 - Tab size 4 indentation
-- In Lua prefer no braces `()` if the function takes 1 argument
-- Use camelCase for function names
+- 80 line column limit, unless it breaks code or anything like that
+- In Lua prefer no braces `()` if the function takes 1 string argument
+- Use camelCase
 
 ### Making the Pull Request
 1. Ensure that any new install or build dependencies are documented in
-the README.md and PR request.
+the README.md and pull request.
 
-2. Say in the pull request details the changes to the shell,
-this includes useful file locations and breaking changes.
+2. Mention any and all changes, this includes useful file locations and
+breaking changes.
 
-3. We use [SemVer](http://semver.org/) for versioning and
+3. We use [Semver](http://semver.org/) for versioning and
 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
-for commit messages.
-Please document any backwards incompatible changes and be sure to name
-your commits correctly.
+for commit messages. Please document any breaking changes and be sure to
+write proper commits, or your pull request will not be considered.
 
-4. Finally, make the pull request to the **dev** branch.
+4. Finally, make the pull request.
 
 ## Finding Issues to Contribute to
 You can check out the [help wanted](https://github.com/Rosettea/Hilbish/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+)
 labels to figure out what we need your help working on.  
 
-The [up for grabs](https://github.com/Rosettea/Hilbish/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22+) labeled issues are low hanging fruit that should be
-easy for anyone. You can use this to get started on contributing!
+The [up for grabs](https://github.com/Rosettea/Hilbish/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22+)
+labeled issues are low hanging fruit that should be easy for anyone. You can
+use this to get started on contributing!

cmd/docgen/docgen.go

@@ -11,10 +11,24 @@ import (
 	"os"
 )
 
+type EmmyPiece struct {
+	FuncName string
+	Docs []string
+	Params []string // we only need to know param name to put in function
+}
+type DocPiece struct {
+	Doc []string
+	FuncSig string
+	FuncName string
+}
+
 // feel free to clean this up
 // it works, dont really care about the code
 func main() {
 	fset := token.NewFileSet()
+	os.Mkdir("docs", 0777)
+	os.Mkdir("emmyLuaDocs", 0777)
+	
 
 	dirs := []string{"./"}
 	filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error {
@@ -44,7 +58,8 @@ func main() {
 		"bait": "b",
 		"terminal": "term",
 	}
-	docs := make(map[string][]string)
+	docs := make(map[string][]DocPiece)
+	emmyDocs := make(map[string][]EmmyPiece)
 
 	for l, f := range pkgs {
 		p := doc.New(f, "./", doc.AllDecls)
@@ -55,8 +70,30 @@ func main() {
 			parts := strings.Split(strings.TrimSpace(t.Doc), "\n")
 			funcsig := parts[0]
 			doc := parts[1:]
-
-			docs[mod] = append(docs[mod], funcsig + " > " + strings.Join(doc, "\n"))
+			funcdoc := []string{}
+			em := EmmyPiece{FuncName: strings.TrimPrefix(t.Name, prefix[mod])}
+			for _, d := range doc {
+				if strings.HasPrefix(d, "---") {
+					emmyLine := strings.TrimSpace(strings.TrimPrefix(d, "---"))
+					emmyLinePieces := strings.Split(emmyLine, " ")
+					emmyType := emmyLinePieces[0]
+					if emmyType == "@param" {
+						em.Params = append(em.Params, emmyLinePieces[1])
+					}
+					em.Docs = append(em.Docs, d)
+				} else {
+					funcdoc = append(funcdoc, d)
+				}
+			}
+			
+			dps := DocPiece{
+				Doc: funcdoc,
+				FuncSig: funcsig,
+				FuncName: strings.TrimPrefix(t.Name, prefix[mod]),
+			}
+			
+			docs[mod] = append(docs[mod], dps)
+			emmyDocs[mod] = append(emmyDocs[mod], em)
 		}
 		for _, t := range p.Types {
 			for _, m := range t.Methods {
@@ -64,15 +101,64 @@ func main() {
 				parts := strings.Split(strings.TrimSpace(m.Doc), "\n")
 				funcsig := parts[0]
 				doc := parts[1:]
+				funcdoc := []string{}
+				em := EmmyPiece{FuncName: strings.TrimPrefix(m.Name, prefix[l])}
+				for _, d := range doc {
+					if strings.HasPrefix(d, "---") {
+						emmyLine := strings.TrimSpace(strings.TrimPrefix(d, "---"))
+						emmyLinePieces := strings.Split(emmyLine, " ")
+						emmyType := emmyLinePieces[0]
+						if emmyType == "@param" {
+							em.Params = append(em.Params, emmyLinePieces[1])
+						}
+						em.Docs = append(em.Docs, d)
+					} else {
+						funcdoc = append(funcdoc, d)
+					}
+				}
+				dps := DocPiece{
+					Doc: funcdoc,
+					FuncSig: funcsig,
+					FuncName: strings.TrimPrefix(m.Name, prefix[l]),
+				}
 
-				docs[l] = append(docs[l], funcsig + " > " + strings.Join(doc, "\n"))
+				docs[l] = append(docs[l], dps)
+				emmyDocs[l] = append(emmyDocs[l], em)
 			}
 		}
 	}
 
 	for mod, v := range docs {
-		os.Mkdir("docs", 0777)
+		if mod == "main" { continue }
 		f, _ := os.Create("docs/" + mod + ".txt")
-		f.WriteString(strings.Join(v, "\n\n") + "\n")
+		for _, dps := range v {
+			f.WriteString(dps.FuncSig + " > ")
+			for _, doc := range dps.Doc {
+				if !strings.HasPrefix(doc, "---") {
+					f.WriteString(doc + "\n")
+				}
+			}
+			f.WriteString("\n")
+		}
+	}
+	
+	for mod, v := range emmyDocs {
+		if mod == "main" { continue }
+		f, _ := os.Create("emmyLuaDocs/" + mod + ".lua")
+		f.WriteString("--- @meta\n\nlocal " + mod + " = {}\n\n")
+		for _, em := range v {
+			var funcdocs []string
+			for _, dps := range docs[mod] {
+				if dps.FuncName == em.FuncName {
+					funcdocs = dps.Doc
+				}
+			}
+			f.WriteString("--- " + strings.Join(funcdocs, "\n--- ") + "\n")
+			if len(em.Docs) != 0 {
+				f.WriteString(strings.Join(em.Docs, "\n") + "\n")
+			}
+			f.WriteString("function " + mod + "." + em.FuncName + "(" + strings.Join(em.Params, ", ") + ") end\n\n")
+		}
+		f.WriteString("return " + mod + "\n")
 	}
 }

docs/bait.txt

@@ -3,3 +3,4 @@ catch(name, cb) > Catches a hook with `name`. Runs the `cb` when it is thrown
 catchOnce(name, cb) > Same as catch, but only runs the `cb` once and then removes the hook
 
 throw(name, ...args) > Throws a hook with `name` with the provided `args`
+

docs/commander.txt

@@ -1,3 +1,4 @@
 deregister(name) > Deregisters any command registered with `name`
 
 register(name, cb) > Register a command with `name` that runs `cb` when ran
+

docs/fs.txt

@@ -5,3 +5,4 @@ mkdir(name, recursive) > Makes a directory called `name`. If `recursive` is true
 readdir(dir) > Returns a table of files in `dir`
 
 stat(path) > Returns info about `path`
+

docs/hilbish.txt

@@ -36,3 +36,4 @@ Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which s
 run(cmd) > Runs `cmd` in Hilbish's sh interpreter.
 
 timeout(cb, time) > Runs the `cb` function after `time` in milliseconds
+

docs/terminal.txt

@@ -6,3 +6,4 @@ saveState() > Saves the current state of the terminal
 
 size() > Gets the dimensions of the terminal. Returns a table with `width` and `height`
 Note: this is not the size in relation to the dimensions of the display
+

emmyLuaDocs/bait.lua

@@ -0,0 +1,20 @@
+--- @meta
+
+local bait = {}
+
+--- Catches a hook with `name`. Runs the `cb` when it is thrown
+--- @param name string
+--- @param cb function
+function bait.catch(name, cb) end
+
+--- Same as catch, but only runs the `cb` once and then removes the hook
+--- @param name string
+--- @param cb function
+function bait.catchOnce(name, cb) end
+
+--- Throws a hook with `name` with the provided `args`
+--- @param name string
+--- @vararg any
+function bait.throw(name) end
+
+return bait

emmyLuaDocs/commander.lua

@@ -0,0 +1,14 @@
+--- @meta
+
+local commander = {}
+
+--- Deregisters any command registered with `name`
+--- @param name string
+function commander.deregister(name) end
+
+--- Register a command with `name` that runs `cb` when ran
+--- @param name string
+--- @param cb function
+function commander.register(name, cb) end
+
+return commander

emmyLuaDocs/fs.lua

@@ -0,0 +1,23 @@
+--- @meta
+
+local fs = {}
+
+--- Changes directory to `dir`
+--- @param dir string
+function fs.cd(dir) end
+
+--- Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
+--- @param name string
+--- @param recursive boolean
+function fs.mkdir(name, recursive) end
+
+--- Returns a table of files in `dir`
+--- @param dir string
+--- @return table
+function fs.readdir(dir) end
+
+--- Returns info about `path`
+--- @param path string
+function fs.stat(path) end
+
+return fs

emmyLuaDocs/hilbish.lua

@@ -0,0 +1,58 @@
+--- @meta
+
+local hilbish = {}
+
+--- Sets an alias of `orig` to `cmd`
+function hilbish.alias() end
+
+--- Appends `dir` to $PATH
+function hilbish.appendPath() end
+
+--- Registers a completion handler for `scope`.
+--- A `scope` is currently only expected to be `command.<cmd>`,
+--- replacing <cmd> with the name of the command (for example `command.git`).
+--- `cb` must be a function that returns a table of the entries to complete.
+--- Nested tables will be used as sub-completions.
+function hilbish.complete() end
+
+--- Returns the current directory of the shell
+function hilbish.cwd() end
+
+--- Replaces running hilbish with `cmd`
+function hilbish.exec() end
+
+--- Checks if the `f` flag has been passed to Hilbish.
+function hilbish.flag() end
+
+--- Puts `fn` in a goroutine
+function hilbish.goroutine() end
+
+--- Runs the `cb` function every `time` milliseconds
+function hilbish.interval() end
+
+--- Changes the continued line prompt to `str`
+function hilbish.mlprompt() end
+
+--- Prepends `dir` to $PATH
+function hilbish.prependPath() end
+
+--- Changes the shell prompt to `str`
+--- There are a few verbs that can be used in the prompt text.
+--- These will be formatted and replaced with the appropriate values.
+--- `%d` - Current working directory
+--- `%u` - Name of current user
+--- `%h` - Hostname of device
+function hilbish.prompt() end
+
+--- Read input from the user, using Hilbish's line editor/input reader.
+--- This is a separate instance from the one Hilbish actually uses.
+--- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)
+function hilbish.read() end
+
+--- Runs `cmd` in Hilbish's sh interpreter.
+function hilbish.run() end
+
+--- Runs the `cb` function after `time` in milliseconds
+function hilbish.timeout() end
+
+return hilbish

emmyLuaDocs/terminal.lua

@@ -0,0 +1,18 @@
+--- @meta
+
+local terminal = {}
+
+--- Puts the terminal in raw mode
+function terminal.raw() end
+
+--- Restores the last saved state of the terminal
+function terminal.restoreState() end
+
+--- Saves the current state of the terminal
+function terminal.saveState() end
+
+--- Gets the dimensions of the terminal. Returns a table with `width` and `height`
+--- Note: this is not the size in relation to the dimensions of the display
+function terminal.size() end
+
+return terminal

golibs/bait/bait.go

@@ -47,18 +47,24 @@ failed, etc. To find all available hooks, see doc hooks.`)
 
 // throw(name, ...args)
 // Throws a hook with `name` with the provided `args`
+// --- @param name string
+// --- @vararg any
 func (b *Bait) bthrow(name string, args ...interface{}) {
 	b.Em.Emit(name, args...)
 }
 
 // catch(name, cb)
 // Catches a hook with `name`. Runs the `cb` when it is thrown
+// --- @param name string
+// --- @param cb function
 func (b *Bait) bcatch(name string, catcher func(...interface{})) {
 	b.Em.On(name, catcher)
 }
 
 // catchOnce(name, cb)
 // Same as catch, but only runs the `cb` once and then removes the hook
+// --- @param name string
+// --- @param cb function
 func (b *Bait) bcatchOnce(name string, catcher func(...interface{})) {
 	b.Em.Once(name, catcher)
 }

golibs/commander/commander.go

@@ -23,7 +23,7 @@ func (c *Commander) Loader(L *lua.LState) int {
 		"deregister": c.cderegister,
 	}
 	mod := L.SetFuncs(L.NewTable(), exports)
-	util.Document(L, mod, "Commander is Hilbish's custom command library, a way to write commands with the shell in Lua.")
+	util.Document(L, mod, "Commander is Hilbish's custom command library, a way to write commands in Lua.")
 	L.Push(mod)
 
 	return 1
@@ -31,6 +31,8 @@ func (c *Commander) Loader(L *lua.LState) int {
 
 // register(name, cb)
 // Register a command with `name` that runs `cb` when ran
+// --- @param name string
+// --- @param cb function
 func (c *Commander) cregister(L *lua.LState) int {
 	cmdName := L.CheckString(1)
 	cmd := L.CheckFunction(2)
@@ -42,6 +44,7 @@ func (c *Commander) cregister(L *lua.LState) int {
 
 // deregister(name)
 // Deregisters any command registered with `name`
+// --- @param name string
 func (c *Commander) cderegister(L *lua.LState) int {
 	cmdName := L.CheckString(1)
 

golibs/fs/fs.go

@@ -31,6 +31,7 @@ var exports = map[string]lua.LGFunction{
 
 // cd(dir)
 // Changes directory to `dir`
+// --- @param dir string
 func fcd(L *lua.LState) int {
 	path := L.CheckString(1)
 
@@ -45,6 +46,8 @@ func fcd(L *lua.LState) int {
 
 // mkdir(name, recursive)
 // Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
+// --- @param name string
+// --- @param recursive boolean
 func fmkdir(L *lua.LState) int {
 	dirname := L.CheckString(1)
 	recursive := L.ToBool(2)
@@ -65,6 +68,7 @@ func fmkdir(L *lua.LState) int {
 
 // stat(path)
 // Returns info about `path`
+// --- @param path string
 func fstat(L *lua.LState) int {
 	path := L.CheckString(1)
 
@@ -85,6 +89,8 @@ func fstat(L *lua.LState) int {
 
 // readdir(dir)
 // Returns a table of files in `dir`
+// --- @param dir string
+// --- @return table
 func freaddir(L *lua.LState) int {
 	dir := L.CheckString(1)
 	names := L.NewTable()