Compare commits

...

3 Commits

Author SHA1 Message Date
sammyette 48ef443bb5
docs: minor changes and fixes 2023-12-25 22:48:25 -04:00
sammyette 85e1307e7d
docs: fix fs.mkdir example 2023-12-25 22:36:32 -04:00
sammyette 3219c47071
docs: reorganize text and add more info 2023-12-25 22:32:37 -04:00
19 changed files with 312 additions and 193 deletions

62
api.go
View File

@ -237,7 +237,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// cwd() -> string // cwd() -> string
// Returns the current directory of the shell // Returns the current directory of the shell.
// #returns string // #returns string
func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
cwd, _ := os.Getwd() cwd, _ := os.Getwd()
@ -249,8 +249,8 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// read(prompt) -> input (string) // read(prompt) -> input (string)
// Read input from the user, using Hilbish's line editor/input reader. // Read input from the user, using Hilbish's line editor/input reader.
// This is a separate instance from the one Hilbish actually uses. // 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). // Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
// #param prompt? string // #param prompt? string Text to print before input, can be empty.
// #returns string|nil // #returns string|nil
func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
luaprompt := c.Arg(0) luaprompt := c.Arg(0)
@ -479,8 +479,9 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// goro(fn) // goro(fn)
// Puts `fn` in a Goroutine. // Puts `fn` in a Goroutine.
// This can be used to run any function in another thread. // This can be used to run any function in another thread at the same time as other Lua code.
// **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** // **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
// **This is a limitation of the Lua runtime.**
// #param fn function // #param fn function
func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
@ -503,10 +504,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// timeout(cb, time) -> @Timer // timeout(cb, time) -> @Timer
// Runs the `cb` function after `time` in milliseconds. // Executed the `cb` function after a period of `time`.
// This creates a Timer that starts immediately. // This creates a Timer that starts ticking immediately.
// #param cb function // #param cb function
// #param time number // #param time number Time to run in milliseconds.
// #returns Timer // #returns Timer
func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
@ -529,10 +530,10 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// interval(cb, time) -> @Timer // interval(cb, time) -> @Timer
// Runs the `cb` function every `time` milliseconds. // Runs the `cb` function every specified amount of `time`.
// This creates a timer that starts immediately. // This creates a timer that ticking immediately.
// #param cb function // #param cb function
// #param time number // #param time number Time in milliseconds.
// #return Timer // #return Timer
func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
@ -556,12 +557,39 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// complete(scope, cb) // complete(scope, cb)
// Registers a completion handler for the specified scope. // Registers a completion handler for the specified scope.
// A `scope` is currently only expected to be `command.<cmd>`, // A `scope` is expected to be `command.<cmd>`,
// replacing <cmd> with the name of the command (for example `command.git`). // replacing <cmd> with the name of the command (for example `command.git`).
// The documentation for completions, under Features/Completions or `doc completions` // The documentation for completions, under Features/Completions or `doc completions`
// provides more details. // provides more details.
// #param scope string // #param scope string
// #param cb function // #param cb function
/*
#example
-- This is a very simple example. Read the full doc for completions for details.
hilbish.complete('command.sudo', function(query, ctx, fields)
if #fields == 0 then
-- complete for commands
local comps, pfx = hilbish.completion.bins(query, ctx, fields)
local compGroup = {
items = comps, -- our list of items to complete
type = 'grid' -- what our completions will look like.
}
return {compGroup}, pfx
end
-- otherwise just be boring and return files
local comps, pfx = hilbish.completion.files(query, ctx, fields)
local compGroup = {
items = comps,
type = 'grid'
}
return {compGroup}, pfx
end)
#example
*/
func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
scope, cb, err := util.HandleStrCallback(t, c) scope, cb, err := util.HandleStrCallback(t, c)
if err != nil { if err != nil {
@ -628,10 +656,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// inputMode(mode) // 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.
// `emacs` is the default. Setting it to `vim` changes behavior of input to be // `emacs` is the default. Setting it to `vim` changes behavior of input to be
// Vim-like with modes and Vim keybinds. // Vim-like with modes and Vim keybinds.
// #param mode string // #param mode string Can be set to either `emacs` or `vim`
func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -656,11 +684,13 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// runnerMode(mode) // runnerMode(mode)
// Sets the execution/runner mode for interactive Hilbish. This determines whether // Sets the execution/runner mode for interactive Hilbish.
// Hilbish wll try to run input as Lua and/or sh or only do one of either. // 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), // 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 // sh, and lua. It also accepts a function, to which if it is passed one
// will call it to execute user input instead. // will call it to execute user input instead.
// Read [about runner mode](../features/runner-mode) for more information.
// #param mode string|function // #param mode string|function
func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
@ -688,7 +718,7 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// as the text for the hint. This is by default a shim. To set hints, // as the text for the hint. This is by default a shim. To set hints,
// override this function with your custom handler. // override this function with your custom handler.
// #param line string // #param line string
// #param pos number // #param pos number Position of cursor in line. Usually equals string.len(line)
/* /*
#example #example
-- this will display "hi" after the cursor in a dimmed color. -- this will display "hi" after the cursor in a dimmed color.

View File

@ -37,7 +37,7 @@ this function will set the user prompt.
|----|----| |----|----|
|<a href="#catch">catch(name, cb)</a>|Catches an event. This function can be used to act on events.| |<a href="#catch">catch(name, cb)</a>|Catches an event. This function can be used to act on events.|
|<a href="#catchOnce">catchOnce(name, cb)</a>|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.| |<a href="#catchOnce">catchOnce(name, cb)</a>|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.|
|<a href="#hooks">hooks(name) -> table</a>|Returns a list of callbacks that are hooked on an event with the corresponding `name`.| |<a href="#hooks">hooks(name) -> table</a>|Returns a table of functions that are hooked on an event with the corresponding `name`.|
|<a href="#release">release(name, catcher)</a>|Removes the `catcher` for the event with `name`.| |<a href="#release">release(name, catcher)</a>|Removes the `catcher` for the event with `name`.|
|<a href="#throw">throw(name, ...args)</a>|Throws a hook with `name` with the provided `args`.| |<a href="#throw">throw(name, ...args)</a>|Throws a hook with `name` with the provided `args`.|
@ -96,11 +96,11 @@ bait.hooks(name) -> table
</a> </a>
</h4> </h4>
Returns a list of callbacks that are hooked on an event with the corresponding `name`. Returns a table of functions that are hooked on an event with the corresponding `name`.
#### Parameters #### Parameters
`string` **`name`** `string` **`name`**
The name of the function The name of the hook
</div> </div>

View File

@ -167,9 +167,6 @@ fs.mkdir(name, recursive)
Creates a new directory with the provided `name`. Creates a new directory with the provided `name`.
With `recursive`, mkdir will create parent directories. 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 #### Parameters
`string` **`name`** `string` **`name`**
@ -180,7 +177,9 @@ Whether to create parent directories for the provided name
#### Example #### Example
```lua ```lua
-- 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)
``` ```
</div> </div>

View File

@ -17,20 +17,20 @@ interfaces and functions which directly relate to shell functionality.
|<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.| |<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
|<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)| |<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
|<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.| |<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell| |<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell.|
|<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.| |<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
|<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.| |<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.|
|<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.| |<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
|<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to| |<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to|
|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.| |<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader.|
|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.| |<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every specified amount of `time`.|
|<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.| |<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
|<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.| |<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
|<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.| |<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
|<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.| |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.| |<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether| |<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.| |<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
|<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.| |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
## Static module fields ## Static module fields
@ -113,7 +113,7 @@ hilbish.complete(scope, cb)
</h4> </h4>
Registers a completion handler for the specified scope. Registers a completion handler for the specified scope.
A `scope` is currently only expected to be `command.<cmd>`, A `scope` is expected to be `command.<cmd>`,
replacing <cmd> with the name of the command (for example `command.git`). replacing <cmd> with the name of the command (for example `command.git`).
The documentation for completions, under Features/Completions or `doc completions` The documentation for completions, under Features/Completions or `doc completions`
provides more details. provides more details.
@ -125,6 +125,32 @@ provides more details.
`function` **`cb`** `function` **`cb`**
#### Example
```lua
-- This is a very simple example. Read the full doc for completions for details.
hilbish.complete('command.sudo', function(query, ctx, fields)
if #fields == 0 then
-- complete for commands
local comps, pfx = hilbish.completion.bins(query, ctx, fields)
local compGroup = {
items = comps, -- our list of items to complete
type = 'grid' -- what our completions will look like.
}
return {compGroup}, pfx
end
-- otherwise just be boring and return files
local comps, pfx = hilbish.completion.files(query, ctx, fields)
local compGroup = {
items = comps,
type = 'grid'
}
return {compGroup}, pfx
end)
```
</div> </div>
<hr> <hr>
@ -136,7 +162,7 @@ hilbish.cwd() -> string
</a> </a>
</h4> </h4>
Returns the current directory of the shell Returns the current directory of the shell.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
@ -170,8 +196,9 @@ hilbish.goro(fn)
</h4> </h4>
Puts `fn` in a Goroutine. Puts `fn` in a Goroutine.
This can be used to run any function in another thread. This can be used to run any function in another thread at the same time as other Lua code.
**NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
**This is a limitation of the Lua runtime.**
#### Parameters #### Parameters
`function` **`fn`** `function` **`fn`**
@ -227,7 +254,7 @@ override this function with your custom handler.
`number` **`pos`** `number` **`pos`**
Position of cursor in line. Usually equals string.len(line)
#### Example #### Example
```lua ```lua
@ -247,13 +274,13 @@ hilbish.inputMode(mode)
</a> </a>
</h4> </h4>
Sets the input mode for Hilbish's line reader. Accepts either emacs or vim. Sets the input mode for Hilbish's line reader.
`emacs` is the default. Setting it to `vim` changes behavior of input to be `emacs` is the default. Setting it to `vim` changes behavior of input to be
Vim-like with modes and Vim keybinds. Vim-like with modes and Vim keybinds.
#### Parameters #### Parameters
`string` **`mode`** `string` **`mode`**
Can be set to either `emacs` or `vim`
</div> </div>
@ -266,15 +293,15 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
</a> </a>
</h4> </h4>
Runs the `cb` function every `time` milliseconds. Runs the `cb` function every specified amount of `time`.
This creates a timer that starts immediately. This creates a timer that ticking immediately.
#### Parameters #### Parameters
`function` **`cb`** `function` **`cb`**
`number` **`time`** `number` **`time`**
Time in milliseconds.
</div> </div>
@ -375,11 +402,11 @@ hilbish.read(prompt) -> input (string)
Read input from the user, using Hilbish's line editor/input reader. Read input from the user, using Hilbish's line editor/input reader.
This is a separate instance from the one Hilbish actually uses. 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). Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
#### Parameters #### Parameters
`string` **`prompt?`** `string` **`prompt?`**
Text to print before input, can be empty.
</div> </div>
@ -412,11 +439,13 @@ hilbish.runnerMode(mode)
</a> </a>
</h4> </h4>
Sets the execution/runner mode for interactive Hilbish. This determines whether Sets the execution/runner mode for interactive Hilbish.
Hilbish wll try to run input as Lua and/or sh or only do one of either. 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), 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 sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead. will call it to execute user input instead.
Read [about runner mode](../features/runner-mode) for more information.
#### Parameters #### Parameters
`string|function` **`mode`** `string|function` **`mode`**
@ -433,15 +462,15 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
</a> </a>
</h4> </h4>
Runs the `cb` function after `time` in milliseconds. Executed the `cb` function after a period of `time`.
This creates a Timer that starts immediately. This creates a Timer that starts ticking immediately.
#### Parameters #### Parameters
`function` **`cb`** `function` **`cb`**
`number` **`time`** `number` **`time`**
Time to run in milliseconds.
</div> </div>

View File

@ -43,7 +43,7 @@ String that a user would write for the job
Arguments for the commands. Has to include the name of the command. Arguments for the commands. Has to include the name of the command.
`string` **`execPath`** `string` **`execPath`**
Binary to use to run the command. Does not Binary to use to run the command. Needs to be an absolute path.
#### Example #### Example
```lua ```lua

View File

@ -14,6 +14,41 @@ Users can add and change the default runner for interactive input to any
language or script of their choosing. A good example is using it to language or script of their choosing. A good example is using it to
write command in Fennel. write command in Fennel.
Runners are functions that evaluate user input. The default runners in
Hilbish can run shell script and Lua code.
A runner is passed the input and has to return a table with these values.
All are not required, only the useful ones the runner needs to return.
(So if there isn't an error, just omit `err`.)
- `exitCode` (number): A numerical code to indicate the exit result.
- `input` (string): The user input. This will be used to add
to the history.
- `err` (string): A string to indicate an interal error for the runner.
It can be set to a few special values for Hilbish to throw the right hooks and have a better looking message:
`[command]: not-found` will throw a command.not-found hook based on what `[command]` is.
`[command]: not-executable` will throw a command.not-executable hook.
- `continue` (boolean): Whether to prompt the user for more input.
Here is a simple example of a fennel runner. It falls back to
shell script if fennel eval has an error.
```lua
local fennel = require 'fennel'
hilbish.runnerMode(function(input)
local ok = pcall(fennel.eval, input)
if ok then
return {
input = input
}
end
return hilbish.runner.sh(input)
end)
```
## Functions ## Functions
||| |||
|----|----| |----|----|

View File

@ -7,59 +7,72 @@ menu:
parent: "Features" parent: "Features"
--- ---
Hilbish has a pretty good completion system. It has a nice looking Completions for commands can be created with the [`hilbish.complete`](../api/hilbish#complete)
menu, with 2 types of menus: grid (like file completions) or function. See the link for how to use it.
list.
To create completions for a command is simple.
The callback will be passed 3 parameters:
- `query` (string): The text that the user is currently trying to complete.
This should be used to match entries.
- `ctx` (string): Contains the entire line. Use this if
more text is needed to be parsed for context.
- `fields` (string): The `ctx` split up by spaces.
In most cases, the completer just uses `fields` to check the amount
and `query` on what to match entries on.
In order to return your results, it has to go within a "completion group."
Then you return a table of completion groups and a prefix. The prefix will
usually just be the `query`.
Hilbish allows one to mix completion menus of different types, so
a grid menu and a list menu can be used and complete and display at the same time.
A completion group is a table with these keys:
- `type` (string): type of completion menu, either `grid` or `list`.
- `items` (table): a list of items.
The requirements of the `items` table is different based on the
`type`. If it is a `grid`, it can simply be a table of strings.
Otherwise if it is a `list` then each entry can
either be a string or a table.
Example:
```lua
local cg = {
items = {
'list item 1',
['--command-flag-here'] = {'this does a thing', '--the-flag-alias'}
},
type = 'list'
}
local cg2 = {
items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
type = 'grid'
}
return {cg, cg2}, prefix
```
Which looks like this:
{{< video src="https://safe.saya.moe/t4CiLK6dgPbD.mp4" >}}
# Completion Handler
Like most parts of Hilbish, it's made to be extensible and Like most parts of Hilbish, it's made to be extensible and
customizable. The default handler for completions in general can customizable. The default handler for completions in general can
be overwritten to provide more advanced completions if needed. be overwritten to provide more advanced completions if needed.
This usually doesn't need to be done though, unless you know
what you're doing.
# Completion Handler The default completion handler provides 3 things:
By default, it provides 3 things: for the first argument,
binaries (with a plain name requested to complete, those in binaries (with a plain name requested to complete, those in
$PATH), files, or command completions. With the default $PATH), files, or command completions. It will try to run a handler
completion handler, it will try to run a handler for the for the command or fallback to file completions.
command or fallback to file completions.
To overwrite it, just assign a function to To overwrite it, just assign a function to `hilbish.completion.handler` like so:
`hilbish.completion.handler` like so: ```lua
-- line is the entire line as a string
-- pos is the position of the cursor.
function hilbish.completion.handler(line, pos) function hilbish.completion.handler(line, pos)
-- do things -- do things
end end
```
It is passed 2 arguments, the entire line, and the current
cursor position. The functions in the completion interface
take 3 arguments: query, ctx, and fields.
- The `query`, which what the user is currently trying to complete
- `ctx`, being just the entire line
- `fields` being a table of arguments. It's just `ctx` split up,
delimited by spaces.
It's expected to return 2 things: a table of completion groups, and
a prefix. A completion group is defined as a table with 2 keys:
`items` and `type`.
- The `items` field is just a table of items to use for completions.
- The `type` is for the completion menu type, being either `grid` or
`list`.
The prefix is what all the completions start with. It should be empty
if the user doesn't have a query. If the beginning of the completion
item does not match the prefix, it will be replaced and fixed
properly in the line. It is case sensitive.
If you want to overwrite the functionality of the general completion
handler, or make your command completion have files as well
(and filter them), then there is the `files` function, which is
mentioned below.
# Completion Interface
## Functions
- `files(query, ctx, fields)` -> table, prefix: get file completions,
based on the user's query.
- `bins(query, ctx, fields)` -> table, prefix: get binary/executable
completions, based on user query.
- `call(scope, query, ctx, fields)` -> table, prefix: call a completion
handler with `scope`, usually being in the form of `command.<name>`

View File

@ -19,3 +19,48 @@ Fennel as the interactive script runner.
Runner mode can also be used to handle specific kinds of input before Runner mode can also be used to handle specific kinds of input before
evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh) evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh)
handles links. handles links.
The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`,
which determines how Hilbish will run user input. By default, this is
set to `hybrid` which is the previously mentioned behaviour of running Lua
first then going to shell script. If you want the reverse order, you can
set it to `hybridRev` and for isolated modes there is `sh` and `lua`
respectively.
You can also set it to a function, which will be called everytime Hilbish
needs to run interactive input. For more detail, see the [API documentation](../../api/hilbish/hilbish.runner)
The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
and also provides the shell script and Lua runner functions that Hilbish itself uses.
A runner function is expected to return a table with the following values:
- `exitCode` (number): Exit code of the command
- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
more is requested.
- `err` (string): A string that represents an error from the runner.
This should only be set when, for example, there is a syntax error.
It can be set to a few special values for Hilbish to throw the right
hooks and have a better looking message.
- `<command>: not-found` will throw a `command.not-found` hook
based on what `<command>` is.
- `<command>: not-executable` will throw a `command.not-executable` hook.
- `continue` (boolean): Whether Hilbish should prompt the user for no input
## Functions
These are the "low level" functions for the `hilbish.runner` interface.
+ setMode(mode) > The same as `hilbish.runnerMode`
+ sh(input) -> table > Runs `input` in Hilbish's sh interpreter
+ lua(input) -> table > Evals `input` as Lua code
These functions should be preferred over the previous ones.
+ setCurrent(mode) > The same as `setMode`, but works with runners managed
via the functions below.
+ add(name, runner) > Adds a runner to a table of available runners. The `runner`
argument is either a function or a table with a run callback.
+ set(name, runner) > The same as `add` but requires passing a table and
overwrites if the `name`d runner already exists.
+ get(name) > runner > Gets a runner by name. It is a table with at least a
run function, to run input.
+ exec(cmd, runnerName) > Runs `cmd` with a runner. If `runnerName` isn't passed,
the current runner mode is used.

View File

@ -1,11 +1,4 @@
--- (This has mainly been replaced by [hilbish.jobs](../api/hilbish.jobs)).
title: Jobs
description: Controls for background commands in Hilbish.
layout: doc
menu:
docs:
parent: "Features"
---
Hilbish has pretty standard job control. It's missing one or two things, Hilbish has pretty standard job control. It's missing one or two things,
but works well. One thing which is different from other shells but works well. One thing which is different from other shells

View File

@ -1,70 +0,0 @@
Hilbish allows you to change how interactive text can be interpreted.
This is mainly due to the fact that the default method Hilbish uses
is that it runs Lua first and then falls back to shell script.
In some cases, someone might want to switch to just shell script to avoid
it while interactive but still have a Lua config, or go full Lua to use
Hilbish as a REPL. This also allows users to add alternative languages like
Fennel as the interactive script runner.
Runner mode can also be used to handle specific kinds of input before
evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh)
handles links.
The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`,
which determines how Hilbish will run user input. By default, this is
set to `hybrid` which is the previously mentioned behaviour of running Lua
first then going to shell script. If you want the reverse order, you can
set it to `hybridRev` and for isolated modes there is `sh` and `lua`
respectively.
You can also set it to a function, which will be called everytime Hilbish
needs to run interactive input. For example, you can set this to a simple
function to compile and evaluate Fennel, and now you can run Fennel.
You can even mix it with sh to make a hybrid mode with Lua replaced by
Fennel.
An example:
hilbish.runnerMode(function(input)
local ok = pcall(fennel.eval, input)
if ok then
return input, 0, nil
end
return hilbish.runner.sh(input)
end)
The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
and also provides the shell script and Lua runner functions that Hilbish itself uses.
A runner function is expected to return a table with the following values:
- `exitCode` (number): Exit code of the command
- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
more is requested.
- `err` (string): A string that represents an error from the runner.
This should only be set when, for example, there is a syntax error.
It can be set to a few special values for Hilbish to throw the right
hooks and have a better looking message.
- `<command>: not-found` will throw a `command.not-found` hook
based on what `<command>` is.
- `<command>: not-executable` will throw a `command.not-executable` hook.
- `continue` (boolean): Whether Hilbish should prompt the user for no input
## Functions
These are the "low level" functions for the `hilbish.runner` interface.
+ setMode(mode) > The same as `hilbish.runnerMode`
+ sh(input) -> table > Runs `input` in Hilbish's sh interpreter
+ lua(input) -> table > Evals `input` as Lua code
These functions should be preferred over the previous ones.
+ setCurrent(mode) > The same as `setMode`, but works with runners managed
via the functions below.
+ add(name, runner) > Adds a runner to a table of available runners. The `runner`
argument is either a function or a table with a run callback.
+ set(name, runner) > The same as `add` but requires passing a table and
overwrites if the `name`d runner already exists.
+ get(name) > runner > Gets a runner by name. It is a table with at least a
run function, to run input.
+ exec(cmd, runnerName) > Runs `cmd` with a runner. If `runnerName` isn't passed,
the current runner mode is used.

View File

@ -10,7 +10,7 @@ function bait.catch(name, cb) end
--- 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.
function bait.catchOnce(name, cb) end function bait.catchOnce(name, cb) end
--- Returns a list of callbacks that are hooked on an event with the corresponding `name`. --- Returns a table of functions that are hooked on an event with the corresponding `name`.
function bait.hooks(name) end function bait.hooks(name) end
--- Removes the `catcher` for the event with `name`. --- Removes the `catcher` for the event with `name`.

View File

@ -31,9 +31,7 @@ function fs.join(...path) end
--- Creates a new directory with the provided `name`. --- Creates a new directory with the provided `name`.
--- With `recursive`, mkdir will create parent directories. --- 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 function fs.mkdir(name, recursive) end
--- Returns a list of all files and directories in the provided path. --- Returns a list of all files and directories in the provided path.

View File

@ -61,13 +61,15 @@ function hilbish.alias(cmd, orig) end
function hilbish.appendPath(dir) end function hilbish.appendPath(dir) end
--- Registers a completion handler for the specified scope. --- Registers a completion handler for the specified scope.
--- A `scope` is currently only expected to be `command.<cmd>`, --- A `scope` is expected to be `command.<cmd>`,
--- replacing <cmd> with the name of the command (for example `command.git`). --- replacing <cmd> with the name of the command (for example `command.git`).
--- The documentation for completions, under Features/Completions or `doc completions` --- The documentation for completions, under Features/Completions or `doc completions`
--- provides more details. --- provides more details.
---
---
function hilbish.complete(scope, cb) end function hilbish.complete(scope, cb) end
--- Returns the current directory of the shell --- Returns the current directory of the shell.
function hilbish.cwd() end function hilbish.cwd() end
--- Replaces the currently running Hilbish instance with the supplied command. --- Replaces the currently running Hilbish instance with the supplied command.
@ -75,8 +77,9 @@ function hilbish.cwd() end
function hilbish.exec(cmd) end function hilbish.exec(cmd) end
--- Puts `fn` in a Goroutine. --- Puts `fn` in a Goroutine.
--- This can be used to run any function in another thread. --- This can be used to run any function in another thread at the same time as other Lua code.
--- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** --- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
--- **This is a limitation of the Lua runtime.**
function hilbish.goro(fn) end function hilbish.goro(fn) end
--- Line highlighter handler. --- Line highlighter handler.
@ -96,13 +99,13 @@ function hilbish.highlighter(line) end
--- ---
function hilbish.hinter(line, pos) end function hilbish.hinter(line, pos) end
--- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim. --- Sets the input mode for Hilbish's line reader.
--- `emacs` is the default. Setting it to `vim` changes behavior of input to be --- `emacs` is the default. Setting it to `vim` changes behavior of input to be
--- Vim-like with modes and Vim keybinds. --- Vim-like with modes and Vim keybinds.
function hilbish.inputMode(mode) end function hilbish.inputMode(mode) end
--- Runs the `cb` function every `time` milliseconds. --- Runs the `cb` function every specified amount of `time`.
--- This creates a timer that starts immediately. --- This creates a timer that ticking immediately.
function hilbish.interval(cb, time) end function hilbish.interval(cb, time) end
--- Changes the text prompt when Hilbish asks for more input. --- Changes the text prompt when Hilbish asks for more input.
@ -125,21 +128,23 @@ function hilbish.prompt(str, typ) end
--- Read input from the user, using Hilbish's line editor/input reader. --- Read input from the user, using Hilbish's line editor/input reader.
--- This is a separate instance from the one Hilbish actually uses. --- 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). --- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
function hilbish.read(prompt) end function hilbish.read(prompt) end
--- Runs `cmd` in Hilbish's shell script interpreter. --- Runs `cmd` in Hilbish's shell script interpreter.
function hilbish.run(cmd, returnOut) end function hilbish.run(cmd, returnOut) end
--- Sets the execution/runner mode for interactive Hilbish. This determines whether --- Sets the execution/runner mode for interactive Hilbish.
--- Hilbish wll try to run input as Lua and/or sh or only do one of either. --- 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), --- 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 --- sh, and lua. It also accepts a function, to which if it is passed one
--- will call it to execute user input instead. --- will call it to execute user input instead.
--- Read [about runner mode](../features/runner-mode) for more information.
function hilbish.runnerMode(mode) end function hilbish.runnerMode(mode) end
--- Runs the `cb` function after `time` in milliseconds. --- Executed the `cb` function after a period of `time`.
--- This creates a Timer that starts immediately. --- This creates a Timer that starts ticking immediately.
function hilbish.timeout(cb, time) end function hilbish.timeout(cb, time) end
--- Checks if `name` is a valid command. --- Checks if `name` is a valid command.

View File

@ -285,8 +285,8 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// hooks(name) -> table // hooks(name) -> table
// Returns a list of callbacks that are hooked on an event with the corresponding `name`. // Returns a table of functions that are hooked on an event with the corresponding `name`.
// #param name string The name of the function // #param name string The name of the hook
// #returns table<function> // #returns table<function>
func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {

View File

@ -198,6 +198,7 @@ func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-- This will create the directory foo, then create the directory bar in the -- 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. -- foo directory. If recursive is false in this case, it will fail.
fs.mkdir('./foo/bar', true) fs.mkdir('./foo/bar', true)
#example
*/ */
func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {

2
job.go
View File

@ -418,7 +418,7 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs. // used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
// #param cmdstr string String that a user would write for the job // #param cmdstr string String that a user would write for the job
// #param args table Arguments for the commands. Has to include the name of the command. // #param args table Arguments for the commands. Has to include the name of the command.
// #param execPath string Binary to use to run the command. Does not // #param execPath string Binary to use to run the command. Needs to be an absolute path.
/* /*
#example #example
hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go') hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')

View File

@ -8,11 +8,47 @@ import (
// #interface runner // #interface runner
// interactive command runner customization // interactive command runner customization
// The runner interface contains functions that allow the user to change /* The runner interface contains functions that allow the user to change
// how Hilbish interprets interactive input. how Hilbish interprets interactive input.
// Users can add and change the default runner for interactive input to any Users can add and change the default runner for interactive input to any
// language or script of their choosing. A good example is using it to language or script of their choosing. A good example is using it to
// write command in Fennel. write command in Fennel.
Runners are functions that evaluate user input. The default runners in
Hilbish can run shell script and Lua code.
A runner is passed the input and has to return a table with these values.
All are not required, only the useful ones the runner needs to return.
(So if there isn't an error, just omit `err`.)
- `exitCode` (number): A numerical code to indicate the exit result.
- `input` (string): The user input. This will be used to add
to the history.
- `err` (string): A string to indicate an interal error for the runner.
It can be set to a few special values for Hilbish to throw the right hooks and have a better looking message:
`[command]: not-found` will throw a command.not-found hook based on what `[command]` is.
`[command]: not-executable` will throw a command.not-executable hook.
- `continue` (boolean): Whether to prompt the user for more input.
Here is a simple example of a fennel runner. It falls back to
shell script if fennel eval has an error.
```lua
local fennel = require 'fennel'
hilbish.runnerMode(function(input)
local ok = pcall(fennel.eval, input)
if ok then
return {
input = input
}
end
return hilbish.runner.sh(input)
end)
```
*/
func runnerModeLoader(rtm *rt.Runtime) *rt.Table { func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
exports := map[string]util.LuaExport{ exports := map[string]util.LuaExport{
"sh": {shRunner, 1, false}, "sh": {shRunner, 1, false},

Binary file not shown.

View File

@ -0,0 +1,5 @@
<video src="{{ .Get "src" }}" style="height: auto; max-width: 100%;" controls>
There's a video missing here...
Well here is the URL: {{ .Get "src" }}
</video>