From 7c1984135b5838c9c22d031e28a14675c09e06d1 Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 26 Aug 2023 11:30:51 -0400 Subject: [PATCH 01/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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/22] 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