From 0d43142d5a5bb5f94dd55540677a00993f60ff2c Mon Sep 17 00:00:00 2001 From: sammy-ette Date: Thu, 12 Jun 2025 23:27:39 -0400 Subject: [PATCH] fix: add back docs --- docs/api/hilbish/_index.md | 4 +- docs/api/hilbish/hilbish.editor.md | 124 +++++++++++++++++++++++ docs/api/hilbish/hilbish.history.md | 102 +++++++++++++++++++ docs/api/hilbish/hilbish.jobs.md | 146 ++++++++++++++++++++++++++++ docs/api/hilbish/hilbish.module.md | 73 ++++++++++++++ docs/api/hilbish/hilbish.os.md | 20 ++++ docs/api/hilbish/hilbish.timers.md | 100 +++++++++++++++++++ docs/api/readline.md | 7 ++ 8 files changed, 575 insertions(+), 1 deletion(-) create mode 100644 docs/api/hilbish/hilbish.editor.md create mode 100644 docs/api/hilbish/hilbish.history.md create mode 100644 docs/api/hilbish/hilbish.jobs.md create mode 100644 docs/api/hilbish/hilbish.module.md create mode 100644 docs/api/hilbish/hilbish.os.md create mode 100644 docs/api/hilbish/hilbish.timers.md diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index cfe107be..8c0218f9 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -227,7 +227,9 @@ Note that to set a highlighter, one has to override this function. ```lua --This code will highlight all double quoted strings in green. function hilbish.highlighter(line) - return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) + + return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) + end ``` diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md new file mode 100644 index 00000000..6dac64b8 --- /dev/null +++ b/docs/api/hilbish/hilbish.editor.md @@ -0,0 +1,124 @@ +--- +title: Module hilbish.editor +description: interactions for Hilbish's line reader +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction +The hilbish.editor interface provides functions to +directly interact with the line editor in use. + +## Functions +||| +|----|----| +|deleteByAmount(amount)|Deletes characters in the line by the given amount.| +|getLine() -> string|Returns the current input line.| +|getVimRegister(register) -> string|Returns the text that is at the register.| +|insert(text)|Inserts text into the Hilbish command line.| +|getChar() -> string|Reads a keystroke from the user. This is in a format of something like Ctrl-L.| +|setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.| + +
+
+

+hilbish.editor.deleteByAmount(amount) + + + +

+ +Deletes characters in the line by the given amount. + +#### Parameters +`number` **`amount`** + + +
+ +
+
+

+hilbish.editor.getLine() -> string + + + +

+ +Returns the current input line. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.editor.getVimRegister(register) -> string + + + +

+ +Returns the text that is at the register. + +#### Parameters +`string` **`register`** + + +
+ +
+
+

+hilbish.editor.insert(text) + + + +

+ +Inserts text into the Hilbish command line. + +#### Parameters +`string` **`text`** + + +
+ +
+
+

+hilbish.editor.getChar() -> string + + + +

+ +Reads a keystroke from the user. This is in a format of something like Ctrl-L. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.editor.setVimRegister(register, text) + + + +

+ +Sets the vim register at `register` to hold the passed text. + +#### Parameters +`string` **`register`** + + +`string` **`text`** + + +
+ diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md new file mode 100644 index 00000000..6de9bdf4 --- /dev/null +++ b/docs/api/hilbish/hilbish.history.md @@ -0,0 +1,102 @@ +--- +title: Module hilbish.history +description: command history +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction +The history interface deals with command history. +This includes the ability to override functions to change the main +method of saving history. + +## Functions +||| +|----|----| +|add(cmd)|Adds a command to the history.| +|all() -> table|Retrieves all history as a table.| +|clear()|Deletes all commands from the history.| +|get(index)|Retrieves a command from the history based on the `index`.| +|size() -> number|Returns the amount of commands in the history.| + +
+
+

+hilbish.history.add(cmd) + + + +

+ +Adds a command to the history. + +#### Parameters +`string` **`cmd`** + + +
+ +
+
+

+hilbish.history.all() -> table + + + +

+ +Retrieves all history as a table. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.history.clear() + + + +

+ +Deletes all commands from the history. + +#### Parameters +This function has no parameters. +
+ +
+
+

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

+ +Retrieves a command from the history based on the `index`. + +#### Parameters +`number` **`index`** + + +
+ +
+
+

+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 new file mode 100644 index 00000000..fe3978f6 --- /dev/null +++ b/docs/api/hilbish/hilbish.jobs.md @@ -0,0 +1,146 @@ +--- +title: Module hilbish.jobs +description: background job management +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction + +Manage interactive jobs in Hilbish via Lua. + +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)|Creates a new job. This function does not run the job. This function is intended to be| +|all() -> table[@Job]|Returns a table of all job objects.| +|disown(id)|Disowns a job. This simply deletes it from the list of jobs without stopping it.| +|get(id) -> @Job|Get a job object via its ID.| +|last() -> @Job|Returns the last added job to the table.| + +
+
+

+hilbish.jobs.add(cmdstr, args, execPath) + + + +

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

+hilbish.jobs.all() -> table[Job] + + + +

+ +Returns a table of all job objects. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.jobs.disown(id) + + + +

+ +Disowns a job. This simply deletes it from the list of jobs without stopping it. + +#### Parameters +`number` **`id`** + + +
+ +
+
+

+hilbish.jobs.get(id) -> Job + + + +

+ +Get a job object via its ID. + +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.jobs.last() -> Job + + + +

+ +Returns the last added job to the table. + +#### Parameters +This function has no parameters. +
+ +## Types +
+ +## Job +The Job type describes a Hilbish 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() +Puts a job in the background. This acts the same as initially running a job. + +#### foreground() +Puts a job in the foreground. This will cause it to run like it was +executed normally and wait for it to complete. + +#### start() +Starts running the job. + +#### stop() +Stops the job from running. + diff --git a/docs/api/hilbish/hilbish.module.md b/docs/api/hilbish/hilbish.module.md new file mode 100644 index 00000000..4029d7a7 --- /dev/null +++ b/docs/api/hilbish/hilbish.module.md @@ -0,0 +1,73 @@ +--- +title: Module hilbish.module +description: native module loading +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction + +The hilbish.module interface provides a function to load +Hilbish plugins/modules. Hilbish modules are Go-written +plugins (see https://pkg.go.dev/plugin) that are used to add functionality +to Hilbish that cannot be written in Lua for any reason. + +Note that you don't ever need to use the load function that is here as +modules can be loaded with a `require` call like Lua C modules, and the +search paths can be changed with the `paths` property here. + +To make a valid native module, the Go plugin has to export a Loader function +with a signature like so: `func(*rt.Runtime) rt.Value`. + +`rt` in this case refers to the Runtime type at +https://pkg.go.dev/github.com/arnodel/golua@master/runtime#Runtime + +Hilbish uses this package as its Lua runtime. You will need to read +it to use it for a native plugin. + +Here is some code for an example plugin: +```go +package main + +import ( + rt "github.com/arnodel/golua/runtime" +) + +func Loader(rtm *rt.Runtime) rt.Value { + return rt.StringValue("hello world!") +} +``` + +This can be compiled with `go build -buildmode=plugin plugin.go`. +If you attempt to require and print the result (`print(require 'plugin')`), it will show "hello world!" + +## Functions +||| +|----|----| +|load(path)|Loads a module at the designated `path`.| + +## Static module fields +||| +|----|----| +|paths|A list of paths to search when loading native modules. This is in the style of Lua search paths and will be used when requiring native modules. Example: `?.so;?/?.so`| + +
+
+

+hilbish.module.load(path) + + + +

+ +Loads a module at the designated `path`. +It will throw if any error occurs. + +#### Parameters +`string` **`path`** + + +
+ diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md new file mode 100644 index 00000000..13b56b05 --- /dev/null +++ b/docs/api/hilbish/hilbish.os.md @@ -0,0 +1,20 @@ +--- +title: Module hilbish.os +description: operating system info +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction +Provides simple text information properties about the current operating system. +This mainly includes the name and version. + +## Static module fields +||| +|----|----| +|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.timers.md b/docs/api/hilbish/hilbish.timers.md new file mode 100644 index 00000000..f218d2bc --- /dev/null +++ b/docs/api/hilbish/hilbish.timers.md @@ -0,0 +1,100 @@ +--- +title: Module hilbish.timers +description: timeout and interval API +layout: doc +menu: + docs: + parent: "API" +--- + +## Introduction + +If you ever want to run a piece of code on a timed interval, or want to wait +a few seconds, you don't have to rely on timing tricks, as Hilbish has a +timer API to set intervals and timeouts. + +These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc +accessible with `doc hilbish`, or `Module hilbish` on the Website). + +An example of usage: +```lua +local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() + print 'hello!' +end) + +t:start() +print(t.running) // true +``` + +## Functions +||| +|----|----| +|create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time`.| +|get(id) -> @Timer|Retrieves a timer via its ID.| + +## Static module fields +||| +|----|----| +|INTERVAL|Constant for an interval timer type| +|TIMEOUT|Constant for a timeout timer type| + +
+
+

+hilbish.timers.create(type, time, callback) -> Timer + + + +

+ +Creates a timer that runs based on the specified `time`. + +#### Parameters +`number` **`type`** +What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` + +`number` **`time`** +The amount of time the function should run in milliseconds. + +`function` **`callback`** +The function to run for the timer. + +
+ +
+
+

+hilbish.timers.get(id) -> Timer + + + +

+ +Retrieves a timer via its ID. + +#### Parameters +`number` **`id`** + + +
+ +## Types +
+ +## Timer +The Job type describes a Hilbish timer. +## 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() +Starts a timer. + +#### stop() +Stops a timer. + diff --git a/docs/api/readline.md b/docs/api/readline.md index 656896e0..27b4a08b 100644 --- a/docs/api/readline.md +++ b/docs/api/readline.md @@ -14,6 +14,13 @@ point it will be separated into it's own git repository (at a stage when I am confident that murex will no longer be the primary driver for features, bugs or other code changes) +line reader library +The readline module is responsible for reading input from the user. +The readline module is what Hilbish uses to read input from the user, +including all the interactive features of Hilbish like history search, +syntax highlighting, everything. The global Hilbish readline instance +is usable at `hilbish.editor`. + Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems.