diff --git a/docs/api/bait.md b/docs/api/bait.md index 829ba86..2eaaffe 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -1,91 +1,31 @@ --- name: Module bait -description: the core Hilbish API +description: the event emitter layout: apidoc --- ## Introduction -The Hilbish module includes the core API, containing -interfaces and functions which directly relate to shell functionality. +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. ## Functions -### alias(cmd, orig) -Sets an alias of `cmd` to `orig` +### catch(name, cb) +Catches a hook with `name`. Runs the `cb` when it is thrown -### appendPath(dir) -Appends `dir` to $PATH +### catchOnce(name, cb) +Same as catch, but only runs the `cb` once and then removes the hook -### 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. +### hooks(name) -> {cb, cb...} +Returns a table with hooks on the event with `name`. -### cwd() -Returns the current directory of the shell +### 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. -### exec(cmd) -Replaces running hilbish with `cmd` - -### goro(fn) -Puts `fn` in a goroutine - -### highlighter(line) -Line highlighter handler. This is mainly for syntax highlighting, but in -reality could set the input of the prompt to *display* anything. The -callback is passed the current line and is expected to return a line that -will be used as the input display. - -### hinter(line, pos) -The command line hint handler. It gets called on every key insert to -determine what text to use as an inline hint. It is passed the current -line and cursor position. It is expected to return a string which is used -as the text for the hint. This is by default a shim. To set hints, -override this function with your custom handler. - -### inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim - -### interval(cb, time) -Runs the `cb` function every `time` milliseconds. -Returns a `timer` object (see `doc timers`). - -### multiprompt(str) -Changes the continued line prompt to `str` - -### prependPath(dir) -Prepends `dir` to $PATH - -### prompt(str, typ?) -Changes the shell prompt to `str` -There are a few verbs that can be used in the prompt text. -These will be formatted and replaced with the appropriate values. -`%d` - Current working directory -`%u` - Name of current user -`%h` - Hostname of device - -### read(prompt?) -> input? -Read input from the user, using Hilbish's line editor/input reader. -This is a separate instance from the one Hilbish actually uses. -Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) - -### run(cmd, returnOut) -> exitCode, stdout, stderr -Runs `cmd` in Hilbish's sh interpreter. -If returnOut is true, the outputs of `cmd` will be returned as the 2nd and -3rd values instead of being outputted to the terminal. - -### runnerMode(mode) -Sets the execution/runner mode for interactive Hilbish. This determines whether -Hilbish wll try to run input as Lua and/or sh or only do one of either. -Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), -sh, and lua. It also accepts a function, to which if it is passed one -will call it to execute user input instead. - -### timeout(cb, time) -Runs the `cb` function after `time` in milliseconds -Returns a `timer` object (see `doc timers`). - -### which(name) -Checks if `name` is a valid command +### throw(name, ...args) +Throws a hook with `name` with the provided `args` diff --git a/docs/api/commander.md b/docs/api/commander.md index 01031d6..379ecba 100644 --- a/docs/api/commander.md +++ b/docs/api/commander.md @@ -1,23 +1,16 @@ --- name: Module commander -description: low level terminal library +description: library for custom commands layout: apidoc --- ## Introduction -The terminal library is a simple and lower level library for certain terminal interactions. +Commander is a library for writing custom commands in Lua. ## Functions -### restoreState() -Restores the last saved state of the terminal +### deregister(name) +Deregisters any command registered with `name` -### saveState() -Saves the current state of the terminal - -### setRaw() -Puts the terminal in raw mode - -### size() -Gets the dimensions of the terminal. Returns a table with `width` and `height` -Note: this is not the size in relation to the dimensions of the display +### register(name, cb) +Register a command with `name` that runs `cb` when ran diff --git a/docs/api/fs.md b/docs/api/fs.md index 3a9db21..3800422 100644 --- a/docs/api/fs.md +++ b/docs/api/fs.md @@ -1,91 +1,43 @@ --- name: Module fs -description: the core Hilbish API +description: filesystem interaction and functionality library layout: apidoc --- ## Introduction -The Hilbish module includes the core API, containing -interfaces and functions which directly relate to shell functionality. +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. ## Functions -### alias(cmd, orig) -Sets an alias of `cmd` to `orig` +### abs(path) +Gives an absolute version of `path`. -### appendPath(dir) -Appends `dir` to $PATH +### basename(path) +Gives the basename of `path`. For the rules, +see Go's filepath.Base -### 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. +### cd(dir) +Changes directory to `dir` -### cwd() -Returns the current directory of the shell +### dir(path) +Returns the directory part of `path`. For the rules, see Go's +filepath.Dir -### exec(cmd) -Replaces running hilbish with `cmd` +### glob(pattern) +Glob all files and directories that match the pattern. +For the rules, see Go's filepath.Glob -### goro(fn) -Puts `fn` in a goroutine +### join(paths...) +Takes paths and joins them together with the OS's +directory separator (forward or backward slash). -### highlighter(line) -Line highlighter handler. This is mainly for syntax highlighting, but in -reality could set the input of the prompt to *display* anything. The -callback is passed the current line and is expected to return a line that -will be used as the input display. +### mkdir(name, recursive) +Makes a directory called `name`. If `recursive` is true, it will create its parent directories. -### hinter(line, pos) -The command line hint handler. It gets called on every key insert to -determine what text to use as an inline hint. It is passed the current -line and cursor position. It is expected to return a string which is used -as the text for the hint. This is by default a shim. To set hints, -override this function with your custom handler. +### readdir(dir) +Returns a table of files in `dir` -### inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim - -### interval(cb, time) -Runs the `cb` function every `time` milliseconds. -Returns a `timer` object (see `doc timers`). - -### multiprompt(str) -Changes the continued line prompt to `str` - -### prependPath(dir) -Prepends `dir` to $PATH - -### prompt(str, typ?) -Changes the shell prompt to `str` -There are a few verbs that can be used in the prompt text. -These will be formatted and replaced with the appropriate values. -`%d` - Current working directory -`%u` - Name of current user -`%h` - Hostname of device - -### read(prompt?) -> input? -Read input from the user, using Hilbish's line editor/input reader. -This is a separate instance from the one Hilbish actually uses. -Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) - -### run(cmd, returnOut) -> exitCode, stdout, stderr -Runs `cmd` in Hilbish's sh interpreter. -If returnOut is true, the outputs of `cmd` will be returned as the 2nd and -3rd values instead of being outputted to the terminal. - -### runnerMode(mode) -Sets the execution/runner mode for interactive Hilbish. This determines whether -Hilbish wll try to run input as Lua and/or sh or only do one of either. -Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), -sh, and lua. It also accepts a function, to which if it is passed one -will call it to execute user input instead. - -### timeout(cb, time) -Runs the `cb` function after `time` in milliseconds -Returns a `timer` object (see `doc timers`). - -### which(name) -Checks if `name` is a valid command +### stat(path) +Returns info about `path` diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 017084d..f1007d8 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -1,91 +1,23 @@ --- name: Module terminal -description: the core Hilbish API +description: low level terminal library layout: apidoc --- ## Introduction -The Hilbish module includes the core API, containing -interfaces and functions which directly relate to shell functionality. +The terminal library is a simple and lower level library for certain terminal interactions. ## Functions -### alias(cmd, orig) -Sets an alias of `cmd` to `orig` +### restoreState() +Restores the last saved state of the terminal -### appendPath(dir) -Appends `dir` to $PATH +### saveState() +Saves the current state of the terminal -### complete(scope, cb) -Registers a completion handler for `scope`. -A `scope` is currently only expected to be `command.`, -replacing with the name of the command (for example `command.git`). -`cb` must be a function that returns a table of "completion groups." -Check `doc completions` for more information. +### setRaw() +Puts the terminal in raw mode -### cwd() -Returns the current directory of the shell - -### exec(cmd) -Replaces running hilbish with `cmd` - -### goro(fn) -Puts `fn` in a goroutine - -### highlighter(line) -Line highlighter handler. This is mainly for syntax highlighting, but in -reality could set the input of the prompt to *display* anything. The -callback is passed the current line and is expected to return a line that -will be used as the input display. - -### hinter(line, pos) -The command line hint handler. It gets called on every key insert to -determine what text to use as an inline hint. It is passed the current -line and cursor position. It is expected to return a string which is used -as the text for the hint. This is by default a shim. To set hints, -override this function with your custom handler. - -### inputMode(mode) -Sets the input mode for Hilbish's line reader. Accepts either emacs or vim - -### interval(cb, time) -Runs the `cb` function every `time` milliseconds. -Returns a `timer` object (see `doc timers`). - -### multiprompt(str) -Changes the continued line prompt to `str` - -### prependPath(dir) -Prepends `dir` to $PATH - -### prompt(str, typ?) -Changes the shell prompt to `str` -There are a few verbs that can be used in the prompt text. -These will be formatted and replaced with the appropriate values. -`%d` - Current working directory -`%u` - Name of current user -`%h` - Hostname of device - -### read(prompt?) -> input? -Read input from the user, using Hilbish's line editor/input reader. -This is a separate instance from the one Hilbish actually uses. -Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) - -### run(cmd, returnOut) -> exitCode, stdout, stderr -Runs `cmd` in Hilbish's sh interpreter. -If returnOut is true, the outputs of `cmd` will be returned as the 2nd and -3rd values instead of being outputted to the terminal. - -### runnerMode(mode) -Sets the execution/runner mode for interactive Hilbish. This determines whether -Hilbish wll try to run input as Lua and/or sh or only do one of either. -Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), -sh, and lua. It also accepts a function, to which if it is passed one -will call it to execute user input instead. - -### timeout(cb, time) -Runs the `cb` function after `time` in milliseconds -Returns a `timer` object (see `doc timers`). - -### which(name) -Checks if `name` is a valid command +### 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