From 7c1984135b5838c9c22d031e28a14675c09e06d1 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 26 Aug 2023 11:30:51 -0400 Subject: [PATCH 01/26] docs: add detailed parameter listing, change interface to modules there are a few changes here - documentation of each parameter separately has been added to the generated text docs - interfaces have been renamed to modules. this was honestly a pointless and confusing distinction (interfaces are tables for modules that are lua modules). it also makes it so that (formerly) interfaces and modules line up with each other on the doc list im not sure what else i did, these are old changes --- cmd/docgen/docgen.go | 45 ++++++++++++++-- docs/api/bait.md | 25 +++++++-- docs/api/commander.md | 8 ++- docs/api/fs.md | 36 +++++++++---- docs/api/hilbish/_index.md | 72 ++++++++++++++++++------- docs/api/hilbish/hilbish.aliases.md | 18 +++++-- docs/api/hilbish/hilbish.completions.md | 18 +++++-- docs/api/hilbish/hilbish.editor.md | 18 +++++-- docs/api/hilbish/hilbish.history.md | 22 +++++--- docs/api/hilbish/hilbish.jobs.md | 22 +++++--- docs/api/hilbish/hilbish.os.md | 2 +- docs/api/hilbish/hilbish.runner.md | 14 +++-- docs/api/hilbish/hilbish.timers.md | 10 ++-- docs/api/hilbish/hilbish.userDir.md | 2 +- docs/api/terminal.md | 16 ++++-- golibs/bait/bait.go | 2 + 16 files changed, 253 insertions(+), 77 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index aae6202..9008cca 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -43,6 +43,12 @@ type module struct { HasTypes bool } +type param struct{ + Name string + Type string + Doc []string +} + type docPiece struct { Doc []string FuncSig string @@ -55,6 +61,7 @@ type docPiece struct { IsType bool Fields []docPiece Properties []docPiece + Params []param } type tag struct { @@ -215,6 +222,17 @@ start: fields := docPieceTag("field", tags) properties := docPieceTag("property", tags) + var params []param + if paramsRaw := tags["param"]; paramsRaw != nil { + params = make([]param, len(paramsRaw)) + for i, p := range paramsRaw { + params[i] = param{ + Name: p.id, + Type: p.fields[0], + Doc: p.fields[1:], + } + } + } for _, d := range doc { if strings.HasPrefix(d, "---") { @@ -252,6 +270,7 @@ start: ParentModule: parentMod, Fields: fields, Properties: properties, + Params: params, } if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) { dps.Doc = parts @@ -412,7 +431,7 @@ func main() { defer wg.Done() modOrIface := "Module" if modu.ParentModule != "" { - modOrIface = "Interface" + modOrIface = "Module" } f, _ := os.Create(docPath) @@ -454,7 +473,7 @@ func main() { if dps.IsMember { continue } - htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string { + htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(modname + "." + dps.FuncSig, "<", `\<`, -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] ifaces := typLookup[0] + "." + typLookup[1] + "/" @@ -462,7 +481,7 @@ func main() { ifaces = "" } linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName)) - return fmt.Sprintf(`%s`, linkedTyp, typName) + return fmt.Sprintf(`%s`, linkedTyp, typName) }) f.WriteString(fmt.Sprintf("### %s\n", htmlSig)) for _, doc := range dps.Doc { @@ -470,6 +489,26 @@ func main() { f.WriteString(doc + "\n") } } + f.WriteString("#### Parameters\n") + if len(dps.Params) == 0 { + f.WriteString("This function has no parameters. \n") + } + for _, p := range dps.Params { + isVariadic := false + typ := p.Type + if strings.HasPrefix(p.Type, "...") { + isVariadic = true + typ = p.Type[3:] + } + + f.WriteString(fmt.Sprintf("`%s` **`%s`**", typ, p.Name)) + if isVariadic { + f.WriteString(" (This type is variadic. You can pass an infinite amount of parameters with this type.)") + } + f.WriteString(" \n") + f.WriteString(strings.Join(p.Doc, " ")) + f.WriteString("\n\n") + } f.WriteString("\n") } } diff --git a/docs/api/bait.md b/docs/api/bait.md index a70eb17..5929bbd 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -15,20 +15,35 @@ happened, like when you've changed directory, a command has failed, etc. To find all available hooks thrown by Hilbish, see doc hooks. ## Functions -### catch(name, cb) +### bait.catch(name, cb) Catches a hook with `name`. Runs the `cb` when it is thrown +#### Parameters +This function has no parameters. -### catchOnce(name, cb) +### bait.catchOnce(name, cb) Same as catch, but only runs the `cb` once and then removes the hook +#### Parameters +This function has no parameters. -### hooks(name) -> table +### bait.hooks(name) -> table Returns a table with hooks (callback functions) on the event with `name`. +#### Parameters +This function has no parameters. -### release(name, catcher) +### bait.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. +#### Parameters +This function has no parameters. -### throw(name, ...args) +### bait.throw(name, ...args) Throws a hook with `name` with the provided `args` +#### Parameters +`string` **`name`** +The name of the hook. + +`any` **`args`** (This type is variadic. You can pass an infinite amount of parameters with this type.) +The arguments to pass to the hook. + diff --git a/docs/api/commander.md b/docs/api/commander.md index 341eeda..aa0849e 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -38,9 +38,13 @@ output should go. name would suggest. ## Functions -### deregister(name) +### commander.deregister(name) Deregisters any command registered with `name` +#### Parameters +This function has no parameters. -### register(name, cb) +### commander.register(name, cb) Register a command with `name` that runs `cb` when ran +#### Parameters +This function has no parameters. diff --git a/docs/api/fs.md b/docs/api/fs.md index ee6949f..e6e8f87 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -13,39 +13,57 @@ and other things, and acts an addition to the Lua standard library's I/O and filesystem functions. ## Functions -### abs(path) -> string +### fs.abs(path) -> string Gives an absolute version of `path`. +#### Parameters +This function has no parameters. -### basename(path) -> string +### fs.basename(path) -> string Gives the basename of `path`. For the rules, see Go's filepath.Base +#### Parameters +This function has no parameters. -### cd(dir) +### fs.cd(dir) Changes directory to `dir` +#### Parameters +This function has no parameters. -### dir(path) -> string +### fs.dir(path) -> string Returns the directory part of `path`. For the rules, see Go's filepath.Dir +#### Parameters +This function has no parameters. -### glob(pattern) -> matches (table) +### fs.glob(pattern) -> matches (table) Glob all files and directories that match the pattern. For the rules, see Go's filepath.Glob +#### Parameters +This function has no parameters. -### join(...) -> string +### fs.join(...) -> string Takes paths and joins them together with the OS's directory separator (forward or backward slash). +#### Parameters +This function has no parameters. -### mkdir(name, recursive) +### fs.mkdir(name, recursive) Makes a directory called `name`. If `recursive` is true, it will create its parent directories. +#### Parameters +This function has no parameters. -### readdir(dir) -> {} +### fs.readdir(dir) -> {} Returns a table of files in `dir`. +#### Parameters +This function has no parameters. -### stat(path) -> {} +### fs.stat(path) -> {} Returns a table of info about the `path`. It contains the following keys: name (string) - Name of the path size (number) - Size of the path mode (string) - Permission mode in an octal format string (with leading 0) isDir (boolean) - If the path is a directory +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 4cf0180..9ebd21a 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -23,29 +23,41 @@ interfaces and functions which directly relate to shell functionality. - `exitCode`: xit code of the last executed command ## Functions -### alias(cmd, orig) +### hilbish.alias(cmd, orig) Sets an alias of `cmd` to `orig` +#### Parameters +This function has no parameters. -### appendPath(dir) +### hilbish.appendPath(dir) Appends `dir` to $PATH +#### Parameters +This function has no parameters. -### complete(scope, cb) +### hilbish.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. +#### Parameters +This function has no parameters. -### cwd() -> string +### hilbish.cwd() -> string Returns the current directory of the shell +#### Parameters +This function has no parameters. -### exec(cmd) +### hilbish.exec(cmd) Replaces running hilbish with `cmd` +#### Parameters +This function has no parameters. -### goro(fn) +### hilbish.goro(fn) Puts `fn` in a goroutine +#### Parameters +This function has no parameters. -### highlighter(line) +### hilbish.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 @@ -58,59 +70,83 @@ function hilbish.highlighter(line) end ``` This code will highlight all double quoted strings in green. +#### Parameters +This function has no parameters. -### hinter(line, pos) +### hilbish.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. +#### Parameters +This function has no parameters. -### inputMode(mode) +### hilbish.inputMode(mode) Sets the input mode for Hilbish's line reader. Accepts either emacs or vim +#### Parameters +This function has no parameters. -### interval(cb, time) -> Timer +### hilbish.interval(cb, time) -> Timer Runs the `cb` function every `time` milliseconds. This creates a timer that starts immediately. +#### Parameters +This function has no parameters. -### multiprompt(str) +### hilbish.multiprompt(str) Changes the continued line prompt to `str` +#### Parameters +This function has no parameters. -### prependPath(dir) +### hilbish.prependPath(dir) Prepends `dir` to $PATH +#### Parameters +This function has no parameters. -### prompt(str, typ) +### hilbish.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 +#### Parameters +This function has no parameters. -### read(prompt) -> input (string) +### hilbish.read(prompt) -> input (string) 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) +#### Parameters +This function has no parameters. -### run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) +### hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) 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. +#### Parameters +This function has no parameters. -### runnerMode(mode) +### hilbish.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. +#### Parameters +This function has no parameters. -### timeout(cb, time) -> Timer +### hilbish.timeout(cb, time) -> Timer Runs the `cb` function after `time` in milliseconds. This creates a timer that starts immediately. +#### Parameters +This function has no parameters. -### which(name) -> string +### hilbish.which(name) -> string Checks if `name` is a valid command. Will return the path of the binary, or a basename if it's a commander. +#### Parameters +This function has no parameters. ## Types ## Sink diff --git a/docs/api/hilbish/hilbish.aliases.md b/docs/api/hilbish/hilbish.aliases.md index bae5bfc..1936b47 100644 --- a/docs/api/hilbish/hilbish.aliases.md +++ b/docs/api/hilbish/hilbish.aliases.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.aliases +title: Module hilbish.aliases description: command aliasing layout: doc menu: @@ -11,15 +11,23 @@ menu: The alias interface deals with all command aliases in Hilbish. ## Functions -### add(alias, cmd) +### hilbish.aliases.add(alias, cmd) This is an alias (ha) for the `hilbish.alias` function. +#### Parameters +This function has no parameters. -### delete(name) +### hilbish.aliases.delete(name) Removes an alias. +#### Parameters +This function has no parameters. -### list() -> table\ +### hilbish.aliases.list() -> table\ Get a table of all aliases, with string keys as the alias and the value as the command. +#### Parameters +This function has no parameters. -### resolve(alias) -> command (string) +### hilbish.aliases.resolve(alias) -> command (string) Tries to resolve an alias to its command. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 6f8740f..6ec1206 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.completions +title: Module hilbish.completions description: tab completions layout: doc menu: @@ -11,19 +11,27 @@ menu: The completions interface deals with tab completions. ## Functions -### call(name, query, ctx, fields) -> completionGroups (table), prefix (string) +### hilbish.completions.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` 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. -### handler(line, pos) +### hilbish.completions.handler(line, pos) 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. -### bins(query, ctx, fields) -> entries (table), prefix (string) +### hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string) Returns binary/executale completion candidates based on the provided query. +#### Parameters +This function has no parameters. -### files(query, ctx, fields) -> entries (table), prefix (string) +### hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string) Returns file completion candidates based on the provided query. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 30a3842..e10aca9 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.editor +title: Module hilbish.editor description: interactions for Hilbish's line reader layout: doc menu: @@ -12,15 +12,23 @@ The hilbish.editor interface provides functions to directly interact with the line editor in use. ## Functions -### getLine() -> string +### hilbish.editor.getLine() -> string Returns the current input line. +#### Parameters +This function has no parameters. -### getVimRegister(register) -> string +### hilbish.editor.getVimRegister(register) -> string Returns the text that is at the register. +#### Parameters +This function has no parameters. -### insert(text) +### hilbish.editor.insert(text) Inserts text into the line. +#### Parameters +This function has no parameters. -### setVimRegister(register, text) +### hilbish.editor.setVimRegister(register, text) Sets the vim register at `register` to hold the passed text. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 9fa9b01..902155f 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.history +title: Module hilbish.history description: command history layout: doc menu: @@ -13,18 +13,28 @@ This includes the ability to override functions to change the main method of saving history. ## Functions -### add(cmd) +### hilbish.history.add(cmd) Adds a command to the history. +#### Parameters +This function has no parameters. -### all() -> table +### hilbish.history.all() -> table Retrieves all history. +#### Parameters +This function has no parameters. -### clear() +### hilbish.history.clear() Deletes all commands from the history. +#### Parameters +This function has no parameters. -### get(idx) +### hilbish.history.get(idx) Retrieves a command from the history based on the `idx`. +#### Parameters +This function has no parameters. -### size() -> number +### hilbish.history.size() -> number Returns the amount of commands in the history. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index e41be2c..5f8992d 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.jobs +title: Module hilbish.jobs description: background job management layout: doc menu: @@ -15,20 +15,30 @@ Jobs are the name of background tasks/commands. A job can be started via interactive usage or with the functions defined below for use in external runners. ## Functions -### add(cmdstr, args, execPath) +### hilbish.jobs.add(cmdstr, args, execPath) Adds a new job to the job table. Note that this does not immediately run it. +#### Parameters +This function has no parameters. -### all() -> table\<Job> +### hilbish.jobs.all() -> table\<Job> Returns a table of all job objects. +#### Parameters +This function has no parameters. -### disown(id) +### hilbish.jobs.disown(id) Disowns a job. This deletes it from the job table. +#### Parameters +This function has no parameters. -### get(id) -> Job +### hilbish.jobs.get(id) -> Job Get a job object via its ID. +#### Parameters +This function has no parameters. -### last() -> Job +### hilbish.jobs.last() -> Job Returns the last added job from the table. +#### Parameters +This function has no parameters. ## Types ## Job diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index aa2198e..00196da 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.os +title: Module hilbish.os description: OS Info layout: doc menu: diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 68ffdc6..7729bdd 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.runner +title: Module hilbish.runner description: interactive command runner customization layout: doc menu: @@ -15,17 +15,23 @@ language or script of their choosing. A good example is using it to write command in Fennel. ## Functions -### setMode(cb) +### hilbish.runner.setMode(cb) This is the same as the `hilbish.runnerMode` function. It takes a callback, which will be used to execute all interactive input. In normal cases, neither callbacks should be overrided by the user, as the higher level functions listed below this will handle it. +#### Parameters +This function has no parameters. -### lua(cmd) +### hilbish.runner.lua(cmd) Evaluates `cmd` as Lua input. This is the same as using `dofile` or `load`, but is appropriated for the runner interface. +#### Parameters +This function has no parameters. -### sh(cmd) +### hilbish.runner.sh(cmd) Runs a command in Hilbish's shell script interpreter. This is the equivalent of using `source`. +#### Parameters +This function has no parameters. diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index e899d1d..576c820 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.timers +title: Module hilbish.timers description: timeout and interval API layout: doc menu: @@ -35,12 +35,16 @@ print(t.running) // true - `TIMEOUT`: Constant for a timeout timer type ## Functions -### create(type, time, callback) -> Timer +### hilbish.timers.create(type, time, callback) -> Timer Creates a timer that runs based on the specified `time` in milliseconds. The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` +#### Parameters +This function has no parameters. -### get(id) -> Timer +### hilbish.timers.get(id) -> Timer Retrieves a timer via its ID. +#### Parameters +This function has no parameters. ## Types ## Timer diff --git a/docs/api/hilbish/hilbish.userDir.md b/docs/api/hilbish/hilbish.userDir.md index 0b95057..0c1d7d0 100644 --- a/docs/api/hilbish/hilbish.userDir.md +++ b/docs/api/hilbish/hilbish.userDir.md @@ -1,5 +1,5 @@ --- -title: Interface hilbish.userDir +title: Module hilbish.userDir description: user-related directories layout: doc menu: diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 99d4b49..5ad24c7 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -11,16 +11,24 @@ menu: The terminal library is a simple and lower level library for certain terminal interactions. ## Functions -### restoreState() +### terminal.restoreState() Restores the last saved state of the terminal +#### Parameters +This function has no parameters. -### saveState() +### terminal.saveState() Saves the current state of the terminal +#### Parameters +This function has no parameters. -### setRaw() +### terminal.setRaw() Puts the terminal in raw mode +#### Parameters +This function has no parameters. -### size() +### 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 +#### Parameters +This function has no parameters. diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 3f3c34e..4ba2a37 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -229,6 +229,8 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar } // throw(name, ...args) +// #param name string The name of the hook. +// #param args ...any The arguments to pass to the hook. // Throws a hook with `name` with the provided `args` // --- @param name string // --- @vararg any From 81b7e20cbf7388cc8483b202a1db11e77f494933 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 12:57:13 -0400 Subject: [PATCH 02/26] docs: add better introduction for bait module also highlights codeblocks better --- cmd/docgen/docgen.go | 2 +- docs/api/bait.md | 32 +++++-- golibs/bait/bait.go | 33 +++++-- website/config.toml | 3 + website/themes/hsh/assets/css/syntax.css | 85 +++++++++++++++++++ website/themes/hsh/layouts/partials/head.html | 3 + 6 files changed, 144 insertions(+), 14 deletions(-) create mode 100644 website/themes/hsh/assets/css/syntax.css diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 9008cca..11f41db 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -437,7 +437,7 @@ func main() { f, _ := os.Create(docPath) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) typeTag, _ := regexp.Compile(`@\w+`) - modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(modu.Description, "<", `\<`, -1), func(typ string) string { + modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(strings.Replace(modu.Description, "<", `\<`, -1), "{{\\<", "{{<", -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] ifaces := typLookup[0] + "." + typLookup[1] + "/" diff --git a/docs/api/bait.md b/docs/api/bait.md index 5929bbd..c464563 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -8,17 +8,37 @@ menu: --- ## 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. + +Bait is the event emitter for Hilbish. Much like Node.js and +its `events` system, many actions in Hilbish emit events. +Unlike Node.js, Hilbish events are global. So make sure to +pick a unique name! + +Usage of the Bait module consists of userstanding +event-driven architecture, but it's pretty simple: +If you want to act on a certain event, you can `catch` it. +You can act on events via callback functions. + +Examples of this are in the Hilbish default config! +Consider this part of it: +``` +bait.catch('command.exit', function(code) + running = false + doPrompt(code ~= 0) + doNotifyPrompt() +end) +``` + +What this does is, whenever the `command.exit` event is thrown, +this function will set the user prompt. ## Functions ### bait.catch(name, cb) Catches a hook with `name`. Runs the `cb` when it is thrown #### Parameters -This function has no parameters. +`string` **`name`** +ummm + ### bait.catchOnce(name, cb) Same as catch, but only runs the `cb` once and then removes the hook diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 4ba2a37..269ea1e 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -1,9 +1,28 @@ // the event emitter -// 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. +/* +Bait is the event emitter for Hilbish. Much like Node.js and +its `events` system, many actions in Hilbish emit events. +Unlike Node.js, Hilbish events are global. So make sure to +pick a unique name! + +Usage of the Bait module consists of userstanding +event-driven architecture, but it's pretty simple: +If you want to act on a certain event, you can `catch` it. +You can act on events via callback functions. + +Examples of this are in the Hilbish default config! +Consider this part of it: +``` +bait.catch('command.exit', function(code) + running = false + doPrompt(code ~= 0) + doNotifyPrompt() +end) +``` + +What this does is, whenever the `command.exit` event is thrown, +this function will set the user prompt. +*/ package bait import ( @@ -253,8 +272,8 @@ func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // catch(name, cb) // Catches a hook with `name`. Runs the `cb` when it is thrown -// --- @param name string -// --- @param cb function +// #param name string ummm +// #param cb function ? func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { diff --git a/website/config.toml b/website/config.toml index 31f42d5..0ae7ff2 100644 --- a/website/config.toml +++ b/website/config.toml @@ -29,6 +29,9 @@ enableGitInfo = true [markup.goldmark.renderer] unsafe = true +[markup.highlight] +style = 'pastie' + [author] [author.sammyette] name = 'sammyette' diff --git a/website/themes/hsh/assets/css/syntax.css b/website/themes/hsh/assets/css/syntax.css new file mode 100644 index 0000000..724106a --- /dev/null +++ b/website/themes/hsh/assets/css/syntax.css @@ -0,0 +1,85 @@ +/* Background */ .bg { background-color: #ffffff; } +/* PreWrapper */ .chroma { background-color: #ffffff; } +/* Other */ .chroma .x { } +/* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 } +/* CodeLine */ .chroma .cl { } +/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; } +/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; } +/* LineHighlight */ .chroma .hl { background-color: #ffffcc } +/* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } +/* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } +/* Line */ .chroma .line { display: flex; } +/* Keyword */ .chroma .k { color: #008800; font-weight: bold } +/* KeywordConstant */ .chroma .kc { color: #008800; font-weight: bold } +/* KeywordDeclaration */ .chroma .kd { color: #008800; font-weight: bold } +/* KeywordNamespace */ .chroma .kn { color: #008800; font-weight: bold } +/* KeywordPseudo */ .chroma .kp { color: #008800 } +/* KeywordReserved */ .chroma .kr { color: #008800; font-weight: bold } +/* KeywordType */ .chroma .kt { color: #888888; font-weight: bold } +/* Name */ .chroma .n { } +/* NameAttribute */ .chroma .na { color: #336699 } +/* NameBuiltin */ .chroma .nb { color: #003388 } +/* NameBuiltinPseudo */ .chroma .bp { } +/* NameClass */ .chroma .nc { color: #bb0066; font-weight: bold } +/* NameConstant */ .chroma .no { color: #003366; font-weight: bold } +/* NameDecorator */ .chroma .nd { color: #555555 } +/* NameEntity */ .chroma .ni { } +/* NameException */ .chroma .ne { color: #bb0066; font-weight: bold } +/* NameFunction */ .chroma .nf { color: #0066bb; font-weight: bold } +/* NameFunctionMagic */ .chroma .fm { } +/* NameLabel */ .chroma .nl { color: #336699; font-style: italic } +/* NameNamespace */ .chroma .nn { color: #bb0066; font-weight: bold } +/* NameOther */ .chroma .nx { } +/* NameProperty */ .chroma .py { color: #336699; font-weight: bold } +/* NameTag */ .chroma .nt { color: #bb0066; font-weight: bold } +/* NameVariable */ .chroma .nv { color: #336699 } +/* NameVariableClass */ .chroma .vc { color: #336699 } +/* NameVariableGlobal */ .chroma .vg { color: #dd7700 } +/* NameVariableInstance */ .chroma .vi { color: #3333bb } +/* NameVariableMagic */ .chroma .vm { } +/* Literal */ .chroma .l { } +/* LiteralDate */ .chroma .ld { } +/* LiteralString */ .chroma .s { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringAffix */ .chroma .sa { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringBacktick */ .chroma .sb { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringChar */ .chroma .sc { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDelimiter */ .chroma .dl { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDoc */ .chroma .sd { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringDouble */ .chroma .s2 { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringEscape */ .chroma .se { color: #0044dd; background-color: #fff0f0 } +/* LiteralStringHeredoc */ .chroma .sh { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringInterpol */ .chroma .si { color: #3333bb; background-color: #fff0f0 } +/* LiteralStringOther */ .chroma .sx { color: #22bb22; background-color: #f0fff0 } +/* LiteralStringRegex */ .chroma .sr { color: #008800; background-color: #fff0ff } +/* LiteralStringSingle */ .chroma .s1 { color: #dd2200; background-color: #fff0f0 } +/* LiteralStringSymbol */ .chroma .ss { color: #aa6600; background-color: #fff0f0 } +/* LiteralNumber */ .chroma .m { color: #0000dd; font-weight: bold } +/* LiteralNumberBin */ .chroma .mb { color: #0000dd; font-weight: bold } +/* LiteralNumberFloat */ .chroma .mf { color: #0000dd; font-weight: bold } +/* LiteralNumberHex */ .chroma .mh { color: #0000dd; font-weight: bold } +/* LiteralNumberInteger */ .chroma .mi { color: #0000dd; font-weight: bold } +/* LiteralNumberIntegerLong */ .chroma .il { color: #0000dd; font-weight: bold } +/* LiteralNumberOct */ .chroma .mo { color: #0000dd; font-weight: bold } +/* Operator */ .chroma .o { } +/* OperatorWord */ .chroma .ow { color: #008800 } +/* Punctuation */ .chroma .p { } +/* Comment */ .chroma .c { color: #888888 } +/* CommentHashbang */ .chroma .ch { color: #888888 } +/* CommentMultiline */ .chroma .cm { color: #888888 } +/* CommentSingle */ .chroma .c1 { color: #888888 } +/* CommentSpecial */ .chroma .cs { color: #cc0000; background-color: #fff0f0; font-weight: bold } +/* CommentPreproc */ .chroma .cp { color: #cc0000; font-weight: bold } +/* CommentPreprocFile */ .chroma .cpf { color: #cc0000; font-weight: bold } +/* Generic */ .chroma .g { } +/* GenericDeleted */ .chroma .gd { color: #000000; background-color: #ffdddd } +/* GenericEmph */ .chroma .ge { font-style: italic } +/* GenericError */ .chroma .gr { color: #aa0000 } +/* GenericHeading */ .chroma .gh { color: #333333 } +/* GenericInserted */ .chroma .gi { color: #000000; background-color: #ddffdd } +/* GenericOutput */ .chroma .go { color: #888888 } +/* GenericPrompt */ .chroma .gp { color: #555555 } +/* GenericStrong */ .chroma .gs { font-weight: bold } +/* GenericSubheading */ .chroma .gu { color: #666666 } +/* GenericTraceback */ .chroma .gt { color: #aa0000 } +/* GenericUnderline */ .chroma .gl { text-decoration: underline } +/* TextWhitespace */ .chroma .w { color: #bbbbbb } diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index fca4558..cb2e12e 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -23,7 +23,10 @@ + {{ $syntax := resources.Get "css/syntax.css" | resources.Minify | resources.Fingerprint }} + + From 22cf0fcb4951e2ea6d5cd17f81d5d6daa995e1d8 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 14:30:31 -0400 Subject: [PATCH 04/26] docs: change colors for syntax highlight and function jump highlight --- website/themes/hsh/assets/css/syntax.css | 6 +++--- website/themes/hsh/layouts/partials/head.html | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/themes/hsh/assets/css/syntax.css b/website/themes/hsh/assets/css/syntax.css index 724106a..021dcb3 100644 --- a/website/themes/hsh/assets/css/syntax.css +++ b/website/themes/hsh/assets/css/syntax.css @@ -1,11 +1,11 @@ -/* Background */ .bg { background-color: #ffffff; } -/* PreWrapper */ .chroma { background-color: #ffffff; } +/* Background */ .bg { background-color: #edfdff; } +/* PreWrapper */ .chroma { background-color: #edfdff; } /* Other */ .chroma .x { } /* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 } /* CodeLine */ .chroma .cl { } /* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; } /* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; } -/* LineHighlight */ .chroma .hl { background-color: #ffffcc } +/* LineHighlight */ .chroma .hl { background-color: #edfdff } /* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* Line */ .chroma .line { display: flex; } diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index 087d997..8299693 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -43,7 +43,7 @@ background: none } 50% { - background: yellow; + background: #fff2cf; } 100% { background: none; @@ -51,7 +51,7 @@ } div:target { - animation: highlight 1s; + animation: highlight 1.2s; animation-timing-function: cubic-bezier(1,-0.02,.45,.89); } From eda4fda972cf93e4fbd73e040a22ec516cf8dbc0 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 15:32:53 -0400 Subject: [PATCH 05/26] docs(commander): remove note about input sink being unimplemented --- docs/api/commander.md | 2 +- golibs/commander/commander.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/commander.md b/docs/api/commander.md index 72140ad..fa641b4 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -31,7 +31,7 @@ The `sinks` parameter is a table with 3 keys: `in`, `out`, and `err`. The values of these is a Sink. - `in` is the standard input. You can read from this sink -to get user input. (**This is currently unimplemented.**) +to get user input. - `out` is standard output. This is usually where text meant for output should go. - `err` is standard error. This sink is for writing errors, as the diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index c639cf9..a21de1c 100644 --- a/golibs/commander/commander.go +++ b/golibs/commander/commander.go @@ -22,7 +22,7 @@ The `sinks` parameter is a table with 3 keys: `in`, `out`, and `err`. The values of these is a @Sink. - `in` is the standard input. You can read from this sink -to get user input. (**This is currently unimplemented.**) +to get user input. - `out` is standard output. This is usually where text meant for output should go. - `err` is standard error. This sink is for writing errors, as the From 090028430426009ec8d7c200fecda28e425406d9 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:01:57 -0400 Subject: [PATCH 06/26] docs: turn properties list into a table also fix member functions causing a spam of separators --- cmd/docgen/docgen.go | 19 ++-- docs/api/bait.md | 20 +++- docs/api/commander.md | 8 +- docs/api/fs.md | 36 +++++-- docs/api/hilbish/_index.md | 93 +++++++++++++------ docs/api/hilbish/hilbish.aliases.md | 16 +++- docs/api/hilbish/hilbish.completions.md | 16 +++- docs/api/hilbish/hilbish.editor.md | 16 +++- docs/api/hilbish/hilbish.history.md | 20 +++- docs/api/hilbish/hilbish.jobs.md | 21 ++++- docs/api/hilbish/hilbish.os.md | 8 +- docs/api/hilbish/hilbish.runner.md | 12 ++- docs/api/hilbish/hilbish.timers.md | 15 ++- docs/api/hilbish/hilbish.userDir.md | 6 +- docs/api/terminal.md | 16 +++- website/themes/hsh/layouts/partials/head.html | 1 + 16 files changed, 236 insertions(+), 87 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index a14742d..9332dfa 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -481,11 +481,17 @@ func main() { if len(modu.Fields) != 0 { f.WriteString("## Interface fields\n") - for _, dps := range modu.Fields { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + + mdTable := md.NewTable(len(modu.Fields), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + + for i, dps := range modu.Fields { + mdTable.SetContent(i, 0, dps.FuncName) + mdTable.SetContent(i, 1, strings.Join(dps.Doc, " ")) } + f.WriteString(mdTable.String()) f.WriteString("\n") } if len(modu.Properties) != 0 { @@ -499,12 +505,12 @@ func main() { } if len(modu.Docs) != 0 { - //f.WriteString("## Functions\n") + f.WriteString("## Functions\n") for _, dps := range modu.Docs { - f.WriteString(fmt.Sprintf("
", dps.FuncName)) if dps.IsMember { continue } + f.WriteString(fmt.Sprintf("
", dps.FuncName)) htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(modname + "." + dps.FuncSig, "<", `\<`, -1), func(typ string) string { typName := typ[1:] typLookup := typeTable[strings.ToLower(typName)] @@ -550,6 +556,7 @@ func main() { f.WriteString("\n\n") } f.WriteString("
") + f.WriteString("\n\n") } } diff --git a/docs/api/bait.md b/docs/api/bait.md index 292152f..468648f 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -41,6 +41,7 @@ this function will set the user prompt. |release(name, catcher)|Removes the `catcher` for the event with `name`.| |throw(name, ...args)|Throws a hook with `name` with the provided `args`| +## Functions

bait.catch(name, cb) @@ -57,7 +58,9 @@ ummm `function` **`cb`** ? -

+
+ +
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/commander.md b/docs/api/commander.md index fa641b4..20117af 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -43,6 +43,7 @@ name would suggest. |deregister(name)|Deregisters any command registered with `name`| |register(name, cb)|Register a command with `name` that runs `cb` when ran| +## Functions

commander.deregister(name) @@ -54,7 +55,9 @@ commander.deregister(name) Deregisters any command registered with `name` #### Parameters This function has no parameters. -

+
+ +
\ No newline at end of file + + diff --git a/docs/api/fs.md b/docs/api/fs.md index 64a2092..fff8877 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -25,6 +25,7 @@ I/O and filesystem functions. |readdir(dir) -> {}|Returns a table of files in `dir`.| |stat(path) -> {}|Returns a table of info about the `path`.| +## Functions

fs.abs(path) -> string @@ -36,7 +37,9 @@ fs.abs(path) -> string Gives an absolute version of `path`. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
 \ No newline at end of file + + diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 317ba5d..2fb9aa7 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -34,16 +34,19 @@ interfaces and functions which directly relate to shell functionality. |which(name) -> string|Checks if `name` is a valid command.| ## Interface fields -- `ver`: The version of Hilbish -- `goVersion`: The version of Go that Hilbish was compiled with -- `user`: Username of the user -- `host`: Hostname of the machine -- `dataDir`: Directory for Hilbish data files, including the docs and default modules -- `interactive`: Is Hilbish in an interactive shell? -- `login`: Is Hilbish the login shell? -- `vimMode`: Current Vim input mode of Hilbish (will be nil if not in Vim input mode) -- `exitCode`: xit code of the last executed command +||| +|----|----| +|ver|The version of Hilbish| +|goVersion|The version of Go that Hilbish was compiled with| +|user|Username of the user| +|host|Hostname of the machine| +|dataDir|Directory for Hilbish data files, including the docs and default modules| +|interactive|Is Hilbish in an interactive shell?| +|login|Is Hilbish the login shell?| +|vimMode|Current Vim input mode of Hilbish (will be nil if not in Vim input mode)| +|exitCode|xit code of the last executed command| +## Functions

hilbish.alias(cmd, orig) @@ -55,7 +58,9 @@ hilbish.alias(cmd, orig) Sets an alias of `cmd` to `orig` #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
 + diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 726e7e9..698140d 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -18,6 +18,7 @@ The completions interface deals with tab completions. |bins(query, ctx, fields) -> entries (table), prefix (string)|Returns binary/executale completion candidates based on the provided query.| |files(query, ctx, fields) -> entries (table), prefix (string)|Returns file completion candidates based on the provided query.| +## Functions

hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string) @@ -32,7 +33,9 @@ of `command.name`, example: `command.git`. You can check `doc completions` for info on the `completionGroups` return value. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 38b247e..ee55580 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -19,6 +19,7 @@ directly interact with the line editor in use. |insert(text)|Inserts text into the line.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.| +## Functions

hilbish.editor.getLine() -> string @@ -30,7 +31,9 @@ hilbish.editor.getLine() -> string Returns the current input line. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 0f60370..dee087a 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -21,6 +21,7 @@ method of saving history. |get(idx)|Retrieves a command from the history based on the `idx`.| |size() -> number|Returns the amount of commands in the history.| +## Functions

hilbish.history.add(cmd) @@ -32,7 +33,9 @@ hilbish.history.add(cmd) Adds a command to the history. #### Parameters This function has no parameters. -

+
+ +
+ +
+ +
+ +
 \ No newline at end of file +
+ diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index f27bc98..ecc045e 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -23,6 +23,7 @@ interactive usage or with the functions defined below for use in external runner |get(id) -> @Job|Get a job object via its ID.| |last() -> @Job|Returns the last added job from the table.| +## Functions

hilbish.jobs.add(cmdstr, args, execPath) @@ -34,7 +35,9 @@ hilbish.jobs.add(cmdstr, args, execPath) Adds a new job to the job table. Note that this does not immediately run it. #### Parameters This function has no parameters. -

+
+ +
+ +

hilbish.jobs.get(id) -> Job @@ -67,7 +74,9 @@ hilbish.jobs.get(id) ->
+
+ +
 + +## Types ## Job The Job type describes a Hilbish job. ### Properties diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 00196da..3abd8f7 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -13,7 +13,9 @@ the current OS on the systen. This mainly includes the name and version. ## Interface fields -- `family`: Family name of the current OS -- `name`: Pretty name of the current OS -- `version`: Version of the current OS +||| +|----|----| +|family|Family name of the current OS| +|name|Pretty name of the current OS| +|version|Version of the current OS| diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index f5977e1..98e8f6c 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -21,6 +21,7 @@ write command in Fennel. |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| +## Functions

hilbish.runner.setMode(cb) @@ -35,7 +36,9 @@ In normal cases, neither callbacks should be overrided by the user, as the higher level functions listed below this will handle it. #### Parameters This function has no parameters. -

+
+ +
+ +
 \ No newline at end of file +

+ diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 20efd7c..186c1af 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -37,9 +37,12 @@ print(t.running) // true |get(id) -> @Timer|Retrieves a timer via its ID.| ## Interface fields -- `INTERVAL`: Constant for an interval timer type -- `TIMEOUT`: Constant for a timeout timer type +||| +|----|----| +|INTERVAL|Constant for an interval timer type| +|TIMEOUT|Constant for a timeout timer type| +## Functions

hilbish.timers.create(type, time, callback) -> Timer @@ -52,7 +55,9 @@ Creates a timer that runs based on the specified `time` in milliseconds. The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` #### Parameters This function has no parameters. -

+
+ +
+ diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index 8299693..6109fb5 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -60,6 +60,7 @@ border-style: solid; border-color: #565c64;; border-collapse: collapse; + margin-bottom: 12px; } table td { From 7fd2ed391b17b143bf908b721e8696fd26006698 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:11:57 -0400 Subject: [PATCH 07/26] docs: add separators for types, make object properties into tables --- cmd/docgen/docgen.go | 33 ++++++++++++++++++++--------- docs/api/hilbish/_index.md | 6 ++++-- docs/api/hilbish/hilbish.jobs.md | 23 ++++++++++++-------- docs/api/hilbish/hilbish.os.md | 2 +- docs/api/hilbish/hilbish.timers.md | 17 +++++++++------ docs/api/hilbish/hilbish.userDir.md | 2 +- 6 files changed, 54 insertions(+), 29 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 9332dfa..8598091 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -480,7 +480,7 @@ func main() { } if len(modu.Fields) != 0 { - f.WriteString("## Interface fields\n") + f.WriteString("## Static module fields\n") mdTable := md.NewTable(len(modu.Fields), 2) mdTable.SetTitle(0, "") @@ -496,11 +496,17 @@ func main() { } if len(modu.Properties) != 0 { f.WriteString("## Object properties\n") - for _, dps := range modu.Properties { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + + mdTable := md.NewTable(len(modu.Fields), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + + for i, dps := range modu.Properties { + mdTable.SetContent(i, 0, dps.FuncName) + mdTable.SetContent(i, 1, strings.Join(dps.Doc, " ")) } + f.WriteString(mdTable.String()) f.WriteString("\n") } @@ -563,6 +569,7 @@ func main() { if len(modu.Types) != 0 { f.WriteString("## Types\n") for _, dps := range modu.Types { + f.WriteString("
\n\n") f.WriteString(fmt.Sprintf("## %s\n", dps.FuncName)) for _, doc := range dps.Doc { if !strings.HasPrefix(doc, "---") { @@ -570,12 +577,18 @@ func main() { } } if len(dps.Properties) != 0 { - f.WriteString("### Properties\n") - for _, dps := range dps.Properties { - f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName)) - f.WriteString(strings.Join(dps.Doc, " ")) - f.WriteString("\n") + f.WriteString("## Object properties\n") + + mdTable := md.NewTable(len(dps.Properties), 2) + mdTable.SetTitle(0, "") + mdTable.SetTitle(1, "") + + for i, d := range dps.Properties { + mdTable.SetContent(i, 0, d.FuncName) + mdTable.SetContent(i, 1, strings.Join(d.Doc, " ")) } + f.WriteString(mdTable.String()) + f.WriteString("\n") } f.WriteString("\n") f.WriteString("### Methods\n") diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 2fb9aa7..3bfb92b 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -33,7 +33,7 @@ interfaces and functions which directly relate to shell functionality. |timeout(cb, time) -> @Timer|Runs the `cb` function after `time` in milliseconds.| |which(name) -> string|Checks if `name` is a valid command.| -## Interface fields +## Static module fields ||| |----|----| |ver|The version of Hilbish| @@ -316,7 +316,9 @@ Will return the path of the binary, or a basename if it's a commander. This function has no parameters.
-
## Types +## Types +
+ ## Sink A sink is a structure that has input and/or output to/from a desination. diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index ecc045e..290fe6f 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -24,7 +24,7 @@ interactive usage or with the functions defined below for use in external runner |last() -> @Job|Returns the last added job from the table.| ## Functions -
+

hilbish.jobs.add(cmdstr, args, execPath) @@ -90,16 +90,21 @@ This function has no parameters.

## Types +
+ ## Job The Job type describes a Hilbish job. -### Properties -- `cmd`: The user entered command string for the job. -- `running`: Whether the job is running or not. -- `id`: The ID of the job in the job table -- `pid`: The Process ID -- `exitCode`: The last exit code of the job. -- `stdout`: The standard output of the job. This just means the normal logs of the process. -- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job. +## Object properties +||| +|----|----| +|cmd|The user entered command string for the job.| +|running|Whether the job is running or not.| +|id|The ID of the job in the job table| +|pid|The Process ID| +|exitCode|The last exit code of the job.| +|stdout|The standard output of the job. This just means the normal logs of the process.| +|stderr|The standard error stream of the process. This (usually) includes error messages of the job.| + ### Methods #### background() diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 3abd8f7..7749e3d 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -12,7 +12,7 @@ The `os` interface provides simple text information properties about the current OS on the systen. This mainly includes the name and version. -## Interface fields +## Static module fields ||| |----|----| |family|Family name of the current OS| diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 186c1af..f996bb4 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -36,14 +36,14 @@ print(t.running) // true |create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time` in milliseconds.| |get(id) -> @Timer|Retrieves a timer via its ID.| -## Interface fields +## Static module fields ||| |----|----| |INTERVAL|Constant for an interval timer type| |TIMEOUT|Constant for a timeout timer type| ## Functions -
+

hilbish.timers.create(type, time, callback) -> Timer @@ -71,12 +71,17 @@ This function has no parameters.

## Types +
+ ## Timer The Job type describes a Hilbish timer. -### Properties -- `type`: What type of timer it is -- `running`: If the timer is running -- `duration`: The duration in milliseconds that the timer will run +## Object properties +||| +|----|----| +|type|What type of timer it is| +|running|If the timer is running| +|duration|The duration in milliseconds that the timer will run| + ### Methods #### start() diff --git a/docs/api/hilbish/hilbish.userDir.md b/docs/api/hilbish/hilbish.userDir.md index 2fd60f6..a2b7337 100644 --- a/docs/api/hilbish/hilbish.userDir.md +++ b/docs/api/hilbish/hilbish.userDir.md @@ -12,7 +12,7 @@ This interface just contains properties to know about certain user directories. It is equivalent to XDG on Linux and gets the user's preferred directories for configs and data. -## Interface fields +## Static module fields ||| |----|----| |config|The user's config directory| From 95ac2e280daaeac7b34ecc6360ebbbe5a92cf971 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Sep 2023 16:24:35 -0400 Subject: [PATCH 08/26] docs: fix description of exitCode prop --- api.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api.go b/api.go index 61aac21..2f0a548 100644 --- a/api.go +++ b/api.go @@ -9,7 +9,7 @@ // #field interactive Is Hilbish in an interactive shell? // #field login Is Hilbish the login shell? // #field vimMode Current Vim input mode of Hilbish (will be nil if not in Vim input mode) -// #field exitCode xit code of the last executed command +// #field exitCode Exit code of the last executed command package main import ( From 726082ba032309b80b27d8ba63ea0a215f7cae91 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 9 Sep 2023 13:38:54 -0400 Subject: [PATCH 09/26] docs: fix duplicate functions header --- cmd/docgen/docgen.go | 6 +++++- docs/api/bait.md | 1 - docs/api/commander.md | 1 - docs/api/fs.md | 1 - docs/api/hilbish/_index.md | 1 - docs/api/hilbish/hilbish.aliases.md | 1 - docs/api/hilbish/hilbish.completions.md | 1 - docs/api/hilbish/hilbish.editor.md | 1 - docs/api/hilbish/hilbish.history.md | 1 - docs/api/hilbish/hilbish.jobs.md | 1 - docs/api/hilbish/hilbish.runner.md | 1 - docs/api/hilbish/hilbish.timers.md | 1 - docs/api/terminal.md | 1 - 13 files changed, 5 insertions(+), 13 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 8598091..487af9f 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -435,6 +435,7 @@ func main() { if modu.ParentModule != "" { modOrIface = "Module" } + lastHeader := "" f, _ := os.Create(docPath) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) @@ -460,6 +461,7 @@ func main() { } f.WriteString("## Functions\n") + lastHeader = "functions" mdTable := md.NewTable(funcCount, 2) mdTable.SetTitle(0, "") @@ -511,7 +513,9 @@ func main() { } if len(modu.Docs) != 0 { - f.WriteString("## Functions\n") + if lastHeader != "functions" { + f.WriteString("## Functions\n") + } for _, dps := range modu.Docs { if dps.IsMember { continue diff --git a/docs/api/bait.md b/docs/api/bait.md index 468648f..91cfb31 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -41,7 +41,6 @@ this function will set the user prompt. |release(name, catcher)|Removes the `catcher` for the event with `name`.| |throw(name, ...args)|Throws a hook with `name` with the provided `args`| -## Functions

bait.catch(name, cb) diff --git a/docs/api/commander.md b/docs/api/commander.md index 20117af..4d67c81 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -43,7 +43,6 @@ name would suggest. |deregister(name)|Deregisters any command registered with `name`| |register(name, cb)|Register a command with `name` that runs `cb` when ran| -## Functions

commander.deregister(name) diff --git a/docs/api/fs.md b/docs/api/fs.md index fff8877..37045eb 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -25,7 +25,6 @@ I/O and filesystem functions. |readdir(dir) -> {}|Returns a table of files in `dir`.| |stat(path) -> {}|Returns a table of info about the `path`.| -## Functions

fs.abs(path) -> string diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 3bfb92b..36e6413 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -46,7 +46,6 @@ interfaces and functions which directly relate to shell functionality. |vimMode|Current Vim input mode of Hilbish (will be nil if not in Vim input mode)| |exitCode|xit code of the last executed command| -## Functions

hilbish.alias(cmd, orig) diff --git a/docs/api/hilbish/hilbish.aliases.md b/docs/api/hilbish/hilbish.aliases.md index b5d27a2..5274e04 100644 --- a/docs/api/hilbish/hilbish.aliases.md +++ b/docs/api/hilbish/hilbish.aliases.md @@ -18,7 +18,6 @@ The alias interface deals with all command aliases in Hilbish. |list() -> table|Get a table of all aliases, with string keys as the alias and the value as the command.| |resolve(alias) -> command (string)|Tries to resolve an alias to its command.| -## Functions

hilbish.aliases.add(alias, cmd) diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 698140d..790aeee 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -18,7 +18,6 @@ The completions interface deals with tab completions. |bins(query, ctx, fields) -> entries (table), prefix (string)|Returns binary/executale completion candidates based on the provided query.| |files(query, ctx, fields) -> entries (table), prefix (string)|Returns file completion candidates based on the provided query.| -## Functions

hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string) diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index ee55580..282737d 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -19,7 +19,6 @@ directly interact with the line editor in use. |insert(text)|Inserts text into the line.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.| -## Functions

hilbish.editor.getLine() -> string diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index dee087a..3d9b856 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -21,7 +21,6 @@ method of saving history. |get(idx)|Retrieves a command from the history based on the `idx`.| |size() -> number|Returns the amount of commands in the history.| -## Functions

hilbish.history.add(cmd) diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index 290fe6f..bb1af1e 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -23,7 +23,6 @@ interactive usage or with the functions defined below for use in external runner |get(id) -> @Job|Get a job object via its ID.| |last() -> @Job|Returns the last added job from the table.| -## Functions

hilbish.jobs.add(cmdstr, args, execPath) diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 98e8f6c..5528195 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -21,7 +21,6 @@ write command in Fennel. |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| -## Functions

hilbish.runner.setMode(cb) diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index f996bb4..dae7782 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -42,7 +42,6 @@ print(t.running) // true |INTERVAL|Constant for an interval timer type| |TIMEOUT|Constant for a timeout timer type| -## Functions

hilbish.timers.create(type, time, callback) -> Timer diff --git a/docs/api/terminal.md b/docs/api/terminal.md index c5cb5ea..4977e97 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -18,7 +18,6 @@ The terminal library is a simple and lower level library for certain terminal in |setRaw()|Puts the terminal in raw mode| |size()|Gets the dimensions of the terminal. Returns a table with `width` and `height`| -## Functions

terminal.restoreState() From 0607a90c3076cf723de9f8782ec54e6abad9e7d3 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 11 Nov 2023 22:27:50 -0400 Subject: [PATCH 10/26] fix: clear before setting statusline --- nature/commands/doc.lua | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/nature/commands/doc.lua b/nature/commands/doc.lua index ee1e37c..fc12a4f 100644 --- a/nature/commands/doc.lua +++ b/nature/commands/doc.lua @@ -89,7 +89,7 @@ Available sections: ]] .. table.concat(modules, ', ') local size = terminal.size() self.region = { width = size.width, - height = size.height - 3 + height = size.height - 2 } end gh:resize() @@ -102,7 +102,8 @@ Available sections: ]] .. table.concat(modules, ', ') workingPage = self.specialPage end - self.sink:write(ansikit.getCSI(self.region.height + 2 .. ';1', 'H')) + self.sink:write(ansikit.getCSI(self.region.height + 1 .. ';1', 'H')) + self.sink:write(ansikit.getCSI(0, 'J')) if not self.isSpecial then if args[1] == 'api' then self.sink:writeln(lunacolors.reset(string.format('%s', workingPage.title))) From 5be470521f692d20622869b9d8ee2c2da988a0d3 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 11 Nov 2023 22:28:18 -0400 Subject: [PATCH 11/26] refactor: move misc docs for use in hilbish and website --- {website/content/docs => docs}/_index.md | 0 {website/content/docs => docs}/faq.md | 9 +++++---- .../content/docs => docs}/features/_index.md | 0 .../docs => docs}/features/notifications.md | 0 .../docs => docs}/features/runner-mode.md | 0 .../content/docs => docs}/getting-started.md | 0 docs/hooks/_index.md | 13 +++++++++++-- docs/hooks/command.md | 17 +++++++++++++---- docs/hooks/hilbish.md | 9 +++++++++ docs/hooks/signal.md | 9 +++++++++ website/content/docs | 1 + website/content/docs/api | 1 - 12 files changed, 48 insertions(+), 11 deletions(-) rename {website/content/docs => docs}/_index.md (100%) rename {website/content/docs => docs}/faq.md (74%) rename {website/content/docs => docs}/features/_index.md (100%) rename {website/content/docs => docs}/features/notifications.md (100%) rename {website/content/docs => docs}/features/runner-mode.md (100%) rename {website/content/docs => docs}/getting-started.md (100%) create mode 120000 website/content/docs delete mode 120000 website/content/docs/api diff --git a/website/content/docs/_index.md b/docs/_index.md similarity index 100% rename from website/content/docs/_index.md rename to docs/_index.md diff --git a/website/content/docs/faq.md b/docs/faq.md similarity index 74% rename from website/content/docs/faq.md rename to docs/faq.md index 997fbaa..f89f269 100644 --- a/website/content/docs/faq.md +++ b/docs/faq.md @@ -15,11 +15,12 @@ It compiles for Windows (CI ensures it does), but otherwise it is not directly supported. If you'd like to improve this situation, checkout [the discussion](https://github.com/Rosettea/Hilbish/discussions/165). -# Where is the API documentation? -The builtin `doc` command supplies all documentation of Hilbish provided -APIs. You can also check the sidebar. - # Why? Hilbish emerged from the desire of a Lua configured shell. It was the initial reason that it was created, but now it's more: to be hyper extensible, simpler and more user friendly. + +# Does it have "autocompletion" or "tab completion" +Of course! This is a modern shell. Hilbish provides a way for users +to write tab completion for any command and/or the whole shell. +Inline hinting and syntax highlighting are also available. diff --git a/website/content/docs/features/_index.md b/docs/features/_index.md similarity index 100% rename from website/content/docs/features/_index.md rename to docs/features/_index.md diff --git a/website/content/docs/features/notifications.md b/docs/features/notifications.md similarity index 100% rename from website/content/docs/features/notifications.md rename to docs/features/notifications.md diff --git a/website/content/docs/features/runner-mode.md b/docs/features/runner-mode.md similarity index 100% rename from website/content/docs/features/runner-mode.md rename to docs/features/runner-mode.md diff --git a/website/content/docs/getting-started.md b/docs/getting-started.md similarity index 100% rename from website/content/docs/getting-started.md rename to docs/getting-started.md diff --git a/docs/hooks/_index.md b/docs/hooks/_index.md index 6616b05..500b6e6 100644 --- a/docs/hooks/_index.md +++ b/docs/hooks/_index.md @@ -1,10 +1,19 @@ +--- +title: Hooks +description: +layout: doc +weight: -50 +menu: + docs +--- + Here is a list of bait hooks that are thrown by Hilbish. 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 -`` just means the arguments of the hook. If a hook doc has the format +`{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`. + error -> eventName, handler, err > Emitted when there is an error in diff --git a/docs/hooks/command.md b/docs/hooks/command.md index 2d29f4b..ee47db7 100644 --- a/docs/hooks/command.md +++ b/docs/hooks/command.md @@ -1,12 +1,21 @@ -+ `command.preexec` -> input, cmdStr > Thrown before a command +--- +title: Command +description: +layout: doc +menu: + docs: + parent: "Hooks" +--- + +- `command.preexec` -> input, cmdStr > Thrown before a command is executed. The `input` is the user written command, while `cmdStr` is what will be executed (`input` will have aliases while `cmdStr` will have alias resolved input). -+ `command.exit` -> code, cmdStr > Thrown when a command exits. +- `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.not-found` -> cmdStr > Thrown when a command is not found. -+ `command.not-executable` -> cmdStr > Thrown when Hilbish attempts to run a file +- `command.not-executable` -> cmdStr > Thrown when Hilbish attempts to run a file that is not executable. diff --git a/docs/hooks/hilbish.md b/docs/hooks/hilbish.md index 7118901..b240683 100644 --- a/docs/hooks/hilbish.md +++ b/docs/hooks/hilbish.md @@ -1,3 +1,12 @@ +--- +title: Hilbish +description: +layout: doc +menu: + docs: + parent: "Hooks" +--- + + `hilbish.exit` > Sent when Hilbish is about to exit. + `hilbish.vimMode` -> modeName > Sent when Hilbish's Vim mode is changed (example insert to normal mode), diff --git a/docs/hooks/signal.md b/docs/hooks/signal.md index ac5deed..317ab79 100644 --- a/docs/hooks/signal.md +++ b/docs/hooks/signal.md @@ -1,3 +1,12 @@ +--- +title: Signal +description: +layout: doc +menu: + docs: + parent: "Hooks" +--- + + `signal.sigint` > Sent when Hilbish receives SIGINT (on Ctrl-C). + `signal.resize` > Sent when the terminal is resized. diff --git a/website/content/docs b/website/content/docs new file mode 120000 index 0000000..92a7f82 --- /dev/null +++ b/website/content/docs @@ -0,0 +1 @@ +../../docs \ No newline at end of file diff --git a/website/content/docs/api b/website/content/docs/api deleted file mode 120000 index 1c5c360..0000000 --- a/website/content/docs/api +++ /dev/null @@ -1 +0,0 @@ -../../../docs/api/ \ No newline at end of file From e8ea79b5eccade2e2b93b9181215bf8f28b9b478 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 17:37:08 -0400 Subject: [PATCH 12/26] website(docs): remove unused header --- website/themes/hsh/layouts/partials/head.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/themes/hsh/layouts/partials/head.html b/website/themes/hsh/layouts/partials/head.html index 6109fb5..147fb11 100644 --- a/website/themes/hsh/layouts/partials/head.html +++ b/website/themes/hsh/layouts/partials/head.html @@ -70,5 +70,9 @@ table tr { border-width: 1px; } + + thead { + display: none; + } From 2363e6ff2f2b33a3b3b8584f221c007f4229eff3 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 18:30:54 -0400 Subject: [PATCH 13/26] website(docs): add example --- cmd/docgen/docgen.go | 21 +++++++++++++++++++-- docs/api/bait.md | 16 ++++++++++++---- docs/hooks/_index.md | 15 ++------------- emmyLuaDocs/bait.lua | 4 +++- golibs/bait/bait.go | 13 ++++++++++--- 5 files changed, 46 insertions(+), 23 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 5b452d7..6e295be 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -64,11 +64,13 @@ type docPiece struct { Fields []docPiece Properties []docPiece Params []param + Tags map[string][]tag } type tag struct { id string fields []string + startIdx int } var docs = make(map[string]module) @@ -89,7 +91,7 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) { parts := []string{} tags := make(map[string][]tag) - for _, part := range pts { + for idx, part := range pts { if strings.HasPrefix(part, "#") { tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ") if tags[tagParts[0]] == nil { @@ -98,12 +100,21 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) { id = tagParts[1] } tags[tagParts[0]] = []tag{ - {id: id}, + {id: id, startIdx: idx}, } if len(tagParts) >= 2 { tags[tagParts[0]][0].fields = tagParts[2:] } } else { + if tagParts[0] == "example" { + exampleIdx := tags["example"][0].startIdx + exampleCode := pts[exampleIdx+1:idx] + + tags["example"][0].fields = exampleCode + parts = strings.Split(strings.Replace(strings.Join(parts, "\n"), strings.TrimPrefix(strings.Join(exampleCode, "\n"), "#example\n"), "", -1), "\n") + continue + } + fleds := []string{} if len(tagParts) >= 2 { fleds = tagParts[2:] @@ -188,6 +199,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece { ParentModule: parentMod, Fields: fields, Properties: properties, + Tags: tags, } typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces} @@ -273,6 +285,7 @@ start: Fields: fields, Properties: properties, Params: params, + Tags: tags, } if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) { dps.Doc = parts @@ -565,6 +578,10 @@ func main() { f.WriteString(strings.Join(p.Doc, " ")) f.WriteString("\n\n") } + if codeExample := dps.Tags["example"]; codeExample != nil { + f.WriteString("#### Example\n") + f.WriteString(fmt.Sprintf("```lua\n%s\n````\n", strings.Join(codeExample[0].fields, "\n"))) + } f.WriteString("

") f.WriteString("\n\n") } diff --git a/docs/api/bait.md b/docs/api/bait.md index 91cfb31..cc0eb1a 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -35,7 +35,7 @@ this function will set the user prompt. ## Functions ||| |----|----| -|catch(name, cb)|Catches a hook with `name`. Runs the `cb` when it is thrown| +|catch(name, cb)|Catches a hook. This function is used to act on hooks/events.| |catchOnce(name, cb)|Same as catch, but only runs the `cb` once and then removes the hook| |hooks(name) -> table|Returns a table with hooks (callback functions) on the event with `name`.| |release(name, catcher)|Removes the `catcher` for the event with `name`.| @@ -49,14 +49,22 @@ bait.catch(name, cb)

-Catches a hook with `name`. Runs the `cb` when it is thrown +Catches a hook. This function is used to act on hooks/events. + + #### Parameters `string` **`name`** -ummm +The name of the hook. `function` **`cb`** -? +The function that will be called when the hook is thrown. +#### Example +```lua +bait.catch('hilbish.exit', function() + print 'Goodbye Hilbish!' +end) +````
diff --git a/docs/hooks/_index.md b/docs/hooks/_index.md index 500b6e6..bb23477 100644 --- a/docs/hooks/_index.md +++ b/docs/hooks/_index.md @@ -7,16 +7,5 @@ menu: docs --- -Here is a list of bait hooks that are thrown by Hilbish. 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`. - -+ error -> eventName, handler, err > Emitted when there is an error in -an event handler. The `eventName` is the name of the event the handler -is for, the `handler` is the callback function, and `err` is the error -message. +Hooks are Hilbish's versions of events, which are used via the [Bait](../api/bait) module. +For more detail on how to act on these hooks, you may check the Bait page. diff --git a/emmyLuaDocs/bait.lua b/emmyLuaDocs/bait.lua index 6ca76ab..4b74f82 100644 --- a/emmyLuaDocs/bait.lua +++ b/emmyLuaDocs/bait.lua @@ -2,7 +2,9 @@ local bait = {} ---- Catches a hook with `name`. Runs the `cb` when it is thrown +--- Catches a hook. This function is used to act on hooks/events. +--- +--- function bait.catch(name, cb) end --- Same as catch, but only runs the `cb` once and then removes the hook diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index dca3773..e0a29da 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -271,9 +271,16 @@ func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // catch(name, cb) -// Catches a hook with `name`. Runs the `cb` when it is thrown -// #param name string ummm -// #param cb function ? +// Catches a hook. This function is used to act on hooks/events. +// #param name string The name of the hook. +// #param cb function The function that will be called when the hook is thrown. +/* +#example +bait.catch('hilbish.exit', function() + print 'Goodbye Hilbish!' +end) +#example +*/ func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { From e81384e42cab9fa176fce954c5f0648a92de87d7 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 18:32:28 -0400 Subject: [PATCH 14/26] refactor(bait): reorder functions alphabetically --- golibs/bait/bait.go | 80 ++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index e0a29da..0993c44 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -247,29 +247,6 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar } } -// throw(name, ...args) -// #param name string The name of the hook. -// #param args ...any The arguments to pass to the hook. -// Throws a hook with `name` with the provided `args` -// --- @param name string -// --- @vararg any -func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - if err := c.Check1Arg(); err != nil { - return nil, err - } - name, err := c.StringArg(0) - if err != nil { - return nil, err - } - ifaceSlice := make([]interface{}, len(c.Etc())) - for i, v := range c.Etc() { - ifaceSlice[i] = v - } - b.Emit(name, ifaceSlice...) - - return c.Next(), nil -} - // catch(name, cb) // Catches a hook. This function is used to act on hooks/events. // #param name string The name of the hook. @@ -307,23 +284,6 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } -// 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. -// --- @param name string -// --- @param catcher function -func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - name, catcher, err := util.HandleStrCallback(t, c) - if err != nil { - return nil, err - } - - b.OffLua(name, catcher) - - return c.Next(), nil -} - // hooks(name) -> table // Returns a table with hooks (callback functions) on the event with `name`. // --- @param name string @@ -355,3 +315,43 @@ func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext1(t.Runtime, rt.TableValue(luaHandlers)), nil } + +// 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. +// --- @param name string +// --- @param catcher function +func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + name, catcher, err := util.HandleStrCallback(t, c) + if err != nil { + return nil, err + } + + b.OffLua(name, catcher) + + return c.Next(), nil +} + +// throw(name, ...args) +// #param name string The name of the hook. +// #param args ...any The arguments to pass to the hook. +// Throws a hook with `name` with the provided `args` +// --- @param name string +// --- @vararg any +func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + if err := c.Check1Arg(); err != nil { + return nil, err + } + name, err := c.StringArg(0) + if err != nil { + return nil, err + } + ifaceSlice := make([]interface{}, len(c.Etc())) + for i, v := range c.Etc() { + ifaceSlice[i] = v + } + b.Emit(name, ifaceSlice...) + + return c.Next(), nil +} From f516e1bb8726022ac3939d11ab5ca0f793f50e92 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 22:00:47 -0400 Subject: [PATCH 15/26] website(docs): setup custom syntax highlighting, add line numbers --- website/config.toml | 5 ++++- website/themes/hsh/assets/css/syntax.css | 10 +++++++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/website/config.toml b/website/config.toml index 0ae7ff2..5c9939f 100644 --- a/website/config.toml +++ b/website/config.toml @@ -30,7 +30,10 @@ enableGitInfo = true unsafe = true [markup.highlight] -style = 'pastie' +lineNos = true +lineNumbersInTable = false +noClasses = false +codeFences = true [author] [author.sammyette] diff --git a/website/themes/hsh/assets/css/syntax.css b/website/themes/hsh/assets/css/syntax.css index 021dcb3..c4885c0 100644 --- a/website/themes/hsh/assets/css/syntax.css +++ b/website/themes/hsh/assets/css/syntax.css @@ -1,11 +1,15 @@ -/* Background */ .bg { background-color: #edfdff; } -/* PreWrapper */ .chroma { background-color: #edfdff; } +.chroma { + display: inline-block; + padding: 0.5em; +} +/* Background */ .bg { background-color: #F7F7F7; } +/* PreWrapper */ .chroma { background-color: #F7F7F7; } /* Other */ .chroma .x { } /* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 } /* CodeLine */ .chroma .cl { } /* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; } /* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; } -/* LineHighlight */ .chroma .hl { background-color: #edfdff } +/* LineHighlight */ .chroma .hl { background-color: #F7F7F7 } /* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f } /* Line */ .chroma .line { display: flex; } From d921d3f75264cd49b343fb7857aa2766f366cd8b Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 22:07:48 -0400 Subject: [PATCH 16/26] website(docs/bait): complete documentation --- docs/api/bait.md | 46 +++++++++++++++++++++++++++++++++----------- emmyLuaDocs/bait.lua | 18 ++++++----------- golibs/bait/bait.go | 33 +++++++++++++++++++------------ 3 files changed, 62 insertions(+), 35 deletions(-) diff --git a/docs/api/bait.md b/docs/api/bait.md index cc0eb1a..9f32b25 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -35,11 +35,11 @@ this function will set the user prompt. ## Functions ||| |----|----| -|catch(name, cb)|Catches a hook. This function is used to act on hooks/events.| -|catchOnce(name, cb)|Same as catch, but only runs the `cb` once and then removes the hook| -|hooks(name) -> table|Returns a table with hooks (callback functions) on the event with `name`.| +|catch(name, cb)|Catches an event. This function can be used to act on events.| +|catchOnce(name, cb)|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.| +|hooks(name) -> table|Returns a list of callbacks that are hooked on an event with the corresponding `name`.| |release(name, catcher)|Removes the `catcher` for the event with `name`.| -|throw(name, ...args)|Throws a hook with `name` with the provided `args`| +|throw(name, ...args)|Throws a hook with `name` with the provided `args`.|

@@ -49,7 +49,7 @@ bait.catch(name, cb)

-Catches a hook. This function is used to act on hooks/events. +Catches an event. This function can be used to act on events. #### Parameters @@ -75,9 +75,14 @@ bait.catchOnce(name, cb)

-Same as catch, but only runs the `cb` once and then removes the hook +Catches an event, but only once. This will remove the hook immediately after it runs for the first time. #### Parameters -This function has no parameters. +`string` **`name`** +The name of the event + +`function` **`cb`** +The function that will be called when the event is thrown. +
@@ -88,9 +93,11 @@ bait.hooks(name) -> table

-Returns a table with hooks (callback functions) on the event with `name`. +Returns a list of callbacks that are hooked on an event with the corresponding `name`. #### Parameters -This function has no parameters. +`string` **`name`** +The name of the function +
@@ -104,8 +111,25 @@ bait.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. + + #### Parameters -This function has no parameters. +`string` **`name`** +Name of the event the hook is on + +`function` **`catcher`** +Hook function to remove + +#### Example +```lua +local hookCallback = function() print 'hi' end + +bait.catch('event', hookCallback) + +-- a little while later.... +bait.release('event', hookCallback) +-- and now hookCallback will no longer be ran for the event. +````
@@ -116,7 +140,7 @@ bait.throw(name, ...args)

-Throws a hook with `name` with the provided `args` +Throws a hook with `name` with the provided `args`. #### Parameters `string` **`name`** The name of the hook. diff --git a/emmyLuaDocs/bait.lua b/emmyLuaDocs/bait.lua index 4b74f82..699d2a5 100644 --- a/emmyLuaDocs/bait.lua +++ b/emmyLuaDocs/bait.lua @@ -2,31 +2,25 @@ local bait = {} ---- Catches a hook. This function is used to act on hooks/events. +--- Catches an event. This function can be used to act on events. --- --- 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 +--- Catches an event, but only once. This will remove the hook immediately after it runs for the first time. function bait.catchOnce(name, cb) end ---- Returns a table with hooks (callback functions) on the event with `name`. ---- @param name string ---- @returns table +--- Returns a list of callbacks that are hooked on an event with the corresponding `name`. function bait.hooks(name) end --- 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. ---- @param name string ---- @param catcher function +--- +--- function bait.release(name, catcher) end ---- Throws a hook with `name` with the provided `args` ---- @param name string ---- @vararg any +--- Throws a hook with `name` with the provided `args`. function bait.throw(name, ...args) end return bait diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 0993c44..b507d2b 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -248,7 +248,7 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar } // catch(name, cb) -// Catches a hook. This function is used to act on hooks/events. +// Catches an event. This function can be used to act on events. // #param name string The name of the hook. // #param cb function The function that will be called when the hook is thrown. /* @@ -270,9 +270,9 @@ func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // catchOnce(name, cb) -// Same as catch, but only runs the `cb` once and then removes the hook -// --- @param name string -// --- @param cb function +// Catches an event, but only once. This will remove the hook immediately after it runs for the first time. +// #param name string The name of the event +// #param cb function The function that will be called when the event is thrown. func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { @@ -285,9 +285,9 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // hooks(name) -> table -// Returns a table with hooks (callback functions) on the event with `name`. -// --- @param name string -// --- @returns table +// Returns a list of callbacks that are hooked on an event with the corresponding `name`. +// #param name string The name of the function +// #returns table func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -320,8 +320,19 @@ func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // 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. -// --- @param name string -// --- @param catcher function +// #param name string Name of the event the hook is on +// #param catcher function Hook function to remove +/* +#example +local hookCallback = function() print 'hi' end + +bait.catch('event', hookCallback) + +-- a little while later.... +bait.release('event', hookCallback) +-- and now hookCallback will no longer be ran for the event. +#example +*/ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { @@ -336,9 +347,7 @@ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // throw(name, ...args) // #param name string The name of the hook. // #param args ...any The arguments to pass to the hook. -// Throws a hook with `name` with the provided `args` -// --- @param name string -// --- @vararg any +// Throws a hook with `name` with the provided `args`. func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err From 068ef7a3760e0ad4b9c011e40134dac8fffa6e05 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 22:09:07 -0400 Subject: [PATCH 17/26] website(docs/bait): add example for throw function --- docs/api/bait.md | 11 +++++++++++ emmyLuaDocs/bait.lua | 2 ++ golibs/bait/bait.go | 10 ++++++++++ 3 files changed, 23 insertions(+) diff --git a/docs/api/bait.md b/docs/api/bait.md index 9f32b25..1bc30b7 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -141,6 +141,8 @@ bait.throw(name, ...args)

Throws a hook with `name` with the provided `args`. + + #### Parameters `string` **`name`** The name of the hook. @@ -148,5 +150,14 @@ The name of the hook. `any` **`args`** (This type is variadic. You can pass an infinite amount of parameters with this type.) The arguments to pass to the hook. +#### Example +```lua +bait.throw('greeting', 'world') + +-- This can then be listened to via +bait.catch('gretting', function(greetTo) + print('Hello ' .. greetTo) +end) +````
diff --git a/emmyLuaDocs/bait.lua b/emmyLuaDocs/bait.lua index 699d2a5..09f3d98 100644 --- a/emmyLuaDocs/bait.lua +++ b/emmyLuaDocs/bait.lua @@ -21,6 +21,8 @@ function bait.hooks(name) end function bait.release(name, catcher) end --- Throws a hook with `name` with the provided `args`. +--- +--- function bait.throw(name, ...args) end return bait diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index b507d2b..8f24d17 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -348,6 +348,16 @@ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #param name string The name of the hook. // #param args ...any The arguments to pass to the hook. // Throws a hook with `name` with the provided `args`. +/* +#example +bait.throw('greeting', 'world') + +-- This can then be listened to via +bait.catch('gretting', function(greetTo) + print('Hello ' .. greetTo) +end) +#example +*/ func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err From bb8d072b8c1dd44ba5e0c4891df0120c88c2b249 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 22:19:13 -0400 Subject: [PATCH 18/26] website(docs/commander): rewrite commander docs --- docs/api/commander.md | 56 ++++++++++++++++++++++++----------- emmyLuaDocs/commander.lua | 10 +++---- golibs/commander/commander.go | 46 +++++++++++++++++----------- 3 files changed, 72 insertions(+), 40 deletions(-) diff --git a/docs/api/commander.md b/docs/api/commander.md index 4d67c81..dcb6306 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -9,11 +9,10 @@ menu: ## Introduction -Commander is a library for writing custom commands in Lua. -In order to make it easier to write commands for Hilbish, -not require separate scripts and to be able to use in a config, -the Commander library exists. This is like a very simple wrapper -that works with Hilbish for writing commands. Example: +Commander is the library which handles Hilbish commands. This makes +the user able to add Lua-written commands to their shell without making +a separate script in a bin folder. Instead, you may simply use the Commander +library in your Hilbish config. ```lua local commander = require 'commander' @@ -28,20 +27,20 @@ that will print `Hello world!` to output. One question you may have is: What is the `sinks` parameter? The `sinks` parameter is a table with 3 keys: `in`, `out`, -and `err`. The values of these is a Sink. +and `err`. All of them are a Sink. -- `in` is the standard input. You can read from this sink -to get user input. -- `out` is standard output. This is usually where text meant for -output should go. -- `err` is standard error. This sink is for writing errors, as the -name would suggest. +- `in` is the standard input. +You may use the read functions on this sink to get input from the user. +- `out` is standard output. +This is usually where command output should go. +- `err` is standard error. +This sink is for writing errors, as the name would suggest. ## Functions ||| |----|----| -|deregister(name)|Deregisters any command registered with `name`| -|register(name, cb)|Register a command with `name` that runs `cb` when ran| +|deregister(name)|Removes the named command. Note that this will only remove Commander-registered commands.| +|register(name, cb)|Adds a new command with the given `name`. When Hilbish has to run a command with a name,|

@@ -51,9 +50,11 @@ commander.deregister(name)

-Deregisters any command registered with `name` +Removes the named command. Note that this will only remove Commander-registered commands. #### Parameters -This function has no parameters. +`string` **`name`** +Name of the command to remove. +
@@ -64,8 +65,27 @@ commander.register(name, cb)

-Register a command with `name` that runs `cb` when ran +Adds a new command with the given `name`. When Hilbish has to run a command with a name, +it will run the function providing the arguments and sinks. + + #### Parameters -This function has no parameters. +`string` **`name`** +Name of the command + +`function` **`cb`** +Callback to handle command invocation + +#### Example +```lua +-- When you run the command `hello` in the shell, it will print `Hello world`. +-- If you run it with, for example, `hello Hilbish`, it will print 'Hello Hilbish' +commander.register('hello', function(args, sinks) + local name = 'world' + if #args > 0 then name = args[1] end + + sinks.out:writeln('Hello ' .. name) +end) +````
diff --git a/emmyLuaDocs/commander.lua b/emmyLuaDocs/commander.lua index c6738dd..285c4b5 100644 --- a/emmyLuaDocs/commander.lua +++ b/emmyLuaDocs/commander.lua @@ -2,13 +2,13 @@ local commander = {} ---- Deregisters any command registered with `name` ---- @param name string +--- Removes the named command. Note that this will only remove Commander-registered commands. function commander.deregister(name) end ---- Register a command with `name` that runs `cb` when ran ---- @param name string ---- @param cb function +--- Adds a new command with the given `name`. When Hilbish has to run a command with a name, +--- it will run the function providing the arguments and sinks. +--- +--- function commander.register(name, cb) end return commander diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index a21de1c..ea2da7a 100644 --- a/golibs/commander/commander.go +++ b/golibs/commander/commander.go @@ -1,10 +1,9 @@ // library for custom commands /* -Commander is a library for writing custom commands in Lua. -In order to make it easier to write commands for Hilbish, -not require separate scripts and to be able to use in a config, -the Commander library exists. This is like a very simple wrapper -that works with Hilbish for writing commands. Example: +Commander is the library which handles Hilbish commands. This makes +the user able to add Lua-written commands to their shell without making +a separate script in a bin folder. Instead, you may simply use the Commander +library in your Hilbish config. ```lua local commander = require 'commander' @@ -19,14 +18,14 @@ that will print `Hello world!` to output. One question you may have is: What is the `sinks` parameter? The `sinks` parameter is a table with 3 keys: `in`, `out`, -and `err`. The values of these is a @Sink. +and `err`. All of them are a @Sink. -- `in` is the standard input. You can read from this sink -to get user input. -- `out` is standard output. This is usually where text meant for -output should go. -- `err` is standard error. This sink is for writing errors, as the -name would suggest. +- `in` is the standard input. +You may use the read functions on this sink to get input from the user. +- `out` is standard output. +This is usually where command output should go. +- `err` is standard error. +This sink is for writing errors, as the name would suggest. */ package commander @@ -67,9 +66,22 @@ func (c *Commander) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) { } // register(name, cb) -// Register a command with `name` that runs `cb` when ran -// --- @param name string -// --- @param cb function +// Adds a new command with the given `name`. When Hilbish has to run a command with a name, +// it will run the function providing the arguments and sinks. +// #param name string Name of the command +// #param cb function Callback to handle command invocation +/* +#example +-- When you run the command `hello` in the shell, it will print `Hello world`. +-- If you run it with, for example, `hello Hilbish`, it will print 'Hello Hilbish' +commander.register('hello', function(args, sinks) + local name = 'world' + if #args > 0 then name = args[1] end + + sinks.out:writeln('Hello ' .. name) +end) +#example +*/ func (c *Commander) cregister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) { cmdName, cmd, err := util.HandleStrCallback(t, ct) if err != nil { @@ -82,8 +94,8 @@ func (c *Commander) cregister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) { } // deregister(name) -// Deregisters any command registered with `name` -// --- @param name string +// Removes the named command. Note that this will only remove Commander-registered commands. +// #param name string Name of the command to remove. func (c *Commander) cderegister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) { if err := ct.Check1Arg(); err != nil { return nil, err From 77979dca1944221f3c222dd6cd2ea7ba91e42eb4 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 08:22:09 -0400 Subject: [PATCH 19/26] website: set highlighter options to guess syntax --- website/config.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/config.toml b/website/config.toml index 5c9939f..174c434 100644 --- a/website/config.toml +++ b/website/config.toml @@ -1,5 +1,5 @@ -baseURL = 'https://rosettea.github.io/Hilbish/' languageCode = 'en-us' +baseURL = 'https://rosettea.github.io/Hilbish/' title = 'Hilbish' theme = 'hsh' enableGitInfo = true @@ -34,6 +34,7 @@ lineNos = true lineNumbersInTable = false noClasses = false codeFences = true +guessSyntax = true [author] [author.sammyette] From 393b2009bf3f32e0f6b782af2a835255931eb34b Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 08:22:40 -0400 Subject: [PATCH 20/26] fix(docgen): add double space after line of text --- cmd/docgen/docgen.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 6e295be..12d9f76 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -555,7 +555,7 @@ func main() { `, htmlSig, dps.FuncName)) for _, doc := range dps.Doc { if !strings.HasPrefix(doc, "---") { - f.WriteString(doc + "\n") + f.WriteString(doc + " \n") } } f.WriteString("#### Parameters\n") From be526c15d1e874ef1f1a932cff410ba7e9523e50 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 08:23:40 -0400 Subject: [PATCH 21/26] doc(fs): rewrite docs --- golibs/fs/fs.go | 328 ++++++++++++++++++++++++++++-------------------- 1 file changed, 189 insertions(+), 139 deletions(-) diff --git a/golibs/fs/fs.go b/golibs/fs/fs.go index 1c1a5ca..848d82c 100644 --- a/golibs/fs/fs.go +++ b/golibs/fs/fs.go @@ -1,7 +1,10 @@ // filesystem interaction and functionality library -// 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 fs module provides filesystem functions to Hilbish. While Lua's standard +library has some I/O functions, they're missing a lot of the basics. The `fs` +library offers more functions and will work on any operating system Hilbish does. +#field pathSep The operating system's path separator. +*/ package fs import ( @@ -42,9 +45,46 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) { return rt.TableValue(mod), nil } +// abs(path) -> string +// Returns an absolute version of the `path`. +// This can be used to resolve short paths like `..` to `/home/user`. +// #param path string +// #returns string +func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + path, err := c.StringArg(0) + if err != nil { + return nil, err + } + path = util.ExpandHome(path) + + abspath, err := filepath.Abs(path) + if err != nil { + return nil, err + } + + return c.PushingNext1(t.Runtime, rt.StringValue(abspath)), nil +} + +// basename(path) -> string +// Returns the "basename," or the last part of the provided `path`. If path is empty, +// `.` will be returned. +// #param path string Path to get the base name of. +// #returns string +func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + if err := c.Check1Arg(); err != nil { + return nil, err + } + path, err := c.StringArg(0) + if err != nil { + return nil, err + } + + return c.PushingNext(t.Runtime, rt.StringValue(filepath.Base(path))), nil +} + // cd(dir) -// Changes directory to `dir` -// --- @param dir string +// Changes Hilbish's directory to `dir`. +// #param dir string Path to change directory to. func fcd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -63,10 +103,102 @@ func fcd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), err } +// dir(path) -> string +// Returns the directory part of `path`. If a file path like +// `~/Documents/doc.txt` then this function will return `~/Documents`. +// #param path string Path to get the directory for. +// #returns string +func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + if err := c.Check1Arg(); err != nil { + return nil, err + } + path, err := c.StringArg(0) + if err != nil { + return nil, err + } + + return c.PushingNext(t.Runtime, rt.StringValue(filepath.Dir(path))), nil +} + +// glob(pattern) -> matches (table) +// Match all files based on the provided `pattern`. +// For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match +// #param pattern string Pattern to compare files with. +// #returns table A list of file names/paths that match. +/* +#example +--[[ + Within a folder that contains the following files: + a.txt + init.lua + code.lua + doc.pdf +]]-- +local matches = fs.glob './*.lua' +print(matches) +-- -> {'init.lua', 'code.lua'} +#example +*/ +func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + if err := c.Check1Arg(); err != nil { + return nil, err + } + pattern, err := c.StringArg(0) + if err != nil { + return nil, err + } + + matches, err := filepath.Glob(pattern) + if err != nil { + return nil, err + } + + luaMatches := rt.NewTable() + + for i, match := range matches { + luaMatches.Set(rt.IntValue(int64(i + 1)), rt.StringValue(match)) + } + + return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil +} + +// join(...path) -> string +// Takes any list of paths and joins them based on the operating system's path separator. +// #param path ...string Paths to join together +// #returns string The joined path. +/* +#example +-- This prints the directory for Hilbish's config! +print(fs.join(hilbish.userDir.config, 'hilbish')) +-- -> '/home/user/.config/hilbish' on Linux +#example +*/ +func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + strs := make([]string, len(c.Etc())) + for i, v := range c.Etc() { + if v.Type() != rt.StringType { + // +2; go indexes of 0 and first arg from above + return nil, fmt.Errorf("bad argument #%d to run (expected string, got %s)", i + 1, v.TypeName()) + } + strs[i] = v.AsString() + } + + res := filepath.Join(strs...) + + return c.PushingNext(t.Runtime, rt.StringValue(res)), nil +} + // mkdir(name, recursive) -// Makes a directory called `name`. If `recursive` is true, it will create its parent directories. -// --- @param name string -// --- @param recursive boolean +// Creates a new directory with the provided `name`. +// With `recursive`, mkdir will create parent directories. +// #param name string Name of the directory +// #param recursive boolean Whether to create parent directories for the provided name +/* +#example +-- This will create the directory foo, then create the directory bar in the +-- foo directory. If recursive is false in this case, it will fail. +fs.mkdir('./foo/bar', true) +*/ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(2); err != nil { return nil, err @@ -93,15 +225,58 @@ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), err } +// readdir(path) -> table[string] +// Returns a list of all files and directories in the provided path. +// #param dir string +// #returns table +func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { + if err := c.Check1Arg(); err != nil { + return nil, err + } + dir, err := c.StringArg(0) + if err != nil { + return nil, err + } + dir = util.ExpandHome(dir) + names := rt.NewTable() + + dirEntries, err := os.ReadDir(dir) + if err != nil { + return nil, err + } + for i, entry := range dirEntries { + names.Set(rt.IntValue(int64(i + 1)), rt.StringValue(entry.Name())) + } + + return c.PushingNext1(t.Runtime, rt.TableValue(names)), nil +} + // stat(path) -> {} -// Returns a table of info about the `path`. -// It contains the following keys: +// Returns the information about a given `path`. +// The returned table contains the following values: // name (string) - Name of the path -// size (number) - Size of the path -// mode (string) - Permission mode in an octal format string (with leading 0) +// size (number) - Size of the path in bytes +// mode (string) - Unix permission mode in an octal format string (with leading 0) // isDir (boolean) - If the path is a directory -// --- @param path string -// --- @returns table +// #param path string +// #returns table +/* +#example +local inspect = require 'inspect' + +local stat = fs.stat '~' +print(inspect(stat)) +--[[ +Would print the following: +{ + isDir = true, + mode = "0755", + name = "username", + size = 12288 +} +]]-- +#example +*/ func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -125,128 +300,3 @@ func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext1(t.Runtime, rt.TableValue(statTbl)), nil } -// readdir(dir) -> {} -// Returns a table of files in `dir`. -// --- @param dir string -// --- @return table -func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - if err := c.Check1Arg(); err != nil { - return nil, err - } - dir, err := c.StringArg(0) - if err != nil { - return nil, err - } - dir = util.ExpandHome(dir) - names := rt.NewTable() - - dirEntries, err := os.ReadDir(dir) - if err != nil { - return nil, err - } - for i, entry := range dirEntries { - names.Set(rt.IntValue(int64(i + 1)), rt.StringValue(entry.Name())) - } - - return c.PushingNext1(t.Runtime, rt.TableValue(names)), nil -} - -// abs(path) -> string -// Gives an absolute version of `path`. -// --- @param path string -// --- @returns string -func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - path, err := c.StringArg(0) - if err != nil { - return nil, err - } - path = util.ExpandHome(path) - - abspath, err := filepath.Abs(path) - if err != nil { - return nil, err - } - - return c.PushingNext1(t.Runtime, rt.StringValue(abspath)), nil -} - -// basename(path) -> string -// Gives the basename of `path`. For the rules, -// see Go's filepath.Base -// --- @returns string -func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - if err := c.Check1Arg(); err != nil { - return nil, err - } - path, err := c.StringArg(0) - if err != nil { - return nil, err - } - - return c.PushingNext(t.Runtime, rt.StringValue(filepath.Base(path))), nil -} - -// dir(path) -> string -// Returns the directory part of `path`. For the rules, see Go's -// filepath.Dir -// --- @param path string -// --- @returns string -func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - if err := c.Check1Arg(); err != nil { - return nil, err - } - path, err := c.StringArg(0) - if err != nil { - return nil, err - } - - return c.PushingNext(t.Runtime, rt.StringValue(filepath.Dir(path))), nil -} - -// glob(pattern) -> matches (table) -// Glob all files and directories that match the pattern. -// For the rules, see Go's filepath.Glob -// --- @param pattern string -// --- @returns table -func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - if err := c.Check1Arg(); err != nil { - return nil, err - } - pattern, err := c.StringArg(0) - if err != nil { - return nil, err - } - - matches, err := filepath.Glob(pattern) - if err != nil { - return nil, err - } - - luaMatches := rt.NewTable() - - for i, match := range matches { - luaMatches.Set(rt.IntValue(int64(i + 1)), rt.StringValue(match)) - } - - return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil -} - -// join(...) -> string -// Takes paths and joins them together with the OS's -// directory separator (forward or backward slash). -// --- @vararg string -// --- @returns string -func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - strs := make([]string, len(c.Etc())) - for i, v := range c.Etc() { - if v.Type() != rt.StringType { - // +2; go indexes of 0 and first arg from above - return nil, fmt.Errorf("bad argument #%d to run (expected string, got %s)", i + 1, v.TypeName()) - } - strs[i] = v.AsString() - } - - res := filepath.Join(strs...) - - return c.PushingNext(t.Runtime, rt.StringValue(res)), nil -} From f40ce3c8f71f54cbd722d562c83ed2f1c1d66f4a Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 08:23:49 -0400 Subject: [PATCH 22/26] chore: update docs --- docs/api/bait.md | 26 ++-- docs/api/commander.md | 10 +- docs/api/fs.md | 159 ++++++++++++++++++------ docs/api/hilbish/_index.md | 106 ++++++++-------- docs/api/hilbish/hilbish.aliases.md | 8 +- docs/api/hilbish/hilbish.completions.md | 16 +-- docs/api/hilbish/hilbish.editor.md | 12 +- docs/api/hilbish/hilbish.history.md | 10 +- docs/api/hilbish/hilbish.jobs.md | 10 +- docs/api/hilbish/hilbish.module.md | 4 +- docs/api/hilbish/hilbish.runner.md | 16 +-- docs/api/hilbish/hilbish.timers.md | 6 +- docs/api/terminal.md | 10 +- emmyLuaDocs/fs.lua | 63 +++++----- 14 files changed, 264 insertions(+), 192 deletions(-) diff --git a/docs/api/bait.md b/docs/api/bait.md index 1bc30b7..9bed78d 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -49,9 +49,9 @@ bait.catch(name, cb)

-Catches an event. This function can be used to act on events. - - +Catches an event. This function can be used to act on events. + + #### Parameters `string` **`name`** The name of the hook. @@ -75,7 +75,7 @@ bait.catchOnce(name, cb)

-Catches an event, but only once. This will remove the hook immediately after it runs for the first time. +Catches an event, but only once. This will remove the hook immediately after it runs for the first time. #### Parameters `string` **`name`** The name of the event @@ -93,7 +93,7 @@ bait.hooks(name) -> table

-Returns a list of callbacks that are hooked on an event with the corresponding `name`. +Returns a list of callbacks that are hooked on an event with the corresponding `name`. #### Parameters `string` **`name`** The name of the function @@ -108,11 +108,11 @@ bait.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. - - +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. + + #### Parameters `string` **`name`** Name of the event the hook is on @@ -140,9 +140,9 @@ bait.throw(name, ...args)

-Throws a hook with `name` with the provided `args`. - - +Throws a hook with `name` with the provided `args`. + + #### Parameters `string` **`name`** The name of the hook. diff --git a/docs/api/commander.md b/docs/api/commander.md index dcb6306..3614f90 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -50,7 +50,7 @@ commander.deregister(name) -Removes the named command. Note that this will only remove Commander-registered commands. +Removes the named command. Note that this will only remove Commander-registered commands. #### Parameters `string` **`name`** Name of the command to remove. @@ -65,10 +65,10 @@ commander.register(name, cb) -Adds a new command with the given `name`. When Hilbish has to run a command with a name, -it will run the function providing the arguments and sinks. - - +Adds a new command with the given `name`. When Hilbish has to run a command with a name, +it will run the function providing the arguments and sinks. + + #### Parameters `string` **`name`** Name of the command diff --git a/docs/api/fs.md b/docs/api/fs.md index 37045eb..0bda1c8 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -8,22 +8,28 @@ menu: --- ## 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 fs module provides filesystem functions to Hilbish. While Lua's standard +library has some I/O functions, they're missing a lot of the basics. The `fs` +library offers more functions and will work on any operating system Hilbish does. ## Functions ||| |----|----| -|abs(path) -> string|Gives an absolute version of `path`.| -|basename(path) -> string|Gives the basename of `path`. For the rules,| -|cd(dir)|Changes directory to `dir`| -|dir(path) -> string|Returns the directory part of `path`. For the rules, see Go's| -|glob(pattern) -> matches (table)|Glob all files and directories that match the pattern.| -|join(...) -> string|Takes paths and joins them together with the OS's| -|mkdir(name, recursive)|Makes a directory called `name`. If `recursive` is true, it will create its parent directories.| -|readdir(dir) -> {}|Returns a table of files in `dir`.| -|stat(path) -> {}|Returns a table of info about the `path`.| +|abs(path) -> string|Returns an absolute version of the `path`.| +|basename(path) -> string|Returns the "basename," or the last part of the provided `path`. If path is empty,| +|cd(dir)|Changes Hilbish's directory to `dir`.| +|dir(path) -> string|Returns the directory part of `path`. If a file path like| +|glob(pattern) -> matches (table)|Match all files based on the provided `pattern`.| +|join(...path) -> string|Takes any list of paths and joins them based on the operating system's path separator.| +|mkdir(name, recursive)|Creates a new directory with the provided `name`.| +|readdir(path) -> table[string]|Returns a list of all files and directories in the provided path.| +|stat(path) -> {}|Returns the information about a given `path`.| + +## Static module fields +||| +|----|----| +|pathSep|The operating system's path separator.|

@@ -33,9 +39,12 @@ fs.abs(path) -> string

-Gives an absolute version of `path`. +Returns an absolute version of the `path`. +This can be used to resolve short paths like `..` to `/home/user`. #### Parameters -This function has no parameters. +`string` **`path`** + +
@@ -46,10 +55,12 @@ fs.basename(path) -> string -Gives the basename of `path`. For the rules, -see Go's filepath.Base +Returns the "basename," or the last part of the provided `path`. If path is empty, +`.` will be returned. #### Parameters -This function has no parameters. +`string` **`path`** +Path to get the base name of. +
@@ -60,9 +71,11 @@ fs.cd(dir) -Changes directory to `dir` +Changes Hilbish's directory to `dir`. #### Parameters -This function has no parameters. +`string` **`dir`** +Path to change directory to. +
@@ -73,10 +86,12 @@ fs.dir(path) -> string -Returns the directory part of `path`. For the rules, see Go's -filepath.Dir +Returns the directory part of `path`. If a file path like +`~/Documents/doc.txt` then this function will return `~/Documents`. #### Parameters -This function has no parameters. +`string` **`path`** +Path to get the directory for. +
@@ -87,24 +102,50 @@ fs.glob(pattern) -> matches (table) -Glob all files and directories that match the pattern. -For the rules, see Go's filepath.Glob +Match all files based on the provided `pattern`. +For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match + + #### Parameters -This function has no parameters. +`string` **`pattern`** +Pattern to compare files with. + +#### Example +```lua +--[[ + Within a folder that contains the following files: + a.txt + init.lua + code.lua + doc.pdf +]]-- +local matches = fs.glob './*.lua' +print(matches) +-- -> {'init.lua', 'code.lua'} +````

-fs.join(...) -> string +fs.join(...path) -> string

-Takes paths and joins them together with the OS's -directory separator (forward or backward slash). +Takes any list of paths and joins them based on the operating system's path separator. + + #### Parameters -This function has no parameters. +`string` **`path`** (This type is variadic. You can pass an infinite amount of parameters with this type.) +Paths to join together + +#### Example +```lua +-- This prints the directory for Hilbish's config! +print(fs.join(hilbish.userDir.config, 'hilbish')) +-- -> '/home/user/.config/hilbish' on Linux +````
@@ -115,22 +156,38 @@ fs.mkdir(name, recursive) -Makes a directory called `name`. If `recursive` is true, it will create its parent directories. +Creates a new directory with the provided `name`. +With `recursive`, mkdir will create parent directories. + +-- This will create the directory foo, then create the directory bar in the +-- foo directory. If recursive is false in this case, it will fail. +fs.mkdir('./foo/bar', true) #### Parameters -This function has no parameters. +`string` **`name`** +Name of the directory + +`boolean` **`recursive`** +Whether to create parent directories for the provided name + +#### Example +```lua + +````

-fs.readdir(dir) -> {} +fs.readdir(path) -> table[string]

-Returns a table of files in `dir`. +Returns a list of all files and directories in the provided path. #### Parameters -This function has no parameters. +`string` **`dir`** + +
@@ -141,13 +198,33 @@ fs.stat(path) -> {} -Returns a table of info about the `path`. -It contains the following keys: -name (string) - Name of the path -size (number) - Size of the path -mode (string) - Permission mode in an octal format string (with leading 0) -isDir (boolean) - If the path is a directory +Returns the information about a given `path`. +The returned table contains the following values: +name (string) - Name of the path +size (number) - Size of the path in bytes +mode (string) - Unix permission mode in an octal format string (with leading 0) +isDir (boolean) - If the path is a directory + + #### Parameters -This function has no parameters. +`string` **`path`** + + +#### Example +```lua +local inspect = require 'inspect' + +local stat = fs.stat '~' +print(inspect(stat)) +--[[ +Would print the following: +{ + isDir = true, + mode = "0755", + name = "username", + size = 12288 +} +]]-- +````
diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 0cb17d5..8278376 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -54,7 +54,7 @@ hilbish.alias(cmd, orig) -Sets an alias of `cmd` to `orig` +Sets an alias of `cmd` to `orig` #### Parameters This function has no parameters.
@@ -67,7 +67,7 @@ hilbish.appendPath(dir) -Appends `dir` to $PATH +Appends `dir` to $PATH #### Parameters This function has no parameters.
@@ -80,11 +80,11 @@ hilbish.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. +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. #### Parameters This function has no parameters.
@@ -97,7 +97,7 @@ hilbish.cwd() -> string -Returns the current directory of the shell +Returns the current directory of the shell #### Parameters This function has no parameters.
@@ -110,7 +110,7 @@ hilbish.exec(cmd) -Replaces running hilbish with `cmd` +Replaces running hilbish with `cmd` #### Parameters This function has no parameters.
@@ -123,7 +123,7 @@ hilbish.goro(fn) -Puts `fn` in a goroutine +Puts `fn` in a goroutine #### Parameters This function has no parameters.
@@ -136,18 +136,18 @@ hilbish.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. -Note that to set a highlighter, one has to override this function. -Example: -``` -function hilbish.highlighter(line) - return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) -end -``` -This code will highlight all double quoted strings in green. +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. +Note that to set a highlighter, one has to override this function. +Example: +``` +function hilbish.highlighter(line) + return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) +end +``` +This code will highlight all double quoted strings in green. #### Parameters This function has no parameters.
@@ -160,11 +160,11 @@ hilbish.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. +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. #### Parameters This function has no parameters.
@@ -177,7 +177,7 @@ hilbish.inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim +Sets the input mode for Hilbish's line reader. Accepts either emacs or vim #### Parameters This function has no parameters.
@@ -190,8 +190,8 @@ hilbish.interval(cb, time) -> -Runs the `cb` function after `time` in milliseconds. -This creates a timer that starts immediately. +Runs the `cb` function after `time` in milliseconds. +This creates a timer that starts immediately. #### Parameters This function has no parameters.
@@ -309,8 +309,8 @@ hilbish.which(name) -> string -Checks if `name` is a valid command. -Will return the path of the binary, or a basename if it's a commander. +Checks if `name` is a valid command. +Will return the path of the binary, or a basename if it's a commander. #### Parameters This function has no parameters.
diff --git a/docs/api/hilbish/hilbish.aliases.md b/docs/api/hilbish/hilbish.aliases.md index 5274e04..4cd5187 100644 --- a/docs/api/hilbish/hilbish.aliases.md +++ b/docs/api/hilbish/hilbish.aliases.md @@ -26,7 +26,7 @@ hilbish.aliases.add(alias, cmd) -This is an alias (ha) for the `hilbish.alias` function. +This is an alias (ha) for the `hilbish.alias` function. #### Parameters This function has no parameters.
@@ -39,7 +39,7 @@ hilbish.aliases.delete(name) -Removes an alias. +Removes an alias. #### Parameters This function has no parameters.
@@ -52,7 +52,7 @@ hilbish.aliases.list() -> table\ -Get a table of all aliases, with string keys as the alias and the value as the command. +Get a table of all aliases, with string keys as the alias and the value as the command. #### Parameters This function has no parameters.
@@ -65,7 +65,7 @@ hilbish.aliases.resolve(alias) -> command (string) -Tries to resolve an alias to its command. +Tries to resolve an alias to its command. #### Parameters This function has no parameters.
diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md index 790aeee..53b1db6 100644 --- a/docs/api/hilbish/hilbish.completions.md +++ b/docs/api/hilbish/hilbish.completions.md @@ -26,10 +26,10 @@ hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), -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. +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.
@@ -42,8 +42,8 @@ hilbish.completions.handler(line, pos) -The handler function is the callback for tab completion in Hilbish. -You can check the completions doc for more info. +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.
@@ -56,7 +56,7 @@ hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string) -Returns binary/executale completion candidates based on the provided query. +Returns binary/executale completion candidates based on the provided query. #### Parameters This function has no parameters.
@@ -69,7 +69,7 @@ hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string -Returns file completion candidates based on the provided query. +Returns file completion candidates based on the provided query. #### Parameters This function has no parameters.
diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 3ded67a..52e6dfc 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -28,7 +28,7 @@ hilbish.editor.getLine() -> string -Returns the current input line. +Returns the current input line. #### Parameters This function has no parameters.
@@ -41,7 +41,7 @@ hilbish.editor.getVimRegister(register) -> string -Returns the text that is at the register. +Returns the text that is at the register. #### Parameters This function has no parameters.
@@ -54,7 +54,7 @@ hilbish.editor.insert(text) -Inserts text into the line. +Inserts text into the line. #### Parameters This function has no parameters.
@@ -67,8 +67,8 @@ hilbish.editor.getChar() -> string -Reads a keystroke from the user. This is in a format -of something like Ctrl-L.. +Reads a keystroke from the user. This is in a format +of something like Ctrl-L.. #### Parameters This function has no parameters.
@@ -81,7 +81,7 @@ hilbish.editor.setVimRegister(register, text) -Sets the vim register at `register` to hold the passed text. +Sets the vim register at `register` to hold the passed text. #### Parameters This function has no parameters.
diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 3d9b856..802ea42 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -29,7 +29,7 @@ hilbish.history.add(cmd) -Adds a command to the history. +Adds a command to the history. #### Parameters This function has no parameters. @@ -42,7 +42,7 @@ hilbish.history.all() -> table -Retrieves all history. +Retrieves all history. #### Parameters This function has no parameters. @@ -55,7 +55,7 @@ hilbish.history.clear() -Deletes all commands from the history. +Deletes all commands from the history. #### Parameters This function has no parameters. @@ -68,7 +68,7 @@ hilbish.history.get(idx) -Retrieves a command from the history based on the `idx`. +Retrieves a command from the history based on the `idx`. #### Parameters This function has no parameters. @@ -81,7 +81,7 @@ hilbish.history.size() -> number -Returns the amount of commands in the history. +Returns the amount of commands in the history. #### Parameters This function has no parameters. diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index bb1af1e..a640726 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -31,7 +31,7 @@ hilbish.jobs.add(cmdstr, args, execPath) -Adds a new job to the job table. Note that this does not immediately run it. +Adds a new job to the job table. Note that this does not immediately run it. #### Parameters This function has no parameters. @@ -44,7 +44,7 @@ hilbish.jobs.all() -> table\< -Get a job object via its ID. +Get a job object via its ID. #### Parameters This function has no parameters. @@ -83,7 +83,7 @@ hilbish.jobs.last() -> -Returns the last added job from the table. +Returns the last added job from the table. #### Parameters This function has no parameters. diff --git a/docs/api/hilbish/hilbish.module.md b/docs/api/hilbish/hilbish.module.md index 9a0af12..7a000c1 100644 --- a/docs/api/hilbish/hilbish.module.md +++ b/docs/api/hilbish/hilbish.module.md @@ -61,8 +61,8 @@ hilbish.module.load(path) -Loads a module at the designated `path`. -It will throw if any error occurs. +Loads a module at the designated `path`. +It will throw if any error occurs. #### Parameters This function has no parameters. diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 5528195..c3e2c19 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -29,10 +29,10 @@ hilbish.runner.setMode(cb) -This is the same as the `hilbish.runnerMode` function. It takes a callback, -which will be used to execute all interactive input. -In normal cases, neither callbacks should be overrided by the user, -as the higher level functions listed below this will handle it. +This is the same as the `hilbish.runnerMode` function. It takes a callback, +which will be used to execute all interactive input. +In normal cases, neither callbacks should be overrided by the user, +as the higher level functions listed below this will handle it. #### Parameters This function has no parameters. @@ -45,8 +45,8 @@ hilbish.runner.lua(cmd) -Evaluates `cmd` as Lua input. This is the same as using `dofile` -or `load`, but is appropriated for the runner interface. +Evaluates `cmd` as Lua input. This is the same as using `dofile` +or `load`, but is appropriated for the runner interface. #### Parameters This function has no parameters. @@ -59,8 +59,8 @@ hilbish.runner.sh(cmd) -Runs a command in Hilbish's shell script interpreter. -This is the equivalent of using `source`. +Runs a command in Hilbish's shell script interpreter. +This is the equivalent of using `source`. #### Parameters This function has no parameters. diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index dae7782..3c0fadb 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -50,8 +50,8 @@ hilbish.timers.create(type, time, callback) -> -Retrieves a timer via its ID. +Retrieves a timer via its ID. #### Parameters This function has no parameters. diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 4977e97..6e72d84 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -26,7 +26,7 @@ terminal.restoreState() -Restores the last saved state of the terminal +Restores the last saved state of the terminal #### Parameters This function has no parameters. @@ -39,7 +39,7 @@ terminal.saveState() -Saves the current state of the terminal +Saves the current state of the terminal #### Parameters This function has no parameters. @@ -52,7 +52,7 @@ terminal.setRaw() -Puts the terminal in raw mode +Puts the terminal in raw mode #### Parameters This function has no parameters. @@ -65,8 +65,8 @@ 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 +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 #### Parameters This function has no parameters. diff --git a/emmyLuaDocs/fs.lua b/emmyLuaDocs/fs.lua index e974ab9..6efc2eb 100644 --- a/emmyLuaDocs/fs.lua +++ b/emmyLuaDocs/fs.lua @@ -2,56 +2,51 @@ local fs = {} ---- Gives an absolute version of `path`. ---- @param path string ---- @returns string +--- Returns an absolute version of the `path`. +--- This can be used to resolve short paths like `..` to `/home/user`. function fs.abs(path) end ---- Gives the basename of `path`. For the rules, ---- see Go's filepath.Base ---- @returns string +--- Returns the "basename," or the last part of the provided `path`. If path is empty, +--- `.` will be returned. function fs.basename(path) end ---- Changes directory to `dir` ---- @param dir string +--- Changes Hilbish's directory to `dir`. function fs.cd(dir) end ---- Returns the directory part of `path`. For the rules, see Go's ---- filepath.Dir ---- @param path string ---- @returns string +--- Returns the directory part of `path`. If a file path like +--- `~/Documents/doc.txt` then this function will return `~/Documents`. function fs.dir(path) end ---- Glob all files and directories that match the pattern. ---- For the rules, see Go's filepath.Glob ---- @param pattern string ---- @returns table +--- Match all files based on the provided `pattern`. +--- For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match +--- +--- function fs.glob(pattern) end ---- Takes paths and joins them together with the OS's ---- directory separator (forward or backward slash). ---- @vararg string ---- @returns string -function fs.join(...) end +--- Takes any list of paths and joins them based on the operating system's path separator. +--- +--- +function fs.join(...path) end ---- Makes a directory called `name`. If `recursive` is true, it will create its parent directories. ---- @param name string ---- @param recursive boolean +--- Creates a new directory with the provided `name`. +--- With `recursive`, mkdir will create parent directories. +--- +--- -- This will create the directory foo, then create the directory bar in the +--- -- foo directory. If recursive is false in this case, it will fail. +--- fs.mkdir('./foo/bar', true) function fs.mkdir(name, recursive) end ---- Returns a table of files in `dir`. ---- @param dir string ---- @return table -function fs.readdir(dir) end +--- Returns a list of all files and directories in the provided path. +function fs.readdir(path) end ---- Returns a table of info about the `path`. ---- It contains the following keys: +--- Returns the information about a given `path`. +--- The returned table contains the following values: --- name (string) - Name of the path ---- size (number) - Size of the path ---- mode (string) - Permission mode in an octal format string (with leading 0) +--- size (number) - Size of the path in bytes +--- mode (string) - Unix permission mode in an octal format string (with leading 0) --- isDir (boolean) - If the path is a directory ---- @param path string ---- @returns table +--- +--- function fs.stat(path) end return fs From 1f7f8e5104dd2d8019ce3ded191ac8999f45ac93 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 10:49:50 -0400 Subject: [PATCH 23/26] docs: update api docs, make others show up on site --- api.go | 32 +++++++++++++++++++++++----- docs/api/_index.md | 2 +- docs/api/hilbish/_index.md | 43 ++++++++++++++++++++++++++++++++------ docs/completions.md | 9 ++++++++ docs/jobs.md | 9 ++++++++ docs/lunacolors.md | 7 +++++++ docs/nature/_index.md | 7 +++++++ docs/vim-mode/_index.md | 7 +++++++ docs/vim-mode/actions.md | 9 ++++++++ emmyLuaDocs/hilbish.lua | 11 +++++----- 10 files changed, 119 insertions(+), 17 deletions(-) diff --git a/api.go b/api.go index b7afb3d..71a4b7b 100644 --- a/api.go +++ b/api.go @@ -336,9 +336,19 @@ func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // alias(cmd, orig) -// Sets an alias of `cmd` to `orig` -// --- @param cmd string -// --- @param orig string +// Sets an alias, with a name of `cmd` to another command. +// #param cmd string Name of the alias +// #param orig string Command that will be aliased +/* +#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 @@ -358,8 +368,20 @@ func hlalias(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // appendPath(dir) -// Appends `dir` to $PATH -// --- @param dir string|table +// Appends the provided dir to the command path (`$PATH`) +// #param dir string|table Directory (or directories) to append to path +/* +#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 diff --git a/docs/api/_index.md b/docs/api/_index.md index 8c9f722..f34539e 100644 --- a/docs/api/_index.md +++ b/docs/api/_index.md @@ -1,7 +1,7 @@ --- title: API layout: doc -weight: -50 +weight: -100 menu: docs --- diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 8278376..8eded6b 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -14,8 +14,8 @@ interfaces and functions which directly relate to shell functionality. ## Functions ||| |----|----| -|alias(cmd, orig)|Sets an alias of `cmd` to `orig`| -|appendPath(dir)|Appends `dir` to $PATH| +|alias(cmd, orig)|Sets an alias, with a name of `cmd` to another command.| +|appendPath(dir)|Appends the provided dir to the command path (`$PATH`)| |complete(scope, cb)|Registers a completion handler for `scope`.| |cwd() -> string|Returns the current directory of the shell| |exec(cmd)|Replaces running hilbish with `cmd`| @@ -54,9 +54,25 @@ hilbish.alias(cmd, orig) -Sets an alias of `cmd` to `orig` +Sets an alias, with a name of `cmd` to another command. + + #### Parameters -This function has no parameters. +`string` **`cmd`** +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). +````
@@ -67,9 +83,24 @@ hilbish.appendPath(dir) -Appends `dir` to $PATH +Appends the provided dir to the command path (`$PATH`) + + #### Parameters -This function has no parameters. +`string|table` **`dir`** +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' +} +````
diff --git a/docs/completions.md b/docs/completions.md index c2de27a..0ea60c2 100644 --- a/docs/completions.md +++ b/docs/completions.md @@ -1,3 +1,12 @@ +--- +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. diff --git a/docs/jobs.md b/docs/jobs.md index a5fee9c..59f2113 100644 --- a/docs/jobs.md +++ b/docs/jobs.md @@ -1,3 +1,12 @@ +--- +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. diff --git a/docs/lunacolors.md b/docs/lunacolors.md index e122fef..bde809c 100644 --- a/docs/lunacolors.md +++ b/docs/lunacolors.md @@ -1,3 +1,10 @@ +--- +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. diff --git a/docs/nature/_index.md b/docs/nature/_index.md index 53df6ca..460d6a3 100644 --- a/docs/nature/_index.md +++ b/docs/nature/_index.md @@ -1,3 +1,10 @@ +--- +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 diff --git a/docs/vim-mode/_index.md b/docs/vim-mode/_index.md index a30fe74..bda01e9 100644 --- a/docs/vim-mode/_index.md +++ b/docs/vim-mode/_index.md @@ -1,3 +1,10 @@ +--- +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`). diff --git a/docs/vim-mode/actions.md b/docs/vim-mode/actions.md index 9dfb7b2..9757827 100644 --- a/docs/vim-mode/actions.md +++ b/docs/vim-mode/actions.md @@ -1,3 +1,12 @@ +--- +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. diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index 2ee93ed..ea30efd 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -49,13 +49,14 @@ function hilbish.editor.getChar() end --- @param text string function hilbish.editor.setVimRegister(register, text) end ---- Sets an alias of `cmd` to `orig` ---- @param cmd string ---- @param orig string +--- Sets an alias, with a name of `cmd` to another command. +--- +--- function hilbish.alias(cmd, orig) end ---- Appends `dir` to $PATH ---- @param dir string|table +--- Appends the provided dir to the command path (`$PATH`) +--- +--- function hilbish.appendPath(dir) end --- Registers a completion handler for `scope`. From 93c0645d124a8ad5435202630357c25c1f2541aa Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 13:03:19 -0400 Subject: [PATCH 24/26] docs: update hilbish.completion --- complete.go | 123 +++++++++++++------- docs/api/hilbish/hilbish.completion.md | 145 ++++++++++++++++++++++++ docs/api/hilbish/hilbish.completions.md | 76 ------------- emmyLuaDocs/hilbish.lua | 42 +++---- 4 files changed, 243 insertions(+), 143 deletions(-) create mode 100644 docs/api/hilbish/hilbish.completion.md delete mode 100644 docs/api/hilbish/hilbish.completions.md diff --git a/complete.go b/complete.go index 0c70e07..faf6371 100644 --- a/complete.go +++ b/complete.go @@ -188,14 +188,14 @@ func escapeFilename(fname string) string { return escapeReplaer.Replace(fname) } -// #interface completions +// #interface completion // tab completions // The completions interface deals with tab completions. func completionLoader(rtm *rt.Runtime) *rt.Table { exports := map[string]util.LuaExport{ - "files": {luaFileComplete, 3, false}, "bins": {luaBinaryComplete, 3, false}, "call": {callLuaCompleter, 4, false}, + "files": {luaFileComplete, 3, false}, "handler": {completionHandler, 2, false}, } @@ -205,26 +205,58 @@ func completionLoader(rtm *rt.Runtime) *rt.Table { return mod } -// #interface completions -// handler(line, pos) -// 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 -func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - return c.Next(), nil +// #interface completion +// bins(query, ctx, fields) -> entries (table), prefix (string) +// Return binaries/executables based on the provided parameters. +// This function is meant to be used as a helper in a command completion handler. +// #param query string +// #param ctx string +// #param fields table +/* +#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 luaBinaryComplete(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` 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 +// 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. +// #param name string +// #param query string +// #param ctx string +// #param fields table func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(4); err != nil { return nil, err @@ -265,12 +297,13 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return cont, nil } -// #interface completions +// #interface completion // files(query, ctx, fields) -> entries (table), prefix (string) -// Returns file completion candidates based on the provided query. -// --- @param query string -// --- @param ctx string -// --- @param fields table +// Returns file matches based on the provided parameters. +// This function is meant to be used as a helper in a command completion handler. +// #param query string +// #param ctx string +// #param fields table func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { query, ctx, fds, err := getCompleteParams(t, c) if err != nil { @@ -287,28 +320,32 @@ func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil } -// #interface completions -// bins(query, ctx, fields) -> entries (table), prefix (string) -// Returns binary/executale completion candidates based on the provided query. -// --- @param query string -// --- @param ctx string -// --- @param fields table -func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { - query, ctx, fds, err := getCompleteParams(t, c) - if err != nil { - return nil, err - } +// #interface completion +// handler(line, pos) +// 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. +// #param line string The current Hilbish command line +// #param pos number Numerical position of the cursor +/* +#example +-- stripped down version of the default implementation +function hilbish.completion.handler(line, pos) + local query = fields[#fields] - 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 + if #fields == 1 then + -- call bins handler here + else + -- call command completer or files completer here + end +end +#example +*/ +func completionHandler(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 diff --git a/docs/api/hilbish/hilbish.completion.md b/docs/api/hilbish/hilbish.completion.md new file mode 100644 index 0000000..cf2477b --- /dev/null +++ b/docs/api/hilbish/hilbish.completion.md @@ -0,0 +1,145 @@ +--- +title: Module hilbish.completion +description: tab completions +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction +The completions interface deals with tab completions. + +## Functions +||| +|----|----| +|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`| +|handler(line, pos)|This function contains the general completion handler for Hilbish. This function handles| +|bins(query, ctx, fields) -> entries (table), prefix (string)|Return binaries/executables based on the provided parameters.| +|files(query, ctx, fields) -> entries (table), prefix (string)|Returns file matches based on the provided parameters.| + +
+

+hilbish.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` +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`** + + +
+ +
+

+hilbish.completion.handler(line, pos) + + + +

+ +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 +```` +
+ +
+

+hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string) + + + +

+ +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) +```` +
+ +
+

+hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string) + + + +

+ +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`** + + +
+ diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md deleted file mode 100644 index 53b1db6..0000000 --- a/docs/api/hilbish/hilbish.completions.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Module hilbish.completions -description: tab completions -layout: doc -menu: - docs: - parent: "API" ---- - -## Introduction -The completions interface deals with tab completions. - -## Functions -||| -|----|----| -|call(name, query, ctx, fields) -> completionGroups (table), prefix (string)|Calls a completer function. This is mainly used to call| -|handler(line, pos)|The handler function is the callback for tab completion in Hilbish.| -|bins(query, ctx, fields) -> entries (table), prefix (string)|Returns binary/executale completion candidates based on the provided query.| -|files(query, ctx, fields) -> entries (table), prefix (string)|Returns file completion candidates based on the provided query.| - -
-

-hilbish.completions.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` 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. -
- -
-

-hilbish.completions.handler(line, pos) - - - -

- -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. -
- -
-

-hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string) - - - -

- -Returns binary/executale completion candidates based on the provided query. -#### Parameters -This function has no parameters. -
- -
-

-hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string) - - - -

- -Returns file completion candidates based on the provided query. -#### Parameters -This function has no parameters. -
- diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index ea30efd..fe258b2 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -14,21 +14,17 @@ 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 +--- 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 ---- 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 +--- 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 --- Returns the current input line. function hilbish.editor.getLine() end @@ -172,17 +168,15 @@ 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 +--- Return binaries/executables based on the provided parameters. +--- This function is meant to be used as a helper in a command completion handler. +--- +--- +function hilbish.completion.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 +--- 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 --- Puts a job in the foreground. This will cause it to run like it was --- executed normally and wait for it to complete. From 7cd1170e41b572ab522a69c7ed9c312275ba0afe Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 2 Dec 2023 13:06:42 -0400 Subject: [PATCH 25/26] chore: reorder hilbish.completion functions --- complete.go | 16 +-- docs/api/hilbish/hilbish.completion.md | 132 ++++++++++++------------- emmyLuaDocs/hilbish.lua | 44 ++++----- 3 files changed, 96 insertions(+), 96 deletions(-) diff --git a/complete.go b/complete.go index faf6371..e3aad91 100644 --- a/complete.go +++ b/complete.go @@ -193,10 +193,10 @@ func escapeFilename(fname string) string { // The completions interface deals with tab completions. func completionLoader(rtm *rt.Runtime) *rt.Table { exports := map[string]util.LuaExport{ - "bins": {luaBinaryComplete, 3, false}, - "call": {callLuaCompleter, 4, false}, - "files": {luaFileComplete, 3, false}, - "handler": {completionHandler, 2, false}, + "bins": {hcmpBins, 3, false}, + "call": {hcmpCall, 4, false}, + "files": {hcmpFiles, 3, false}, + "handler": {hcmpHandler, 2, false}, } mod := rt.NewTable() @@ -231,7 +231,7 @@ hilbish.complete('command.sudo', function(query, ctx, fields) end) #example */ -func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { +func hcmpBins(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { query, ctx, fds, err := getCompleteParams(t, c) if err != nil { return nil, err @@ -257,7 +257,7 @@ func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #param query string // #param ctx string // #param fields table -func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { +func hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(4); err != nil { return nil, err } @@ -304,7 +304,7 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #param query string // #param ctx string // #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 @@ -341,7 +341,7 @@ function hilbish.completion.handler(line, pos) end #example */ -func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { +func hcmpHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } diff --git a/docs/api/hilbish/hilbish.completion.md b/docs/api/hilbish/hilbish.completion.md index cf2477b..7379719 100644 --- a/docs/api/hilbish/hilbish.completion.md +++ b/docs/api/hilbish/hilbish.completion.md @@ -13,10 +13,52 @@ The completions interface deals with tab completions. ## Functions ||| |----|----| -|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`| -|handler(line, pos)|This function contains the general completion handler for Hilbish. This function handles| |bins(query, ctx, fields) -> entries (table), prefix (string)|Return binaries/executables based on the provided parameters.| +|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`| |files(query, ctx, fields) -> entries (table), prefix (string)|Returns file matches based on the provided parameters.| +|handler(line, pos)|This function contains the general completion handler for Hilbish. This function handles| + +
+

+hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string) + + + +

+ +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) +```` +

@@ -42,6 +84,28 @@ You can check the Completions doc or `doc completions` for info on the `completi `table` **`fields`** +

+ +
+

+hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string) + + + +

+ +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`** + +
@@ -79,67 +143,3 @@ end ````
-
-

-hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string) - - - -

- -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) -```` -
- -
-

-hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string) - - - -

- -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`** - - -
- diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index fe258b2..f6d58a4 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -14,18 +14,6 @@ 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 the Completions doc or `doc completions` for info on the `completionGroups` return value. -function hilbish.completion.call(name, 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 - --- Returns the current input line. function hilbish.editor.getLine() end @@ -45,6 +33,28 @@ function hilbish.editor.getChar() end --- @param text string function hilbish.editor.setVimRegister(register, text) end +--- Return binaries/executables based on the provided parameters. +--- This function is meant to be used as a helper in a command completion handler. +--- +--- +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. --- --- @@ -168,16 +178,6 @@ 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 ---- Return binaries/executables based on the provided parameters. ---- This function is meant to be used as a helper in a command completion handler. ---- ---- -function hilbish.completion.bins(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 - --- 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 From 90ef8f7a9c87c9710c54e0c82fe425c6fcb8db2e Mon Sep 17 00:00:00 2001 From: sammyette Date: Sun, 3 Dec 2023 20:54:00 -0400 Subject: [PATCH 26/26] refactor: update documentation for everything --- aliases.go | 24 ++-- api.go | 135 ++++++++++++-------- docs/api/hilbish/_index.md | 189 ++++++++++++++++++++-------- docs/api/hilbish/hilbish.aliases.md | 31 +++-- docs/api/hilbish/hilbish.editor.md | 21 ++-- docs/api/hilbish/hilbish.history.md | 18 +-- docs/api/hilbish/hilbish.jobs.md | 37 ++++-- docs/api/hilbish/hilbish.module.md | 4 +- docs/api/hilbish/hilbish.os.md | 7 +- docs/api/hilbish/hilbish.runner.md | 18 ++- docs/api/hilbish/hilbish.timers.md | 27 ++-- docs/api/terminal.md | 10 +- docs/runner-mode.md | 51 ++++---- editor.go | 13 +- emmyLuaDocs/hilbish.lua | 138 +++++++------------- emmyLuaDocs/terminal.lua | 6 +- golibs/terminal/terminal.go | 6 +- job.go | 26 ++-- module.go | 1 + os.go | 7 +- rl.go | 14 +-- runnermode.go | 10 +- timerhandler.go | 22 ++-- website/config.toml | 1 + 24 files changed, 480 insertions(+), 336 deletions(-) diff --git a/aliases.go b/aliases.go index 8b815b3..8c90fe5 100644 --- a/aliases.go +++ b/aliases.go @@ -111,15 +111,23 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table { // #interface aliases // add(alias, cmd) -// This is an alias (ha) for the `hilbish.alias` function. +// This is an alias (ha) for the [hilbish.alias](../#alias) function. // --- @param alias string // --- @param cmd string func _hlalias() {} // #interface aliases -// list() -> table +// list() -> table[string, string] // Get a table of all aliases, with string keys as the alias and the value as the command. -// --- @returns table +// #returns table[string, string] +/* +#example +hilbish.aliases.add('hi', 'echo hi') + +local aliases = hilbish.aliases.list() +-- -> {hi = 'echo hi'} +#example +*/ func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { aliasesList := rt.NewTable() for k, v := range a.All() { @@ -132,7 +140,7 @@ func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface aliases // delete(name) // Removes an alias. -// --- @param name string +// #param name string func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -147,10 +155,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // #interface aliases -// resolve(alias) -> command (string) -// Tries to resolve an alias to its command. -// --- @param alias string -// --- @returns string +// resolve(alias) -> string? +// Resolves an alias to its original command. Will thrown an error if the alias doesn't exist. +// #param alias string +// #returns string func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err diff --git a/api.go b/api.go index 71a4b7b..b4c4496 100644 --- a/api.go +++ b/api.go @@ -190,12 +190,10 @@ func unsetVimMode() { } // run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) -// 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 -// --- @param returnOut boolean -// --- @returns number, string, string +// Runs `cmd` in Hilbish's shell script interpreter. +// #param cmd string +// #param returnOut boolean If this is true, the function will return the standard output and error of the command instead of printing it. +// #returns number, string, string func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -238,7 +236,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // cwd() -> string // Returns the current directory of the shell -// --- @returns string +// #returns string func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { cwd, _ := os.Getwd() @@ -249,9 +247,9 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // read(prompt) -> input (string) // 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 -// --- @returns string|nil +// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen). +// #param prompt? string +// #returns string|nil func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { luaprompt := c.Arg(0) if typ := luaprompt.Type(); typ != rt.StringType && typ != rt.NilType { @@ -279,14 +277,21 @@ func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { /* prompt(str, typ) -Changes the shell prompt to `str` +Changes the shell prompt to the provided string. 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. +#param str string +#param typ? string Type of prompt, being left or right. Left by default. +#example +-- the default hilbish prompt without color +hilbish.prompt '%u %d ∆' +-- or something of old: +hilbish.prompt '%u@%h :%d $' +-- prompt: user@hostname: ~/directory $ +#example */ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { err := c.Check1Arg() @@ -320,8 +325,28 @@ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // multiprompt(str) -// Changes the continued line prompt to `str` -// --- @param str string +// Changes the text prompt when Hilbish asks for more input. +// This will show up when text is incomplete, like a missing quote +// #param str string +/* +#example +--[[ +imagine this is your text input: +user ~ ∆ echo "hey + +but there's a missing quote! hilbish will now prompt you so the terminal +will look like: +user ~ ∆ echo "hey +--> ...!" + +so then you get +user ~ ∆ echo "hey +--> ...!" +hey ...! +]]-- +hilbish.multiprompt '-->' +#example +*/ func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -415,8 +440,9 @@ func appendPath(dir string) { } // exec(cmd) -// Replaces running hilbish with `cmd` -// --- @param cmd string +// Replaces the currently running Hilbish instance with the supplied command. +// This can be used to do an in-place restart. +// #param cmd string func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -450,8 +476,10 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // goro(fn) -// Puts `fn` in a goroutine -// --- @param fn function +// Puts `fn` in a Goroutine. +// This can be used to run any function in another thread. +// **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** +// #param fn function func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -474,10 +502,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // timeout(cb, time) -> @Timer // Runs the `cb` function after `time` in milliseconds. -// This creates a timer that starts immediately. -// --- @param cb function -// --- @param time number -// --- @returns Timer +// This creates a Timer that starts immediately. +// #param cb function +// #param time number +// #returns Timer func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(2); err != nil { return nil, err @@ -501,9 +529,9 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // interval(cb, time) -> @Timer // Runs the `cb` function every `time` milliseconds. // This creates a timer that starts immediately. -// --- @param cb function -// --- @param time number -// --- @return Timer +// #param cb function +// #param time number +// #return Timer func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(2); err != nil { return nil, err @@ -525,13 +553,13 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // complete(scope, cb) -// Registers a completion handler for `scope`. +// Registers a completion handler for the specified 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 +// The documentation for completions, under Features/Completions or `doc completions` +// provides more details. +// #param scope string +// #param cb function func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { scope, cb, err := util.HandleStrCallback(t, c) if err != nil { @@ -543,8 +571,8 @@ func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // prependPath(dir) -// Prepends `dir` to $PATH -// --- @param dir string +// Prepends `dir` to $PATH. +// #param dir string func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -567,8 +595,8 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // which(name) -> string // Checks if `name` is a valid command. // Will return the path of the binary, or a basename if it's a commander. -// --- @param name string -// --- @returns string +// #param name string +// #returns string func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -598,8 +626,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // inputMode(mode) -// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim -// --- @param mode string +// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim. +// `emacs` is the default. Setting it to `vim` changes behavior of input to be +// Vim-like with modes and Vim keybinds. +// #param mode string func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -629,7 +659,7 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // 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 +// #param mode string|function func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -655,26 +685,33 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // 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 number +// #param line string +// #param pos number +/* +#example +-- this will display "hi" after the cursor in a dimmed color. +function hilbish.hinter(line, pos) + return 'hi' +end +#example +*/ func hlhinter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } // 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. +// 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. // Note that to set a highlighter, one has to override this function. -// Example: -// ``` +// #example +// --This code will highlight all double quoted strings in green. // function hilbish.highlighter(line) // return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) // end -// ``` -// This code will highlight all double quoted strings in green. -// --- @param line string +// #example +// #param line string func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.Next(), nil } diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 8eded6b..aba1c6f 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -16,19 +16,19 @@ interfaces and functions which directly relate to shell functionality. |----|----| |alias(cmd, orig)|Sets an alias, with a name of `cmd` to another command.| |appendPath(dir)|Appends the provided dir to the command path (`$PATH`)| -|complete(scope, cb)|Registers a completion handler for `scope`.| +|complete(scope, cb)|Registers a completion handler for the specified scope.| |cwd() -> string|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| +|exec(cmd)|Replaces the currently running Hilbish instance with the supplied command.| +|goro(fn)|Puts `fn` in a Goroutine.| +|highlighter(line)|Line highlighter handler.| |hinter(line, pos)|The command line hint handler. It gets called on every key insert to| -|inputMode(mode)|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim| +|inputMode(mode)|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.| |interval(cb, time) -> @Timer|Runs the `cb` function every `time` milliseconds.| -|multiprompt(str)|Changes the continued line prompt to `str`| -|prependPath(dir)|Prepends `dir` to $PATH| -|prompt(str, typ)|Changes the shell prompt to `str`| +|multiprompt(str)|Changes the text prompt when Hilbish asks for more input.| +|prependPath(dir)|Prepends `dir` to $PATH.| +|prompt(str, typ)|Changes the shell prompt to the provided string.| |read(prompt) -> input (string)|Read input from the user, using Hilbish's line editor/input reader.| -|run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)|Runs `cmd` in Hilbish's sh interpreter.| +|run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)|Runs `cmd` in Hilbish's shell script interpreter.| |runnerMode(mode)|Sets the execution/runner mode for interactive Hilbish. This determines whether| |timeout(cb, time) -> @Timer|Runs the `cb` function after `time` in milliseconds.| |which(name) -> string|Checks if `name` is a valid command.| @@ -111,13 +111,18 @@ hilbish.complete(scope, cb) -Registers a completion handler for `scope`. +Registers a completion handler for the specified 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. +The documentation for completions, under Features/Completions or `doc completions` +provides more details. #### Parameters -This function has no parameters. +`string` **`scope`** + + +`function` **`cb`** + +
@@ -141,9 +146,12 @@ hilbish.exec(cmd) -Replaces running hilbish with `cmd` +Replaces the currently running Hilbish instance with the supplied command. +This can be used to do an in-place restart. #### Parameters -This function has no parameters. +`string` **`cmd`** + +
@@ -154,9 +162,13 @@ hilbish.goro(fn) -Puts `fn` in a goroutine +Puts `fn` in a Goroutine. +This can be used to run any function in another thread. +**NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** #### Parameters -This function has no parameters. +`function` **`fn`** + +
@@ -167,20 +179,23 @@ hilbish.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. +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. Note that to set a highlighter, one has to override this function. -Example: -``` -function hilbish.highlighter(line) - return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) -end -``` -This code will highlight all double quoted strings in green. + #### Parameters -This function has no parameters. +`string` **`line`** + + +#### Example +```lua +--This code will highlight all double quoted strings in green. +function hilbish.highlighter(line) + return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) +end +````
@@ -196,8 +211,22 @@ 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. + + #### Parameters -This function has no parameters. +`string` **`line`** + + +`number` **`pos`** + + +#### Example +```lua +-- this will display "hi" after the cursor in a dimmed color. +function hilbish.hinter(line, pos) + return 'hi' +end +````
@@ -208,9 +237,13 @@ hilbish.inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim +Sets the input mode for Hilbish's line reader. Accepts either emacs or vim. +`emacs` is the default. Setting it to `vim` changes behavior of input to be +Vim-like with modes and Vim keybinds. #### Parameters -This function has no parameters. +`string` **`mode`** + +
@@ -248,9 +309,11 @@ hilbish.prependPath(dir) -Prepends `dir` to $PATH +Prepends `dir` to $PATH. #### Parameters -This function has no parameters. +`string` **`dir`** + +
@@ -261,14 +324,28 @@ hilbish.prompt(str, typ) -Changes the shell prompt to `str` +Changes the shell prompt to the provided string. 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 + #### Parameters -This function has no parameters. +`string` **`str`** + + +`string` **`typ?`** +Type of prompt, being left or right. Left by default. + +#### Example +```lua +-- the default hilbish prompt without color +hilbish.prompt '%u %d ∆' +-- or something of old: +hilbish.prompt '%u@%h :%d $' +-- prompt: user@hostname: ~/directory $ +````
@@ -281,9 +358,11 @@ hilbish.read(prompt) -> input (string) 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) +Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen). #### Parameters -This function has no parameters. +`string` **`prompt?`** + +
@@ -294,11 +373,14 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin -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. +Runs `cmd` in Hilbish's shell script interpreter. #### Parameters -This function has no parameters. +`string` **`cmd`** + + +`boolean` **`returnOut`** +If this is true, the function will return the standard output and error of the command instead of printing it. +
@@ -315,7 +397,9 @@ 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. #### Parameters -This function has no parameters. +`string|function` **`mode`** + +
@@ -327,9 +411,14 @@ hilbish.timeout(cb, time) -> add(alias, cmd)|This is an alias (ha) for the `hilbish.alias` function.| +|add(alias, cmd)|This is an alias (ha) for the [hilbish.alias](../#alias) function.| |delete(name)|Removes an alias.| -|list() -> table|Get a table of all aliases, with string keys as the alias and the value as the command.| -|resolve(alias) -> command (string)|Tries to resolve an alias to its command.| +|list() -> table[string, string]|Get a table of all aliases, with string keys as the alias and the value as the command.| +|resolve(alias) -> string?|Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.|

@@ -26,7 +26,7 @@ hilbish.aliases.add(alias, cmd)

-This is an alias (ha) for the `hilbish.alias` function. +This is an alias (ha) for the [hilbish.alias](../#alias) function. #### Parameters This function has no parameters.
@@ -41,32 +41,45 @@ hilbish.aliases.delete(name) Removes an alias. #### Parameters -This function has no parameters. +`string` **`name`** + +

-hilbish.aliases.list() -> table\ +hilbish.aliases.list() -> table[string, string]

Get a table of all aliases, with string keys as the alias and the value as the command. + + #### Parameters This function has no parameters. +#### Example +```lua +hilbish.aliases.add('hi', 'echo hi') + +local aliases = hilbish.aliases.list() +-- -> {hi = 'echo hi'} +````

-hilbish.aliases.resolve(alias) -> command (string) +hilbish.aliases.resolve(alias) -> string?

-Tries to resolve an alias to its command. +Resolves an alias to its original command. Will thrown an error if the alias doesn't exist. #### Parameters -This function has no parameters. +`string` **`alias`** + +
diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 52e6dfc..040ca85 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -16,8 +16,8 @@ directly interact with the line editor in use. |----|----| |getLine() -> string|Returns the current input line.| |getVimRegister(register) -> string|Returns the text that is at the register.| -|insert(text)|Inserts text into the line.| -|getChar() -> string|Reads a keystroke from the user. This is in a format| +|insert(text)|Inserts text into the Hilbish command line.| +|getChar() -> string|Reads a keystroke from the user. This is in a format of something like Ctrl-L.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.|
@@ -43,7 +43,9 @@ hilbish.editor.getVimRegister(register) -> string Returns the text that is at the register. #### Parameters -This function has no parameters. +`string` **`register`** + +
@@ -54,9 +56,11 @@ hilbish.editor.insert(text) -Inserts text into the line. +Inserts text into the Hilbish command line. #### Parameters -This function has no parameters. +`string` **`text`** + +
@@ -67,8 +71,7 @@ hilbish.editor.getChar() -> string -Reads a keystroke from the user. This is in a format -of something like Ctrl-L.. +Reads a keystroke from the user. This is in a format of something like Ctrl-L. #### Parameters This function has no parameters.
@@ -83,6 +86,8 @@ hilbish.editor.setVimRegister(register, text) Sets the vim register at `register` to hold the passed text. #### Parameters -This function has no parameters. +`string` **`text`** + + diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 802ea42..bc1efb0 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -16,9 +16,9 @@ method of saving history. ||| |----|----| |add(cmd)|Adds a command to the history.| -|all() -> table|Retrieves all history.| +|all() -> table|Retrieves all history as a table.| |clear()|Deletes all commands from the history.| -|get(idx)|Retrieves a command from the history based on the `idx`.| +|get(index)|Retrieves a command from the history based on the `index`.| |size() -> number|Returns the amount of commands in the history.|
@@ -31,7 +31,9 @@ hilbish.history.add(cmd) Adds a command to the history. #### Parameters -This function has no parameters. +`string` **`cmd`** + +
@@ -42,7 +44,7 @@ hilbish.history.all() -> table -Retrieves all history. +Retrieves all history as a table. #### Parameters This function has no parameters.
@@ -62,15 +64,17 @@ This function has no parameters.

-hilbish.history.get(idx) +hilbish.history.get(index)

-Retrieves a command from the history based on the `idx`. +Retrieves a command from the history based on the `index`. #### Parameters -This function has no parameters. +`number` **`index`** + +
diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index a640726..6a3423f 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -17,11 +17,11 @@ interactive usage or with the functions defined below for use in external runner ## Functions ||| |----|----| -|add(cmdstr, args, execPath)|Adds a new job to the job table. Note that this does not immediately run it.| -|all() -> table<@Job>|Returns a table of all job objects.| -|disown(id)|Disowns a job. This deletes it from the job table.| +|add(cmdstr, args, execPath)|Creates a new job. This function does not run the job. This function is intended to be| +|all() -> table[@Job]|Returns a table of all job objects.| +|disown(id)|Disowns a job. This simply deletes it from the list of jobs without stopping it.| |get(id) -> @Job|Get a job object via its ID.| -|last() -> @Job|Returns the last added job from the table.| +|last() -> @Job|Returns the last added job to the table.|

@@ -31,14 +31,29 @@ hilbish.jobs.add(cmdstr, args, execPath)

-Adds a new job to the job table. Note that this does not immediately run it. +Creates a new job. This function does not run the job. This function is intended to be +used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs. + + #### Parameters -This function has no parameters. +`string` **`cmdstr`** +String that a user would write for the job + +`table` **`args`** +Arguments for the commands. Has to include the name of the command. + +`string` **`execPath`** +Binary to use to run the command. Does not + +#### Example +```lua +hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go') +````

-hilbish.jobs.all() -> table\<Job> +hilbish.jobs.all() -> table[Job] @@ -57,9 +72,11 @@ hilbish.jobs.disown(id)

-Disowns a job. This deletes it from the job table. +Disowns a job. This simply deletes it from the list of jobs without stopping it. #### Parameters -This function has no parameters. +`number` **`id`** + +
diff --git a/docs/api/hilbish/hilbish.module.md b/docs/api/hilbish/hilbish.module.md index 7a000c1..3363ca7 100644 --- a/docs/api/hilbish/hilbish.module.md +++ b/docs/api/hilbish/hilbish.module.md @@ -64,6 +64,8 @@ hilbish.module.load(path) Loads a module at the designated `path`. It will throw if any error occurs. #### Parameters -This function has no parameters. +`string` **`path`** + +
diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 7749e3d..13b56b0 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -1,6 +1,6 @@ --- title: Module hilbish.os -description: OS Info +description: operating system info layout: doc menu: docs: @@ -8,9 +8,8 @@ menu: --- ## Introduction -The `os` interface provides simple text information properties about -the current OS on the systen. This mainly includes the name and -version. +Provides simple text information properties about the current operating system. +This mainly includes the name and version. ## Static module fields ||| diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index c3e2c19..c3134ae 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -17,7 +17,7 @@ write command in Fennel. ## Functions ||| |----|----| -|setMode(cb)|This is the same as the `hilbish.runnerMode` function. It takes a callback,| +|setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| @@ -29,12 +29,14 @@ hilbish.runner.setMode(cb) -This is the same as the `hilbish.runnerMode` function. It takes a callback, -which will be used to execute all interactive input. +This is the same as the `hilbish.runnerMode` function. +It takes a callback, which will be used to execute all interactive input. In normal cases, neither callbacks should be overrided by the user, as the higher level functions listed below this will handle it. #### Parameters -This function has no parameters. +`function` **`cb`** + +
@@ -48,7 +50,9 @@ hilbish.runner.lua(cmd) Evaluates `cmd` as Lua input. This is the same as using `dofile` or `load`, but is appropriated for the runner interface. #### Parameters -This function has no parameters. +`string` **`cmd`** + +
@@ -62,6 +66,8 @@ hilbish.runner.sh(cmd) Runs a command in Hilbish's shell script interpreter. This is the equivalent of using `source`. #### Parameters -This function has no parameters. +`string` **`cmd`** + +
diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 3c0fadb..310c4dd 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -14,14 +14,10 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a timer API to set intervals and timeouts. These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc -accessible with `doc hilbish`). But if you want slightly more control over -them, there is the `hilbish.timers` interface. It allows you to get -a timer via ID and control them. - -All functions documented with the `Timer` type refer to a Timer object. +accessible with `doc hilbish`, or `Module hilbish` on the Website). An example of usage: -``` +```lua local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() print 'hello!' end) @@ -33,7 +29,7 @@ print(t.running) // true ## Functions ||| |----|----| -|create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time` in milliseconds.| +|create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time`.| |get(id) -> @Timer|Retrieves a timer via its ID.| ## Static module fields @@ -50,10 +46,17 @@ hilbish.timers.create(type, time, callback) -> ## Types diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 6e72d84..19eb0eb 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -14,8 +14,8 @@ The terminal library is a simple and lower level library for certain terminal in ||| |----|----| |restoreState()|Restores the last saved state of the terminal| -|saveState()|Saves the current state of the terminal| -|setRaw()|Puts the terminal in raw mode| +|saveState()|Saves the current state of the terminal.| +|setRaw()|Puts the terminal into raw mode.| |size()|Gets the dimensions of the terminal. Returns a table with `width` and `height`|
@@ -39,7 +39,7 @@ terminal.saveState() -Saves the current state of the terminal +Saves the current state of the terminal. #### Parameters This function has no parameters.
@@ -52,7 +52,7 @@ terminal.setRaw() -Puts the terminal in raw mode +Puts the terminal into raw mode. #### Parameters This function has no parameters. @@ -66,7 +66,7 @@ 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 +NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal. #### Parameters This function has no parameters. diff --git a/docs/runner-mode.md b/docs/runner-mode.md index 0b5ce24..4844c27 100644 --- a/docs/runner-mode.md +++ b/docs/runner-mode.md @@ -1,7 +1,15 @@ -Hilbish is *unique,* when interactive it first attempts to run input as -Lua and then tries shell script. But if you're normal, you wouldn't -really be using Hilbish anyway but you'd also not want this -(or maybe want Lua only in some cases.) +Hilbish allows you to change how interactive text can be interpreted. +This is mainly due to the fact that the default method Hilbish uses +is that it runs Lua first and then falls back to shell script. + +In some cases, someone might want to switch to just shell script to avoid +it while interactive but still have a Lua config, or go full Lua to use +Hilbish as a REPL. This also allows users to add alternative languages like +Fennel as the interactive script runner. + +Runner mode can also be used to handle specific kinds of input before +evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh) +handles links. The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`, which determines how Hilbish will run user input. By default, this is @@ -27,12 +35,20 @@ hilbish.runnerMode(function(input) end) The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode` -and also provides the sh and Lua runner functions that Hilbish itself uses. -A runner function is expected to return 3 values: the input, exit code, and an error. -The input return is there incase you need to prompt for more input. -If you don't, just return the input passed to the runner function. -The exit code has to be a number, it will be 0 otherwise and the error can be -`nil` to indicate no error. +and also provides the shell script and Lua runner functions that Hilbish itself uses. + +A runner function is expected to return a table with the following values: +- `exitCode` (number): Exit code of the command +- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case +more is requested. +- `err` (string): A string that represents an error from the runner. +This should only be set when, for example, there is a syntax error. +It can be set to a few special values for Hilbish to throw the right +hooks and have a better looking message. + - `: not-found` will throw a `command.not-found` hook + based on what `` is. + - `: not-executable` will throw a `command.not-executable` hook. +- `continue` (boolean): Whether Hilbish should prompt the user for no input ## Functions These are the "low level" functions for the `hilbish.runner` interface. @@ -41,21 +57,6 @@ These are the "low level" functions for the `hilbish.runner` interface. + sh(input) -> table > Runs `input` in Hilbish's sh interpreter + lua(input) -> table > Evals `input` as Lua code -The table value that runners return can have at least 4 values: -+ input (string): The full input text. -+ exitCode (number): Exit code (usually from a command) -+ continue (boolean): Whether to prompt the user for more input -(in the case of incomplete syntax) -+ err (string): A string that represents an error from the runner. -This should only be set when, for example, there is a syntax error. -It can be set to a few special values for Hilbish to throw the right -hooks and have a better looking message. - -+ `: not-found` will throw a `command.not-found` hook -based on what `` is. -+ `: not-executable` will throw a `command.not-executable` hook. - -The others here are defined in Lua and have EmmyLua documentation. These functions should be preferred over the previous ones. + setCurrent(mode) > The same as `setMode`, but works with runners managed via the functions below. diff --git a/editor.go b/editor.go index d720a41..9c49440 100644 --- a/editor.go +++ b/editor.go @@ -27,7 +27,8 @@ func editorLoader(rtm *rt.Runtime) *rt.Table { // #interface editor // insert(text) -// Inserts text into the line. +// Inserts text into the Hilbish command line. +// #param text string func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -46,8 +47,8 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface editor // setVimRegister(register, text) // Sets the vim register at `register` to hold the passed text. -// --- @param register string -// --- @param text string +// #aram register string +// #param text string func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -71,7 +72,7 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface editor // getVimRegister(register) -> string // Returns the text that is at the register. -// --- @param register string +// #param register string func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -90,6 +91,7 @@ func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface editor // getLine() -> string // Returns the current input line. +// #returns string func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { buf := lr.rl.GetLine() @@ -98,8 +100,7 @@ func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface editor // getChar() -> string -// Reads a keystroke from the user. This is in a format -// of something like Ctrl-L.. +// Reads a keystroke from the user. This is in a format of something like Ctrl-L. func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { buf := lr.rl.ReadChar() diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index f6d58a4..8521065 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -2,35 +2,30 @@ local hilbish = {} ---- This is an alias (ha) for the `hilbish.alias` function. +--- This is an alias (ha) for the [hilbish.alias](../#alias) function. --- @param alias string --- @param cmd string function hilbish.aliases.add(alias, cmd) end ---- This is the same as the `hilbish.runnerMode` function. It takes a callback, ---- which will be used to execute all interactive input. +--- This is the same as the `hilbish.runnerMode` function. +--- It takes a callback, which will be used to execute all interactive input. --- In normal cases, neither callbacks should be overrided by the user, --- as the higher level functions listed below this will handle it. ---- @param cb function function hilbish.runner.setMode(cb) end --- Returns the current input line. function hilbish.editor.getLine() end --- Returns the text that is at the register. ---- @param register string function hilbish.editor.getVimRegister(register) end ---- Inserts text into the line. +--- Inserts text into the Hilbish command line. function hilbish.editor.insert(text) end ---- Reads a keystroke from the user. This is in a format ---- of something like Ctrl-L.. +--- Reads a keystroke from the user. This is in a format of something like Ctrl-L. function hilbish.editor.getChar() end --- Sets the vim register at `register` to hold the passed text. ---- @param register string ---- @param text string function hilbish.editor.setVimRegister(register, text) end --- Return binaries/executables based on the provided parameters. @@ -65,40 +60,31 @@ function hilbish.alias(cmd, orig) end --- function hilbish.appendPath(dir) end ---- Registers a completion handler for `scope`. +--- Registers a completion handler for the specified 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 +--- The documentation for completions, under Features/Completions or `doc completions` +--- provides more details. function hilbish.complete(scope, cb) end --- Returns the current directory of the shell ---- @returns string function hilbish.cwd() end ---- Replaces running hilbish with `cmd` ---- @param cmd string +--- Replaces the currently running Hilbish instance with the supplied command. +--- This can be used to do an in-place restart. function hilbish.exec(cmd) end ---- Puts `fn` in a goroutine ---- @param fn function +--- Puts `fn` in a Goroutine. +--- This can be used to run any function in another thread. +--- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** function hilbish.goro(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. +--- 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. --- Note that to set a highlighter, one has to override this function. ---- Example: ---- ``` ---- function hilbish.highlighter(line) ---- return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) ---- end ---- ``` ---- This code will highlight all double quoted strings in green. ---- @param line string +--- function hilbish.highlighter(line) end --- The command line hint handler. It gets called on every key insert to @@ -106,52 +92,43 @@ function hilbish.highlighter(line) end --- 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 number +--- +--- function hilbish.hinter(line, pos) end ---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim ---- @param mode string +--- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim. +--- `emacs` is the default. Setting it to `vim` changes behavior of input to be +--- Vim-like with modes and Vim keybinds. function hilbish.inputMode(mode) end --- Runs the `cb` function every `time` milliseconds. --- This creates a timer that starts immediately. ---- @param cb function ---- @param time number ---- @return Timer function hilbish.interval(cb, time) end ---- Changes the continued line prompt to `str` ---- @param str string +--- Changes the text prompt when Hilbish asks for more input. +--- This will show up when text is incomplete, like a missing quote +--- +--- function hilbish.multiprompt(str) end ---- Prepends `dir` to $PATH ---- @param dir string +--- Prepends `dir` to $PATH. function hilbish.prependPath(dir) end ---- Changes the shell prompt to `str` +--- Changes the shell prompt to the provided string. --- 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 hilbish.prompt(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 ---- @returns string|nil +--- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen). function hilbish.read(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 ---- @param returnOut boolean ---- @returns number, string, string +--- Runs `cmd` in Hilbish's shell script interpreter. function hilbish.run(cmd, returnOut) end --- Sets the execution/runner mode for interactive Hilbish. This determines whether @@ -159,20 +136,14 @@ function hilbish.run(cmd, returnOut) end --- 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 hilbish.runnerMode(mode) end --- Runs the `cb` function after `time` in milliseconds. ---- This creates a timer that starts immediately. ---- @param cb function ---- @param time number ---- @returns Timer +--- This creates a Timer that starts immediately. function hilbish.timeout(cb, time) end --- Checks if `name` is a valid command. --- Will return the path of the binary, or a basename if it's a commander. ---- @param name string ---- @returns string function hilbish.which(name) end --- Puts a job in the background. This acts the same as initially running a job. @@ -184,7 +155,6 @@ function hilbish.jobs:foreground() end --- Evaluates `cmd` as Lua input. This is the same as using `dofile` --- or `load`, but is appropriated for the runner interface. ---- @param cmd string function hilbish.runner.lua(cmd) end --- Sets/toggles the option of automatically flushing output. @@ -221,7 +191,6 @@ function hilbish.module.load(path) end --- Runs a command in Hilbish's shell script interpreter. --- This is the equivalent of using `source`. ---- @param cmd string function hilbish.runner.sh(cmd) end --- Starts a timer. @@ -231,30 +200,26 @@ function hilbish.timers:start() end function hilbish.timers:stop() end --- Removes an alias. ---- @param name string function hilbish.aliases.delete(name) end --- Get a table of all aliases, with string keys as the alias and the value as the command. ---- @returns table +--- +--- function hilbish.aliases.list() end ---- Tries to resolve an alias to its command. ---- @param alias string ---- @returns string +--- Resolves an alias to its original command. Will thrown an error if the alias doesn't exist. function hilbish.aliases.resolve(alias) end ---- Adds a new job to the job table. Note that this does not immediately run it. ---- @param cmdstr string ---- @param args table ---- @param execPath string +--- Creates a new job. This function does not run the job. This function is intended to be +--- used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs. +--- +--- function hilbish.jobs.add(cmdstr, args, execPath) end --- Returns a table of all job objects. ---- @returns table function hilbish.jobs.all() end ---- Disowns a job. This deletes it from the job table. ---- @param id number +--- Disowns a job. This simply deletes it from the list of jobs without stopping it. function hilbish.jobs.disown(id) end --- Get a job object via its ID. @@ -262,39 +227,28 @@ function hilbish.jobs.disown(id) end --- @returns Job function hilbish.jobs.get(id) end ---- Returns the last added job from the table. ---- @returns Job +--- Returns the last added job to the table. function hilbish.jobs.last() end --- Adds a command to the history. ---- @param cmd string function hilbish.history.add(cmd) end ---- Retrieves all history. ---- @returns table +--- Retrieves all history as a table. function hilbish.history.all() end --- Deletes all commands from the history. function hilbish.history.clear() end ---- Retrieves a command from the history based on the `idx`. ---- @param idx number -function hilbish.history.get(idx) end +--- Retrieves a command from the history based on the `index`. +function hilbish.history.get(index) end --- Returns the amount of commands in the history. ---- @returns number function hilbish.history.size() end ---- Creates a timer that runs based on the specified `time` in milliseconds. ---- The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` ---- @param type number ---- @param time number ---- @param callback function +--- Creates a timer that runs based on the specified `time`. function hilbish.timers.create(type, time, callback) end --- Retrieves a timer via its ID. ---- @param id number ---- @returns Timer function hilbish.timers.get(id) end return hilbish diff --git a/emmyLuaDocs/terminal.lua b/emmyLuaDocs/terminal.lua index 2266ac6..ed0b9ef 100644 --- a/emmyLuaDocs/terminal.lua +++ b/emmyLuaDocs/terminal.lua @@ -5,14 +5,14 @@ local terminal = {} --- Restores the last saved state of the terminal function terminal.restoreState() end ---- Saves the current state of the terminal +--- Saves the current state of the terminal. function terminal.saveState() end ---- Puts the terminal in raw mode +--- Puts the terminal into raw mode. function terminal.setRaw() 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 +--- NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal. function terminal.size() end return terminal diff --git a/golibs/terminal/terminal.go b/golibs/terminal/terminal.go index 2040fac..954a4dd 100644 --- a/golibs/terminal/terminal.go +++ b/golibs/terminal/terminal.go @@ -34,7 +34,7 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) { // 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 +// NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal. func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { w, h, err := term.GetSize(int(os.Stdin.Fd())) if err != nil { @@ -49,7 +49,7 @@ func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // saveState() -// Saves the current state of the terminal +// Saves the current state of the terminal. func termsaveState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { state, err := term.GetState(int(os.Stdin.Fd())) if err != nil { @@ -72,7 +72,7 @@ func termrestoreState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // setRaw() -// Puts the terminal in raw mode +// Puts the terminal into raw mode. func termsetRaw(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { _, err := term.MakeRaw(int(os.Stdin.Fd())) if err != nil { diff --git a/job.go b/job.go index 1beba9c..185ec91 100644 --- a/job.go +++ b/job.go @@ -414,10 +414,16 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface jobs // add(cmdstr, args, execPath) -// Adds a new job to the job table. Note that this does not immediately run it. -// --- @param cmdstr string -// --- @param args table -// --- @param execPath string +// Creates a new job. This function does not run the job. This function is intended to be +// used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs. +// #param cmdstr string String that a user would write for the job +// #param args table Arguments for the commands. Has to include the name of the command. +// #param execPath string Binary to use to run the command. Does not +/* +#example +hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go') +#example +*/ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(3); err != nil { return nil, err @@ -448,9 +454,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // #interface jobs -// all() -> table<@Job> +// all() -> table[@Job] // Returns a table of all job objects. -// --- @returns table +// #returns table[Job] func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { j.mu.RLock() defer j.mu.RUnlock() @@ -465,8 +471,8 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface jobs // disown(id) -// Disowns a job. This deletes it from the job table. -// --- @param id number +// Disowns a job. This simply deletes it from the list of jobs without stopping it. +// #param id number func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -486,8 +492,8 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface jobs // last() -> @Job -// Returns the last added job from the table. -// --- @returns Job +// Returns the last added job to the table. +// #returns Job func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { j.mu.RLock() defer j.mu.RUnlock() diff --git a/module.go b/module.go index 2ab55e8..bf4e32a 100644 --- a/module.go +++ b/module.go @@ -61,6 +61,7 @@ func moduleLoader(rtm *rt.Runtime) *rt.Table { // load(path) // Loads a module at the designated `path`. // It will throw if any error occurs. +// #param path string func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(1); err != nil { return nil, err diff --git a/os.go b/os.go index da9eadd..46e3d3c 100644 --- a/os.go +++ b/os.go @@ -8,10 +8,9 @@ import ( ) // #interface os -// OS Info -// The `os` interface provides simple text information properties about -// the current OS on the systen. This mainly includes the name and -// version. +// operating system info +// Provides simple text information properties about the current operating system. +// This mainly includes the name and version. // #field family Family name of the current OS // #field name Pretty name of the current OS // #field version Version of the current OS diff --git a/rl.go b/rl.go index 17ea4df..7d5ed89 100644 --- a/rl.go +++ b/rl.go @@ -267,7 +267,7 @@ func (lr *lineReader) Loader(rtm *rt.Runtime) *rt.Table { // #interface history // add(cmd) // Adds a command to the history. -// --- @param cmd string +// #param cmd string func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -284,15 +284,15 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) // #interface history // size() -> number // Returns the amount of commands in the history. -// --- @returns number +// #eturns number func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil } // #interface history -// get(idx) -// Retrieves a command from the history based on the `idx`. -// --- @param idx number +// get(index) +// Retrieves a command from the history based on the `index`. +// #param index number func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -309,8 +309,8 @@ func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) // #interface history // all() -> table -// Retrieves all history. -// --- @returns table +// Retrieves all history as a table. +// #returns table func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { tbl := rt.NewTable() size := lr.fileHist.Len() diff --git a/runnermode.go b/runnermode.go index 8e9e7b9..56a0178 100644 --- a/runnermode.go +++ b/runnermode.go @@ -28,18 +28,18 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table { // #interface runner // setMode(cb) -// This is the same as the `hilbish.runnerMode` function. It takes a callback, -// which will be used to execute all interactive input. +// This is the same as the `hilbish.runnerMode` function. +// It takes a callback, which will be used to execute all interactive input. // In normal cases, neither callbacks should be overrided by the user, // as the higher level functions listed below this will handle it. -// --- @param cb function +// #param cb function func _runnerMode() {} // #interface runner // sh(cmd) // Runs a command in Hilbish's shell script interpreter. // This is the equivalent of using `source`. -// --- @param cmd string +// #param cmd string func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -67,7 +67,7 @@ func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // lua(cmd) // Evaluates `cmd` as Lua input. This is the same as using `dofile` // or `load`, but is appropriated for the runner interface. -// --- @param cmd string +// #param cmd string func luaRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err diff --git a/timerhandler.go b/timerhandler.go index 0cb4197..0a8e34f 100644 --- a/timerhandler.go +++ b/timerhandler.go @@ -63,11 +63,10 @@ func (th *timersModule) get(id int) *timer { // #interface timers // create(type, time, callback) -> @Timer -// Creates a timer that runs based on the specified `time` in milliseconds. -// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` -// --- @param type number -// --- @param time number -// --- @param callback function +// Creates a timer that runs based on the specified `time`. +// #param type number What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` +// #param time number The amount of time the function should run in milliseconds. +// #param callback function The function to run for the timer. func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.CheckNArgs(3); err != nil { return nil, err @@ -93,8 +92,8 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface timers // get(id) -> @Timer // Retrieves a timer via its ID. -// --- @param id number -// --- @returns Timer +// #param id number +// #returns Timer func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -122,15 +121,10 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a timer API to set intervals and timeouts. These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc -accessible with `doc hilbish`). But if you want slightly more control over -them, there is the `hilbish.timers` interface. It allows you to get -a timer via ID and control them. - -## Timer Object -All functions documented with the `Timer` type refer to a Timer object. +accessible with `doc hilbish`, or `Module hilbish` on the Website). An example of usage: -``` +```lua local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() print 'hello!' end) diff --git a/website/config.toml b/website/config.toml index 174c434..42f3d30 100644 --- a/website/config.toml +++ b/website/config.toml @@ -35,6 +35,7 @@ lineNumbersInTable = false noClasses = false codeFences = true guessSyntax = true +tabWidth = 4 [author] [author.sammyette]