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