From 3cafbe8c4ff05479d902d1b331b27a76918b0b72 Mon Sep 17 00:00:00 2001 From: sammyette <38820196+TorchedSammy@users.noreply.github.com> Date: Sat, 16 Oct 2021 12:40:53 -0400 Subject: [PATCH] docs: document `hilbish` module functions, xdg vars, and add descriptions for modules --- golibs/bait/bait.go | 4 ++++ golibs/commander/commander.go | 4 +++- golibs/fs/fs.go | 6 ++++++ hilbish.go | 33 +++++++++++++++++++-------------- lua.go | 17 +++++++++++++++-- util/util.go | 10 ++++++++++ 6 files changed, 57 insertions(+), 17 deletions(-) create mode 100644 util/util.go diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index e97eef8..b8aab18 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -1,6 +1,8 @@ package bait import ( + "hilbish/util" + "github.com/chuckpreslar/emission" "github.com/yuin/gopher-lua" "layeh.com/gopher-luar" @@ -21,6 +23,8 @@ func (b *Bait) Loader(L *lua.LState) int { 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 diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index c11bf6d..67e8950 100644 --- a/golibs/commander/commander.go +++ b/golibs/commander/commander.go @@ -1,6 +1,8 @@ package commander import ( + "hilbish/util" + "github.com/chuckpreslar/emission" "github.com/yuin/gopher-lua" ) @@ -21,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.") L.Push(mod) return 1 diff --git a/golibs/fs/fs.go b/golibs/fs/fs.go index 28d141e..2ab851a 100644 --- a/golibs/fs/fs.go +++ b/golibs/fs/fs.go @@ -1,3 +1,5 @@ +// The fs module provides easy and simple access to filesystem functions and other +// things, and acts an addition to the Lua standard library's I/O and fs functions. package fs import ( @@ -5,6 +7,7 @@ import ( "os" "strings" + "hilbish/util" "github.com/yuin/gopher-lua" "layeh.com/gopher-luar" ) @@ -12,6 +15,9 @@ import ( func Loader(L *lua.LState) int { mod := L.SetFuncs(L.NewTable(), exports) + util.Document(L, mod, `The fs module provides easy and simple access to filesystem functions and other +things, and acts an addition to the Lua standard library's I/O and fs functions.`) + L.Push(mod) return 1 } diff --git a/hilbish.go b/hilbish.go index 2f9b135..58a7887 100644 --- a/hilbish.go +++ b/hilbish.go @@ -14,9 +14,9 @@ import ( ) var exports = map[string]lua.LGFunction { - "run": run, - "flag": flag, - "cwd": cwd, + "run": hlrun, + "flag": hlflag, + "cwd": hlcwd, } func HilbishLoader(L *lua.LState) int { @@ -29,23 +29,24 @@ 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)) + setField(L, mod, "ver", lua.LString(version), "The version of Hilbish") + setField(L, mod, "user", lua.LString(username), "Current user's username") + setField(L, mod, "host", lua.LString(host), "Hostname of the system") + setField(L, mod, "home", lua.LString(homedir), "Path of home directory") xdg := L.NewTable() - L.SetField(xdg, "config", lua.LString(confDir)) - L.SetField(xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/"))) - L.SetField(mod, "xdg", xdg) + setField(L, xdg, "config", lua.LString(confDir), "XDG config directory") + setField(L, xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/")), "XDG data directory") + setField(L, mod, "xdg", xdg, "XDG values for Linux") L.Push(mod) return 1 } -// Runs a command -func run(L *lua.LState) int { +// run(cmd) +// Runs `cmd` in Hilbish's sh interpreter +func hlrun(L *lua.LState) int { var exitcode uint8 = 0 cmd := L.CheckString(1) err := execCommand(cmd) @@ -60,7 +61,9 @@ func run(L *lua.LState) int { return 1 } -func flag(L *lua.LState) int { +// flag(f) +// Checks if the `f` flag has been passed to Hilbish. +func hlflag(L *lua.LState) int { flagchar := L.CheckString(1) L.Push(lua.LBool(getopt.Lookup([]rune(flagchar)[0]).Seen())) @@ -68,7 +71,9 @@ func flag(L *lua.LState) int { return 1 } -func cwd(L *lua.LState) int { +// cwd() +// Returns the current directory of the shell +func hlcwd(L *lua.LState) int { cwd, _ := os.Getwd() L.Push(lua.LString(cwd)) diff --git a/lua.go b/lua.go index 141d72e..4e7ceaa 100644 --- a/lua.go +++ b/lua.go @@ -8,6 +8,7 @@ import ( "syscall" "time" + "hilbish/util" "hilbish/golibs/bait" "hilbish/golibs/commander" "hilbish/golibs/fs" @@ -95,8 +96,20 @@ func RunLogin() { } } -// prompt(str) -// Changes the shell prompt to `str` +func setField(L *lua.LState, module lua.LValue, name string, val lua.LValue, doc string) { + if val.Type() == lua.LTTable { + util.Document(L, module, doc) + } + L.SetField(module, name, val) +} + +/* prompt(str) +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 */ func hshprompt(L *lua.LState) int { prompt = L.CheckString(1) diff --git a/util/util.go b/util/util.go new file mode 100644 index 0000000..a0ed738 --- /dev/null +++ b/util/util.go @@ -0,0 +1,10 @@ +package util + +import "github.com/yuin/gopher-lua" + +func Document(L *lua.LState, module lua.LValue, doc string) { + mt := L.NewTable() + L.SetField(mt, "__doc", lua.LString(doc)) + + L.SetMetatable(module, mt) +}