diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 99b5188..3559ae1 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -26,7 +26,7 @@ type emmyPiece struct { } type module struct { - Docs map[string]docPiece + Docs []docPiece ShortDescription string Description string Interface bool @@ -119,19 +119,19 @@ func main() { for l, f := range pkgs { p := doc.New(f, "./", doc.AllDecls) - pieces := make(map[string]docPiece) + pieces := []docPiece{} mod := l for _, t := range p.Funcs { piece := setupDoc(mod, t) if piece != nil { - pieces[piece.FuncName] = *piece + pieces = append(pieces, *piece) } } for _, t := range p.Types { for _, m := range t.Methods { piece := setupDoc(mod, m) if piece != nil { - pieces[piece.FuncName] = *piece + pieces = append(pieces, *piece) } } } @@ -151,7 +151,6 @@ func main() { if mod == "main" { modN = "hilbish" } - fmt.Println(mod) f, _ := os.Create("docs/api/" + modN + ".md") f.WriteString(fmt.Sprintf(header, modN, v.ShortDescription)) f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n## Functions\n", v.Description)) @@ -168,8 +167,12 @@ func main() { ff, _ := os.Create("emmyLuaDocs/" + modN + ".lua") ff.WriteString("--- @meta\n\nlocal " + modN + " = {}\n\n") for _, em := range emmyDocs[mod] { - funcdocs := v.Docs[em.FuncName].Doc - fmt.Println(funcdocs) + funcdocs := []string{} + for _, dps := range docs[mod].Docs{ + if dps.FuncName == em.FuncName { + funcdocs = dps.Doc + } + } ff.WriteString("--- " + strings.Join(funcdocs, "\n--- ") + "\n") if len(em.Docs) != 0 { ff.WriteString(strings.Join(em.Docs, "\n") + "\n") diff --git a/docs/api/bait.md b/docs/api/bait.md index 575a265..829ba86 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -1,31 +1,91 @@ --- name: Module bait -description: the event emitter +description: the core Hilbish API layout: apidoc --- ## Introduction -Bait is the event emitter for Hilbish. Why name it bait? Why not. -It throws hooks that you can catch. 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 thrown by Hilbish, see doc hooks. +The Hilbish module includes the core API, containing +interfaces and functions which directly relate to shell functionality. ## Functions -### catchOnce(name, cb) -Same as catch, but only runs the `cb` once and then removes the hook +### alias(cmd, orig) +Sets an alias of `cmd` to `orig` -### hooks(name) -> {cb, cb...} -Returns a table with hooks on the event with `name`. +### appendPath(dir) +Appends `dir` to $PATH -### release(name, catcher) -Removes the `catcher` for the event with `name` -For this to work, `catcher` has to be the same function used to catch -an event, like one saved to a variable. +### complete(scope, cb) +Registers a completion handler for `scope`. +A `scope` is currently only expected to be `command.`, +replacing with the name of the command (for example `command.git`). +`cb` must be a function that returns a table of "completion groups." +Check `doc completions` for more information. -### throw(name, ...args) -Throws a hook with `name` with the provided `args` +### cwd() +Returns the current directory of the shell -### catch(name, cb) -Catches a hook with `name`. Runs the `cb` when it is thrown +### exec(cmd) +Replaces running hilbish with `cmd` + +### goro(fn) +Puts `fn` in a goroutine + +### highlighter(line) +Line highlighter handler. This is mainly for syntax highlighting, but in +reality could set the input of the prompt to *display* anything. The +callback is passed the current line and is expected to return a line that +will be used as the input display. + +### hinter(line, pos) +The command line hint handler. It gets called on every key insert to +determine what text to use as an inline hint. It is passed the current +line and cursor position. It is expected to return a string which is used +as the text for the hint. This is by default a shim. To set hints, +override this function with your custom handler. + +### inputMode(mode) +Sets the input mode for Hilbish's line reader. Accepts either emacs or vim + +### interval(cb, time) +Runs the `cb` function every `time` milliseconds. +Returns a `timer` object (see `doc timers`). + +### multiprompt(str) +Changes the continued line prompt to `str` + +### prependPath(dir) +Prepends `dir` to $PATH + +### prompt(str, typ?) +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 + +### read(prompt?) -> input? +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) + +### run(cmd, returnOut) -> exitCode, stdout, stderr +Runs `cmd` in Hilbish's sh interpreter. +If returnOut is true, the outputs of `cmd` will be returned as the 2nd and +3rd values instead of being outputted to the terminal. + +### runnerMode(mode) +Sets the execution/runner mode for interactive Hilbish. This determines whether +Hilbish wll try to run input as Lua and/or sh or only do one of either. +Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), +sh, and lua. It also accepts a function, to which if it is passed one +will call it to execute user input instead. + +### timeout(cb, time) +Runs the `cb` function after `time` in milliseconds +Returns a `timer` object (see `doc timers`). + +### which(name) +Checks if `name` is a valid command diff --git a/docs/api/commander.md b/docs/api/commander.md index 379ecba..01031d6 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -1,16 +1,23 @@ --- name: Module commander -description: library for custom commands +description: low level terminal library layout: apidoc --- ## Introduction -Commander is a library for writing custom commands in Lua. +The terminal library is a simple and lower level library for certain terminal interactions. ## Functions -### deregister(name) -Deregisters any command registered with `name` +### restoreState() +Restores the last saved state of the terminal -### register(name, cb) -Register a command with `name` that runs `cb` when ran +### saveState() +Saves the current state of the terminal + +### setRaw() +Puts the terminal in raw mode + +### 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 diff --git a/docs/api/fs.md b/docs/api/fs.md index da9b005..3a9db21 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -1,43 +1,91 @@ --- name: Module fs -description: filesystem interaction and functionality library +description: the core Hilbish API layout: apidoc --- ## Introduction -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 filesystem functions. +The Hilbish module includes the core API, containing +interfaces and functions which directly relate to shell functionality. ## Functions -### basename(path) -Gives the basename of `path`. For the rules, -see Go's filepath.Base +### alias(cmd, orig) +Sets an alias of `cmd` to `orig` -### cd(dir) -Changes directory to `dir` +### appendPath(dir) +Appends `dir` to $PATH -### dir(path) -Returns the directory part of `path`. For the rules, see Go's -filepath.Dir +### complete(scope, cb) +Registers a completion handler for `scope`. +A `scope` is currently only expected to be `command.`, +replacing with the name of the command (for example `command.git`). +`cb` must be a function that returns a table of "completion groups." +Check `doc completions` for more information. -### readdir(dir) -Returns a table of files in `dir` +### cwd() +Returns the current directory of the shell -### abs(path) -Gives an absolute version of `path`. +### exec(cmd) +Replaces running hilbish with `cmd` -### glob(pattern) -Glob all files and directories that match the pattern. -For the rules, see Go's filepath.Glob +### goro(fn) +Puts `fn` in a goroutine -### join(paths...) -Takes paths and joins them together with the OS's -directory separator (forward or backward slash). +### highlighter(line) +Line highlighter handler. This is mainly for syntax highlighting, but in +reality could set the input of the prompt to *display* anything. The +callback is passed the current line and is expected to return a line that +will be used as the input display. -### mkdir(name, recursive) -Makes a directory called `name`. If `recursive` is true, it will create its parent directories. +### hinter(line, pos) +The command line hint handler. It gets called on every key insert to +determine what text to use as an inline hint. It is passed the current +line and cursor position. It is expected to return a string which is used +as the text for the hint. This is by default a shim. To set hints, +override this function with your custom handler. -### stat(path) -Returns info about `path` +### inputMode(mode) +Sets the input mode for Hilbish's line reader. Accepts either emacs or vim + +### interval(cb, time) +Runs the `cb` function every `time` milliseconds. +Returns a `timer` object (see `doc timers`). + +### multiprompt(str) +Changes the continued line prompt to `str` + +### prependPath(dir) +Prepends `dir` to $PATH + +### prompt(str, typ?) +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 + +### read(prompt?) -> input? +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) + +### run(cmd, returnOut) -> exitCode, stdout, stderr +Runs `cmd` in Hilbish's sh interpreter. +If returnOut is true, the outputs of `cmd` will be returned as the 2nd and +3rd values instead of being outputted to the terminal. + +### runnerMode(mode) +Sets the execution/runner mode for interactive Hilbish. This determines whether +Hilbish wll try to run input as Lua and/or sh or only do one of either. +Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), +sh, and lua. It also accepts a function, to which if it is passed one +will call it to execute user input instead. + +### timeout(cb, time) +Runs the `cb` function after `time` in milliseconds +Returns a `timer` object (see `doc timers`). + +### which(name) +Checks if `name` is a valid command diff --git a/docs/api/hilbish.md b/docs/api/hilbish.md index 3e0739f..96746ae 100644 --- a/docs/api/hilbish.md +++ b/docs/api/hilbish.md @@ -9,19 +9,34 @@ The Hilbish module includes the core API, containing interfaces and functions which directly relate to shell functionality. ## Functions -### runnerMode(mode) -Sets the execution/runner mode for interactive Hilbish. This determines whether -Hilbish wll try to run input as Lua and/or sh or only do one of either. -Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), -sh, and lua. It also accepts a function, to which if it is passed one -will call it to execute user input instead. +### alias(cmd, orig) +Sets an alias of `cmd` to `orig` ### appendPath(dir) Appends `dir` to $PATH +### complete(scope, cb) +Registers a completion handler for `scope`. +A `scope` is currently only expected to be `command.`, +replacing with the name of the command (for example `command.git`). +`cb` must be a function that returns a table of "completion groups." +Check `doc completions` for more information. + +### cwd() +Returns the current directory of the shell + +### exec(cmd) +Replaces running hilbish with `cmd` + ### goro(fn) Puts `fn` in a goroutine +### highlighter(line) +Line highlighter handler. This is mainly for syntax highlighting, but in +reality could set the input of the prompt to *display* anything. The +callback is passed the current line and is expected to return a line that +will be used as the input display. + ### hinter(line, pos) The command line hint handler. It gets called on every key insert to determine what text to use as an inline hint. It is passed the current @@ -29,34 +44,6 @@ line and cursor position. It is expected to return a string which is used as the text for the hint. This is by default a shim. To set hints, override this function with your custom handler. -### read(prompt?) -> input? -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) - -### run(cmd, returnOut) -> exitCode, stdout, stderr -Runs `cmd` in Hilbish's sh interpreter. -If returnOut is true, the outputs of `cmd` will be returned as the 2nd and -3rd values instead of being outputted to the terminal. - -### prompt(str, typ?) -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 - -### timeout(cb, time) -Runs the `cb` function after `time` in milliseconds -Returns a `timer` object (see `doc timers`). - -### which(name) -Checks if `name` is a valid command - -### exec(cmd) -Replaces running hilbish with `cmd` - ### inputMode(mode) Sets the input mode for Hilbish's line reader. Accepts either emacs or vim @@ -70,22 +57,35 @@ Changes the continued line prompt to `str` ### prependPath(dir) Prepends `dir` to $PATH -### complete(scope, cb) -Registers a completion handler for `scope`. -A `scope` is currently only expected to be `command.`, -replacing with the name of the command (for example `command.git`). -`cb` must be a function that returns a table of "completion groups." -Check `doc completions` for more information. +### prompt(str, typ?) +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 -### highlighter(line) -Line highlighter handler. This is mainly for syntax highlighting, but in -reality could set the input of the prompt to *display* anything. The -callback is passed the current line and is expected to return a line that -will be used as the input display. +### read(prompt?) -> input? +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) -### alias(cmd, orig) -Sets an alias of `cmd` to `orig` +### run(cmd, returnOut) -> exitCode, stdout, stderr +Runs `cmd` in Hilbish's sh interpreter. +If returnOut is true, the outputs of `cmd` will be returned as the 2nd and +3rd values instead of being outputted to the terminal. -### cwd() -Returns the current directory of the shell +### runnerMode(mode) +Sets the execution/runner mode for interactive Hilbish. This determines whether +Hilbish wll try to run input as Lua and/or sh or only do one of either. +Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), +sh, and lua. It also accepts a function, to which if it is passed one +will call it to execute user input instead. + +### timeout(cb, time) +Runs the `cb` function after `time` in milliseconds +Returns a `timer` object (see `doc timers`). + +### which(name) +Checks if `name` is a valid command diff --git a/docs/api/main.md b/docs/api/main.md deleted file mode 100644 index 3dcdc30..0000000 --- a/docs/api/main.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: Module main -description: the core Hilbish API -layout: apidoc ---- - -## Introduction -The Hilbish module includes the core API, containing -interfaces and functions which directly relate to shell functionality. - -## Functions -### interval(cb, time) -Runs the `cb` function every `time` milliseconds. -Returns a `timer` object (see `doc timers`). - -### timeout(cb, time) -Runs the `cb` function after `time` in milliseconds -Returns a `timer` object (see `doc timers`). - -### cwd() -Returns the current directory of the shell - -### goro(fn) -Puts `fn` in a goroutine - -### prompt(str, typ?) -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 - -### read(prompt?) -> input? -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) - -### run(cmd, returnOut) -> exitCode, stdout, stderr -Runs `cmd` in Hilbish's sh interpreter. -If returnOut is true, the outputs of `cmd` will be returned as the 2nd and -3rd values instead of being outputted to the terminal. - -### hinter(line, pos) -The command line hint handler. It gets called on every key insert to -determine what text to use as an inline hint. It is passed the current -line and cursor position. It is expected to return a string which is used -as the text for the hint. This is by default a shim. To set hints, -override this function with your custom handler. - -### inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim - -### multiprompt(str) -Changes the continued line prompt to `str` - -### prependPath(dir) -Prepends `dir` to $PATH - -### runnerMode(mode) -Sets the execution/runner mode for interactive Hilbish. This determines whether -Hilbish wll try to run input as Lua and/or sh or only do one of either. -Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), -sh, and lua. It also accepts a function, to which if it is passed one -will call it to execute user input instead. - -### appendPath(dir) -Appends `dir` to $PATH - -### highlighter(line) -Line highlighter handler. This is mainly for syntax highlighting, but in -reality could set the input of the prompt to *display* anything. The -callback is passed the current line and is expected to return a line that -will be used as the input display. - -### exec(cmd) -Replaces running hilbish with `cmd` - -### which(name) -Checks if `name` is a valid command - -### alias(cmd, orig) -Sets an alias of `cmd` to `orig` - -### complete(scope, cb) -Registers a completion handler for `scope`. -A `scope` is currently only expected to be `command.`, -replacing with the name of the command (for example `command.git`). -`cb` must be a function that returns a table of "completion groups." -Check `doc completions` for more information. - diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 1e49ffd..017084d 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -1,23 +1,91 @@ --- name: Module terminal -description: low level terminal library +description: the core Hilbish API layout: apidoc --- ## Introduction -The terminal library is a simple and lower level library for certain terminal interactions. +The Hilbish module includes the core API, containing +interfaces and functions which directly relate to shell functionality. ## Functions -### 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 +### alias(cmd, orig) +Sets an alias of `cmd` to `orig` -### restoreState() -Restores the last saved state of the terminal +### appendPath(dir) +Appends `dir` to $PATH -### saveState() -Saves the current state of the terminal +### complete(scope, cb) +Registers a completion handler for `scope`. +A `scope` is currently only expected to be `command.`, +replacing with the name of the command (for example `command.git`). +`cb` must be a function that returns a table of "completion groups." +Check `doc completions` for more information. -### setRaw() -Puts the terminal in raw mode +### cwd() +Returns the current directory of the shell + +### exec(cmd) +Replaces running hilbish with `cmd` + +### goro(fn) +Puts `fn` in a goroutine + +### highlighter(line) +Line highlighter handler. This is mainly for syntax highlighting, but in +reality could set the input of the prompt to *display* anything. The +callback is passed the current line and is expected to return a line that +will be used as the input display. + +### hinter(line, pos) +The command line hint handler. It gets called on every key insert to +determine what text to use as an inline hint. It is passed the current +line and cursor position. It is expected to return a string which is used +as the text for the hint. This is by default a shim. To set hints, +override this function with your custom handler. + +### inputMode(mode) +Sets the input mode for Hilbish's line reader. Accepts either emacs or vim + +### interval(cb, time) +Runs the `cb` function every `time` milliseconds. +Returns a `timer` object (see `doc timers`). + +### multiprompt(str) +Changes the continued line prompt to `str` + +### prependPath(dir) +Prepends `dir` to $PATH + +### prompt(str, typ?) +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 + +### read(prompt?) -> input? +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) + +### run(cmd, returnOut) -> exitCode, stdout, stderr +Runs `cmd` in Hilbish's sh interpreter. +If returnOut is true, the outputs of `cmd` will be returned as the 2nd and +3rd values instead of being outputted to the terminal. + +### runnerMode(mode) +Sets the execution/runner mode for interactive Hilbish. This determines whether +Hilbish wll try to run input as Lua and/or sh or only do one of either. +Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), +sh, and lua. It also accepts a function, to which if it is passed one +will call it to execute user input instead. + +### timeout(cb, time) +Runs the `cb` function after `time` in milliseconds +Returns a `timer` object (see `doc timers`). + +### which(name) +Checks if `name` is a valid command diff --git a/emmyLuaDocs/main.lua b/emmyLuaDocs/main.lua deleted file mode 100644 index 540ea36..0000000 --- a/emmyLuaDocs/main.lua +++ /dev/null @@ -1,110 +0,0 @@ ---- @meta - -local main = {} - ---- Sets an alias of `cmd` to `orig` ---- @param cmd string ---- @param orig string -function main.hlalias(cmd, orig) end - ---- Appends `dir` to $PATH ---- @param dir string|table -function main.hlappendPath(dir) end - ---- Registers a completion handler for `scope`. ---- A `scope` is currently only expected to be `command.`, ---- replacing with the name of the command (for example `command.git`). ---- `cb` must be a function that returns a table of "completion groups." ---- Check `doc completions` for more information. ---- @param scope string ---- @param cb function -function main.hlcomplete(scope, cb) end - ---- Returns the current directory of the shell -function main.hlcwd() end - ---- Replaces running hilbish with `cmd` ---- @param cmd string -function main.hlexec(cmd) end - ---- Puts `fn` in a goroutine ---- @param fn function -function main.hlgoro(fn) end - ---- Line highlighter handler. This is mainly for syntax highlighting, but in ---- reality could set the input of the prompt to *display* anything. The ---- callback is passed the current line and is expected to return a line that ---- will be used as the input display. ---- @param line string -function main.hlhighlighter(line) end - ---- The command line hint handler. It gets called on every key insert to ---- determine what text to use as an inline hint. It is passed the current ---- line and cursor position. It is expected to return a string which is used ---- as the text for the hint. This is by default a shim. To set hints, ---- override this function with your custom handler. ---- @param line string ---- @param pos int -function main.hlhinter(line, pos) end - ---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim ---- @param mode string -function main.hlinputMode(mode) end - ---- Runs the `cb` function every `time` milliseconds. ---- Returns a `timer` object (see `doc timers`). ---- @param cb function ---- @param time number ---- @return table -function main.hlinterval(cb, time) end - ---- Changes the continued line prompt to `str` ---- @param str string -function main.hlmultiprompt(str) end - ---- Prepends `dir` to $PATH ---- @param dir string -function main.hlprependPath(dir) 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 ---- @param str string ---- @param typ string Type of prompt, being left or right. Left by default. -function main.hlprompt(str, typ) 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) ---- @param prompt string -function main.hlread(prompt) end - ---- Runs `cmd` in Hilbish's sh interpreter. ---- If returnOut is true, the outputs of `cmd` will be returned as the 2nd and ---- 3rd values instead of being outputted to the terminal. ---- @param cmd string -function main.hlrun(cmd) end - ---- Sets the execution/runner mode for interactive Hilbish. This determines whether ---- Hilbish wll try to run input as Lua and/or sh or only do one of either. ---- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), ---- sh, and lua. It also accepts a function, to which if it is passed one ---- will call it to execute user input instead. ---- @param mode string|function -function main.hlrunnerMode(mode) end - ---- Runs the `cb` function after `time` in milliseconds ---- Returns a `timer` object (see `doc timers`). ---- @param cb function ---- @param time number ---- @return table -function main.hltimeout(cb, time) end - ---- Checks if `name` is a valid command ---- @param binName string -function main.hlwhich(binName) end - -return main