sammyette
/
Hilbish
mirror of https://github.com/Hilbis/Hilbish
2
2
Fork 0
Code Issues Releases Wiki Activity

docs: minor changes and fixes

pull/260/head
sammyette 2023-12-25 22:48:25 -04:00
parent 85e1307e7d
commit 48ef443bb5
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
5 changed files with 56 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
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 {
@ -655,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
@ -683,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 {
@ -715,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.

43
docs/api/hilbish/_index.md
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
@ -162,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.
@ -196,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`**
@ -253,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
@ -273,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>
@ -292,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>
@ -401,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>
@ -438,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`**
@ -459,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>

2
docs/api/hilbish/hilbish.jobs.md
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

23
emmyLuaDocs/hilbish.lua
View File

@ -69,7 +69,7 @@ function hilbish.appendPath(dir) end
--- ---
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.
@ -77,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.
@ -98,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.
@ -127,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.

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')