mirror of
https://github.com/Hilbis/Hilbish
synced 2025-07-01 16:52:03 +00:00
fix: add back docs
This commit is contained in:
parent
45ceb9097f
commit
0d43142d5a
GPG Key ID:
904FC49417B44DCD
@ -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)
|
||||
|
||||
end
|
||||
```
|
||||
</div>
|
||||
|
||||
124
docs/api/hilbish/hilbish.editor.md
Normal file
124
docs/api/hilbish/hilbish.editor.md
Normal file
@ -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
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#editor.deleteByAmount">deleteByAmount(amount)</a>|Deletes characters in the line by the given amount.|
|
||||
|<a href="#editor.getLine">getLine() -> string</a>|Returns the current input line.|
|
||||
|<a href="#editor.getVimRegister">getVimRegister(register) -> string</a>|Returns the text that is at the register.|
|
||||
|<a href="#editor.insert">insert(text)</a>|Inserts text into the Hilbish command line.|
|
||||
|<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format of something like Ctrl-L.|
|
||||
|<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
|
||||
|
||||
<hr>
|
||||
<div id='editor.deleteByAmount'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.deleteByAmount(amount)
|
||||
<a href="#editor.deleteByAmount" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Deletes characters in the line by the given amount.
|
||||
|
||||
#### Parameters
|
||||
`number` **`amount`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='editor.getLine'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.getLine() -> string
|
||||
<a href="#editor.getLine" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns the current input line.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='editor.getVimRegister'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.getVimRegister(register) -> string
|
||||
<a href="#editor.getVimRegister" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns the text that is at the register.
|
||||
|
||||
#### Parameters
|
||||
`string` **`register`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='editor.insert'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.insert(text)
|
||||
<a href="#editor.insert" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Inserts text into the Hilbish command line.
|
||||
|
||||
#### Parameters
|
||||
`string` **`text`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='editor.getChar'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.getChar() -> string
|
||||
<a href="#editor.getChar" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Reads a keystroke from the user. This is in a format of something like Ctrl-L.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='editor.setVimRegister'>
|
||||
<h4 class='heading'>
|
||||
hilbish.editor.setVimRegister(register, text)
|
||||
<a href="#editor.setVimRegister" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Sets the vim register at `register` to hold the passed text.
|
||||
|
||||
#### Parameters
|
||||
`string` **`register`**
|
||||
|
||||
|
||||
`string` **`text`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
102
docs/api/hilbish/hilbish.history.md
Normal file
102
docs/api/hilbish/hilbish.history.md
Normal file
@ -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
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#history.add">add(cmd)</a>|Adds a command to the history.|
|
||||
|<a href="#history.all">all() -> table</a>|Retrieves all history as a table.|
|
||||
|<a href="#history.clear">clear()</a>|Deletes all commands from the history.|
|
||||
|<a href="#history.get">get(index)</a>|Retrieves a command from the history based on the `index`.|
|
||||
|<a href="#history.size">size() -> number</a>|Returns the amount of commands in the history.|
|
||||
|
||||
<hr>
|
||||
<div id='history.add'>
|
||||
<h4 class='heading'>
|
||||
hilbish.history.add(cmd)
|
||||
<a href="#history.add" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Adds a command to the history.
|
||||
|
||||
#### Parameters
|
||||
`string` **`cmd`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='history.all'>
|
||||
<h4 class='heading'>
|
||||
hilbish.history.all() -> table
|
||||
<a href="#history.all" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Retrieves all history as a table.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='history.clear'>
|
||||
<h4 class='heading'>
|
||||
hilbish.history.clear()
|
||||
<a href="#history.clear" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Deletes all commands from the history.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='history.get'>
|
||||
<h4 class='heading'>
|
||||
hilbish.history.get(index)
|
||||
<a href="#history.get" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Retrieves a command from the history based on the `index`.
|
||||
|
||||
#### Parameters
|
||||
`number` **`index`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='history.size'>
|
||||
<h4 class='heading'>
|
||||
hilbish.history.size() -> number
|
||||
<a href="#history.size" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns the amount of commands in the history.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
146
docs/api/hilbish/hilbish.jobs.md
Normal file
146
docs/api/hilbish/hilbish.jobs.md
Normal file
@ -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
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Creates a new job. This function does not run the job. This function is intended to be|
|
||||
|<a href="#jobs.all">all() -> table[@Job]</a>|Returns a table of all job objects.|
|
||||
|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This simply deletes it from the list of jobs without stopping it.|
|
||||
|<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.|
|
||||
|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
|
||||
|
||||
<hr>
|
||||
<div id='jobs.add'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.add(cmdstr, args, execPath)
|
||||
<a href="#jobs.add" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
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')
|
||||
```
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.all'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>]
|
||||
<a href="#jobs.all" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns a table of all job objects.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.disown'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.disown(id)
|
||||
<a href="#jobs.disown" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Disowns a job. This simply deletes it from the list of jobs without stopping it.
|
||||
|
||||
#### Parameters
|
||||
`number` **`id`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.get'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
|
||||
<a href="#jobs.get" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Get a job object via its ID.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='jobs.last'>
|
||||
<h4 class='heading'>
|
||||
hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
|
||||
<a href="#jobs.last" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Returns the last added job to the table.
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
## Types
|
||||
<hr>
|
||||
|
||||
## 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.
|
||||
|
||||
73
docs/api/hilbish/hilbish.module.md
Normal file
73
docs/api/hilbish/hilbish.module.md
Normal file
@ -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
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#module.load">load(path)</a>|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`|
|
||||
|
||||
<hr>
|
||||
<div id='module.load'>
|
||||
<h4 class='heading'>
|
||||
hilbish.module.load(path)
|
||||
<a href="#module.load" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Loads a module at the designated `path`.
|
||||
It will throw if any error occurs.
|
||||
|
||||
#### Parameters
|
||||
`string` **`path`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
20
docs/api/hilbish/hilbish.os.md
Normal file
20
docs/api/hilbish/hilbish.os.md
Normal file
@ -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|
|
||||
|
||||
100
docs/api/hilbish/hilbish.timers.md
Normal file
100
docs/api/hilbish/hilbish.timers.md
Normal file
@ -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
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time`.|
|
||||
|<a href="#timers.get">get(id) -> @Timer</a>|Retrieves a timer via its ID.|
|
||||
|
||||
## Static module fields
|
||||
|||
|
||||
|----|----|
|
||||
|INTERVAL|Constant for an interval timer type|
|
||||
|TIMEOUT|Constant for a timeout timer type|
|
||||
|
||||
<hr>
|
||||
<div id='timers.create'>
|
||||
<h4 class='heading'>
|
||||
hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;" id="lol">Timer</a>
|
||||
<a href="#timers.create" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
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.
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='timers.get'>
|
||||
<h4 class='heading'>
|
||||
hilbish.timers.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#timer" style="text-decoration: none;" id="lol">Timer</a>
|
||||
<a href="#timers.get" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Retrieves a timer via its ID.
|
||||
|
||||
#### Parameters
|
||||
`number` **`id`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
## Types
|
||||
<hr>
|
||||
|
||||
## 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.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user