sammyette/Hilbish
2
2
Fork 0
mirror of https://github.com/Hilbis/Hilbish synced 2025-04-07 14:13:22 +00:00
Code Issues Releases Wiki Activity

docs: attempt

Browse Source
This commit is contained in:
sammyette 2025-04-02 21:30:16 -04:00
parent 4ba285e74b
commit a2e23f1310
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
12 changed files with 604 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
cmd/docgen/docgen.go
View File

@ -202,6 +202,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
Tags: tags, Tags: tags,
} }
fmt.Println(typeName, parentMod, interfaces)
typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces} typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces}
return dps return dps
@ -320,7 +321,7 @@ provided by Hilbish.
os.Mkdir("emmyLuaDocs", 0777) os.Mkdir("emmyLuaDocs", 0777)
dirs := []string{"./"} dirs := []string{"./util", "./"}
filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error { filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error {
if !info.IsDir() { if !info.IsDir() {
return nil return nil
@ -347,7 +348,7 @@ provided by Hilbish.
pieces := []docPiece{} pieces := []docPiece{}
typePieces := []docPiece{} typePieces := []docPiece{}
mod := l mod := l
if mod == "main" { if mod == "main" || mod == "util" {
mod = "hilbish" mod = "hilbish"
} }
var hasInterfaces bool var hasInterfaces bool
@ -471,9 +472,12 @@ provided by Hilbish.
f, _ := os.Create(docPath) f, _ := os.Create(docPath)
f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription)) f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription))
typeTag, _ := regexp.Compile(`\B@\w+`) typeTag, _ := regexp.Compile(`\B@\w+`)
//fmt.Println(modu.Description)
modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(strings.Replace(modu.Description, "<", `\<`, -1), "{{\\<", "{{<", -1), func(typ string) string { modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(strings.Replace(modu.Description, "<", `\<`, -1), "{{\\<", "{{<", -1), func(typ string) string {
typName := typ[1:] typName := typ[1:]
fmt.Println("typ name", typName)
typLookup := typeTable[strings.ToLower(typName)] typLookup := typeTable[strings.ToLower(typName)]
fmt.Println(typLookup)
ifaces := typLookup[0] + "." + typLookup[1] + "/" ifaces := typLookup[0] + "." + typLookup[1] + "/"
if typLookup[1] == "" { if typLookup[1] == "" {
ifaces = "" ifaces = ""

95
docs/api/hilbish/_index.md
View File

@ -28,8 +28,6 @@ interfaces and functions which directly relate to shell functionality.
|<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, streams) -> 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.|
|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.| |<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.|
@ -408,72 +406,6 @@ Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
`string` **`prompt?`** `string` **`prompt?`**
Text to print before input, can be empty. Text to print before input, can be empty.
</div>
<hr>
<div id='run'>
<h4 class='heading'>
hilbish.run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
<a href="#run" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Runs `cmd` in Hilbish's shell script interpreter.
The `streams` parameter specifies the output and input streams the command should use.
For example, to write command output to a sink.
As a table, the caller can directly specify the standard output, error, and input
streams of the command with the table keys `out`, `err`, and `input` respectively.
As a boolean, it specifies whether the command should use standard output or return its output streams.
#### Parameters
`string` **`cmd`**
`table|boolean` **`streams`**
#### Example
```lua
// This code is the same as `ls -l | wc -l`
local fs = require 'fs'
local pr, pw = fs.pipe()
hilbish.run('ls -l', {
stdout = pw,
stderr = pw,
})
pw:close()
hilbish.run('wc -l', {
stdin = pr
})
```
</div>
<hr>
<div id='runnerMode'>
<h4 class='heading'>
hilbish.runnerMode(mode)
<a href="#runnerMode" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Sets the execution/runner mode for interactive Hilbish.
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),
sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead.
Read [about runner mode](../features/runner-mode) for more information.
#### Parameters
`string|function` **`mode`**
</div> </div>
<hr> <hr>
@ -515,30 +447,3 @@ Will return the path of the binary, or a basename if it's a commander.
</div> </div>
## Types
<hr>
## Sink
A sink is a structure that has input and/or output to/from
a desination.
### Methods
#### autoFlush(auto)
Sets/toggles the option of automatically flushing output.
A call with no argument will toggle the value.
#### flush()
Flush writes all buffered input to the sink.
#### read() -> string
Reads a liine of input from the sink.
#### readAll() -> string
Reads all input from the sink.
#### write(str)
Writes data to a sink.
#### writeln(str)
Writes data to a sink with a newline at the end.

135
docs/api/hilbish/hilbish.messages.md Normal file
View File

@ -0,0 +1,135 @@
---
title: Module hilbish.messages
description: simplistic message passing
layout: doc
menu:
docs:
parent: "API"
---
## Introduction
The messages interface defines a way for Hilbish-integrated commands,
user config and other tasks to send notifications to alert the user.z
The `hilbish.message` type is a table with the following keys:
`title` (string): A title for the message notification.
`text` (string): The contents of the message.
`channel` (string): States the origin of the message, `hilbish.*` is reserved for Hilbish tasks.
`summary` (string): A short summary of the `text`.
`icon` (string): Unicode (preferably standard emoji) icon for the message notification
`read` (boolean): Whether the full message has been read or not.
## Functions
|||
|----|----|
|<a href="#unreadCount">unreadCount()</a>|Returns the amount of unread messages.|
|<a href="#readAll">readAll()</a>|Marks all messages as read.|
|<a href="#send">send(message)</a>|Sends a message.|
|<a href="#read">read(idx)</a>|Marks a message at `idx` as read.|
|<a href="#delete">delete(idx)</a>|Deletes the message at `idx`.|
|<a href="#clear">clear()</a>|Deletes all messages.|
|<a href="#all">all()</a>|Returns all messages.|
<hr>
<div id='all'>
<h4 class='heading'>
hilbish.messages.all()
<a href="#all" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Returns all messages.
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='clear'>
<h4 class='heading'>
hilbish.messages.clear()
<a href="#clear" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Deletes all messages.
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='delete'>
<h4 class='heading'>
hilbish.messages.delete(idx)
<a href="#delete" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Deletes the message at `idx`.
#### Parameters
`idx` **`number`**
</div>
<hr>
<div id='read'>
<h4 class='heading'>
hilbish.messages.read(idx)
<a href="#read" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Marks a message at `idx` as read.
#### Parameters
`idx` **`number`**
</div>
<hr>
<div id='send'>
<h4 class='heading'>
hilbish.messages.send(message)
<a href="#send" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Sends a message.
#### Parameters
`message` **`hilbish.message`**
</div>
<hr>
<div id='readAll'>
<h4 class='heading'>
hilbish.messages.readAll()
<a href="#readAll" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Marks all messages as read.
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='unreadCount'>
<h4 class='heading'>
hilbish.messages.unreadCount()
<a href="#unreadCount" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Returns the amount of unread messages.
#### Parameters
This function has no parameters.
</div>

166
docs/api/hilbish/hilbish.runner.md
View File

@ -54,29 +54,15 @@ end)
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
|<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
|<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.| |<a href="#exec">exec(cmd, runnerName)</a>|Executes `cmd` with a runner.|
|<a href="#set">set(name, runner)</a>|*Sets* a runner by name. The difference between this function and|
<hr> |<a href="#get">get(name)</a>|Get a runner by name.|
<div id='runner.setMode'> |<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners.|
<h4 class='heading'> |<a href="#setCurrent">setCurrent(name)</a>|Sets Hilbish's runner mode by name.|
hilbish.runner.setMode(cb) |<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
<a href="#runner.setMode" class='heading-link'> |<a href="#run">run(input, priv)</a>|Runs `input` with the currently set Hilbish runner.|
<i class="fas fa-paperclip"></i> |<a href="#sh">sh()</a>|nil|
</a>
</h4>
This is the same as the `hilbish.runnerMode` function.
It takes a callback, which will be used to execute all interactive input.
In normal cases, neither callbacks should be overrided by the user,
as the higher level functions listed below this will handle it.
#### Parameters
`function` **`cb`**
</div>
<hr> <hr>
<div id='runner.lua'> <div id='runner.lua'>
@ -97,19 +83,143 @@ or `load`, but is appropriated for the runner interface.
</div> </div>
<hr> <hr>
<div id='runner.sh'> <div id='sh'>
<h4 class='heading'> <h4 class='heading'>
hilbish.runner.sh(cmd) hilbish.runner.sh()
<a href="#runner.sh" class='heading-link'> <a href="#sh" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Runs a command in Hilbish's shell script interpreter.
This is the equivalent of using `source`.
#### Parameters #### Parameters
`string` **`cmd`** This function has no parameters.
</div>
<hr>
<div id='run'>
<h4 class='heading'>
hilbish.runner.run(input, priv)
<a href="#run" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Runs `input` with the currently set Hilbish runner.
This method is how Hilbish executes commands.
`priv` is an optional boolean used to state if the input should be saved to history.
#### Parameters
`input` **`string`**
`priv` **`bool`**
</div>
<hr>
<div id='getCurrent'>
<h4 class='heading'>
hilbish.runner.getCurrent()
<a href="#getCurrent" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Returns the current runner by name.
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='setCurrent'>
<h4 class='heading'>
hilbish.runner.setCurrent(name)
<a href="#setCurrent" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Sets Hilbish's runner mode by name.
#### Parameters
`name` **`string`**
</div>
<hr>
<div id='add'>
<h4 class='heading'>
hilbish.runner.add(name, runner)
<a href="#add" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Adds a runner to the table of available runners.
If runner is a table, it must have the run function in it.
#### Parameters
`name` **`string`**
Name of the runner
`runner` **`function|table`**
</div>
<hr>
<div id='get'>
<h4 class='heading'>
hilbish.runner.get(name)
<a href="#get" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Get a runner by name.
#### Parameters
`name` **`string`**
Name of the runner to retrieve.
</div>
<hr>
<div id='set'>
<h4 class='heading'>
hilbish.runner.set(name, runner)
<a href="#set" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
*Sets* a runner by name. The difference between this function and
add, is set will *not* check if the named runner exists.
The runner table must have the run function in it.
#### Parameters
`name` **`string`**
`runner` **`table`**
</div>
<hr>
<div id='exec'>
<h4 class='heading'>
hilbish.runner.exec(cmd, runnerName)
<a href="#exec" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Executes `cmd` with a runner.
If `runnerName` is not specified, it uses the default Hilbish runner.
#### Parameters
`cmd` **`string`**
`runnerName` **`string?`**
</div> </div>

120
docs/api/snail.md Normal file
View File

@ -0,0 +1,120 @@
---
title: Module snail
description: shell script interpreter library
layout: doc
menu:
docs:
parent: "API"
---
## Introduction
The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
It's not very useful other than running shell scripts, which can be done with other
Hilbish functions.
## Functions
|||
|----|----|
|<a href="#handleStream"></a>||
|<a href="#loaderFunc"></a>||
|<a href="#snailUserData"></a>||
|<a href="#snew">new() -> @Snail</a>|Creates a new Snail instance.|
|<a href="#splitInput"></a>||
|<a href="#Run"></a>||
<hr>
<div id='handleStream'>
<h4 class='heading'>
snail.
<a href="#handleStream" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='loaderFunc'>
<h4 class='heading'>
snail.
<a href="#loaderFunc" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='snailUserData'>
<h4 class='heading'>
snail.
<a href="#snailUserData" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='snew'>
<h4 class='heading'>
snail.new() -> <a href="/Hilbish/docs/api/snail/#snail" style="text-decoration: none;" id="lol">Snail</a>
<a href="#snew" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Creates a new Snail instance.
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='splitInput'>
<h4 class='heading'>
snail.
<a href="#splitInput" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
#### Parameters
This function has no parameters.
</div>
<hr>
<div id='Run'>
<h4 class='heading'>
snail.
<a href="#Run" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
#### Parameters
This function has no parameters.
</div>
## Types
<hr>
## Snail
A Snail is a shell script interpreter instance.
### Methods
#### run(command, streams)
Runs a shell command. Works the same as `hilbish.run`.

53
docs/nature/hilbish.md Normal file
View File

@ -0,0 +1,53 @@
---
title: Module hilbish
description: No description.
layout: doc
menu:
docs:
parent: "Nature"
---
<hr>
<div id='runner'>
<h4 class='heading'>
hilbish.runner(mode)
<a href="#runner" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
**NOTE: This function is deprecated and will be removed in 3.0**
Use `hilbish.runner.setCurrent` instead.
This is the same as the `hilbish.runnerMode` function.
It takes a callback, which will be used to execute all interactive input.
Or a string which names the runner mode to use.
#### Parameters
`mode` **`string|function`**
</div>
<hr>
<div id='runnerMode'>
<h4 class='heading'>
hilbish.runnerMode(mode)
<a href="#runnerMode" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
**NOTE: This function is deprecated and will be removed in 3.0**
Use `hilbish.runner.setCurrent` instead.
Sets the execution/runner mode for interactive Hilbish.
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),
sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead.
Read [about runner mode](../features/runner-mode) for more information.
#### Parameters
`mode` **`string|function`**
</div>

72
emmyLuaDocs/hilbish.lua
View File

@ -2,17 +2,33 @@
local hilbish = {} local hilbish = {}
--- Sets/toggles the option of automatically flushing output.
--- A call with no argument will toggle the value.
--- @param auto boolean|nil
function hilbish:autoFlush(auto) end
--- Flush writes all buffered input to the sink.
function hilbish:flush() end
--- Reads a liine of input from the sink.
--- @returns string
function hilbish:read() end
--- Reads all input from the sink.
--- @returns string
function hilbish:readAll() end
--- Writes data to a sink.
function hilbish:write(str) end
--- Writes data to a sink with a newline at the end.
function hilbish:writeln(str) end
--- This is an alias (ha) for the [hilbish.alias](../#alias) function. --- This is an alias (ha) for the [hilbish.alias](../#alias) function.
--- @param alias string --- @param alias string
--- @param cmd string --- @param cmd string
function hilbish.aliases.add(alias, cmd) end function hilbish.aliases.add(alias, cmd) end
--- This is the same as the `hilbish.runnerMode` function.
--- It takes a callback, which will be used to execute all interactive input.
--- In normal cases, neither callbacks should be overrided by the user,
--- as the higher level functions listed below this will handle it.
function hilbish.runner.setMode(cb) end
--- Returns the current input line. --- Returns the current input line.
function hilbish.editor.getLine() end function hilbish.editor.getLine() end
@ -131,24 +147,6 @@ function hilbish.prompt(str, typ) end
--- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs. --- 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.
--- The `streams` parameter specifies the output and input streams the command should use.
--- For example, to write command output to a sink.
--- As a table, the caller can directly specify the standard output, error, and input
--- streams of the command with the table keys `out`, `err`, and `input` respectively.
--- As a boolean, it specifies whether the command should use standard output or return its output streams.
---
function hilbish.run(cmd, streams) end
--- Sets the execution/runner mode for interactive Hilbish.
--- 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),
--- sh, and lua. It also accepts a function, to which if it is passed one
--- will call it to execute user input instead.
--- Read [about runner mode](../features/runner-mode) for more information.
function hilbish.runnerMode(mode) end
--- Executed the `cb` function after a period of `time`. --- Executed the `cb` function after a period of `time`.
--- This creates a Timer that starts ticking immediately. --- This creates a Timer that starts ticking immediately.
function hilbish.timeout(cb, time) end function hilbish.timeout(cb, time) end
@ -168,28 +166,6 @@ function hilbish.jobs:foreground() end
--- or `load`, but is appropriated for the runner interface. --- or `load`, but is appropriated for the runner interface.
function hilbish.runner.lua(cmd) end function hilbish.runner.lua(cmd) end
--- Sets/toggles the option of automatically flushing output.
--- A call with no argument will toggle the value.
--- @param auto boolean|nil
function hilbish:autoFlush(auto) end
--- Flush writes all buffered input to the sink.
function hilbish:flush() end
--- Reads a liine of input from the sink.
--- @returns string
function hilbish:read() end
--- Reads all input from the sink.
--- @returns string
function hilbish:readAll() end
--- Writes data to a sink.
function hilbish:write(str) end
--- Writes data to a sink with a newline at the end.
function hilbish:writeln(str) end
--- Starts running the job. --- Starts running the job.
function hilbish.jobs:start() end function hilbish.jobs:start() end
@ -200,10 +176,6 @@ function hilbish.jobs:stop() end
--- It will throw if any error occurs. --- It will throw if any error occurs.
function hilbish.module.load(path) end function hilbish.module.load(path) end
--- Runs a command in Hilbish's shell script interpreter.
--- This is the equivalent of using `source`.
function hilbish.runner.sh(cmd) end
--- Starts a timer. --- Starts a timer.
function hilbish.timers:start() end function hilbish.timers:start() end

26
emmyLuaDocs/snail.lua Normal file
View File

@ -0,0 +1,26 @@
--- @meta
local snail = {}
---
function snail. end
---
function snail. end
---
function snail. end
--- Creates a new Snail instance.
function snail.new() end
---
function snail. end
--- Runs a shell command. Works the same as `hilbish.run`.
function snail:run(command, streams) end
---
function snail. end
return snail

83
emmyLuaDocs/util.lua Normal file
View File

@ -0,0 +1,83 @@
--- @meta
local util = {}
---
function util.AbbrevHome changes the user's home directory in the path string to ~ (tilde) end
---
function util. end
---
function util.DoFile runs the contents of the file in the Lua runtime. end
---
function util.DoString runs the code string in the Lua runtime. end
--- directory.
function util.ExpandHome expands ~ (tilde) in the path, changing it to the user home end
---
function util. end
---
function util.ForEach loops through a Lua table. end
---
function util. end
--- a string and a closure.
function util.HandleStrCallback handles function parameters for Go functions which take end
---
function util. end
---
function util. end
---
function util.SetExports puts the Lua function exports in the table. end
--- It is accessible via the __docProp metatable. It is a table of the names of the fields.
function util.SetField sets a field in a table, adding docs for it. end
--- is one which has a metatable proxy to ensure no overrides happen to it.
--- It sets the field in the table and sets the __docProp metatable on the
--- user facing table.
function util.SetFieldProtected sets a field in a protected table. A protected table end
--- Sets/toggles the option of automatically flushing output.
--- A call with no argument will toggle the value.
--- @param auto boolean|nil
function util:autoFlush(auto) end
--- Flush writes all buffered input to the sink.
function util:flush() end
---
function util. end
--- Reads a liine of input from the sink.
--- @returns string
function util:read() end
--- Reads all input from the sink.
--- @returns string
function util:readAll() end
--- Writes data to a sink.
function util:write(str) end
--- Writes data to a sink with a newline at the end.
function util:writeln(str) end
---
function util. end
---
function util. end
---
function util. end
return util

19
golibs/snail/lua.go
View File

@ -1,3 +1,9 @@
// shell script interpreter library
/*
The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
It's not very useful other than running shell scripts, which can be done with other
Hilbish functions.
*/
package snail package snail
import ( import (
@ -48,11 +54,16 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
return rt.TableValue(mod), nil return rt.TableValue(mod), nil
} }
// new() -> @Snail
// Creates a new Snail instance.
func snew(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func snew(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
s := New(t.Runtime) s := New(t.Runtime)
return c.PushingNext1(t.Runtime, rt.UserDataValue(snailUserData(s))), nil return c.PushingNext1(t.Runtime, rt.UserDataValue(snailUserData(s))), nil
} }
// #member
// run(command, streams)
// Runs a shell command. Works the same as `hilbish.run`.
func srun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func srun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -157,7 +168,7 @@ func handleStream(v rt.Value, strms *util.Streams, errStream, inStream bool) err
return nil return nil
} }
func snailArg(c *rt.GoCont, arg int) (*snail, error) { func snailArg(c *rt.GoCont, arg int) (*Snail, error) {
s, ok := valueToSnail(c.Arg(arg)) s, ok := valueToSnail(c.Arg(arg))
if !ok { if !ok {
return nil, fmt.Errorf("#%d must be a snail", arg + 1) return nil, fmt.Errorf("#%d must be a snail", arg + 1)
@ -166,17 +177,17 @@ func snailArg(c *rt.GoCont, arg int) (*snail, error) {
return s, nil return s, nil
} }
func valueToSnail(val rt.Value) (*snail, bool) { func valueToSnail(val rt.Value) (*Snail, bool) {
u, ok := val.TryUserData() u, ok := val.TryUserData()
if !ok { if !ok {
return nil, false return nil, false
} }
s, ok := u.Value().(*snail) s, ok := u.Value().(*Snail)
return s, ok return s, ok
} }
func snailUserData(s *snail) *rt.UserData { func snailUserData(s *Snail) *rt.UserData {
snailMeta := s.runtime.Registry(snailMetaKey) snailMeta := s.runtime.Registry(snailMetaKey)
return rt.NewUserData(s, snailMeta.AsTable()) return rt.NewUserData(s, snailMeta.AsTable())
} }

11
golibs/snail/snail.go
View File

@ -1,4 +1,3 @@
// shell script interpreter library
package snail package snail
import ( import (
@ -23,21 +22,23 @@ import (
"mvdan.cc/sh/v3/expand" "mvdan.cc/sh/v3/expand"
) )
type snail struct{ // #type
// A Snail is a shell script interpreter instance.
type Snail struct{
runner *interp.Runner runner *interp.Runner
runtime *rt.Runtime runtime *rt.Runtime
} }
func New(rtm *rt.Runtime) *snail { func New(rtm *rt.Runtime) *Snail {
runner, _ := interp.New() runner, _ := interp.New()
return &snail{ return &Snail{
runner: runner, runner: runner,
runtime: rtm, runtime: rtm,
} }
} }
func (s *snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){ func (s *Snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){
file, err := syntax.NewParser().Parse(strings.NewReader(cmd), "") file, err := syntax.NewParser().Parse(strings.NewReader(cmd), "")
if err != nil { if err != nil {
return false, nil, nil, err return false, nil, nil, err

1
nature/snail.lua
View File

@ -3,7 +3,6 @@ local snail = require 'snail'
hilbish.snail = snail.new() hilbish.snail = snail.new()
--- run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
--- Runs `cmd` in Hilbish's shell script interpreter. --- Runs `cmd` in Hilbish's shell script interpreter.
--- The `streams` parameter specifies the output and input streams the command should use. --- The `streams` parameter specifies the output and input streams the command should use.
--- For example, to write command output to a sink. --- For example, to write command output to a sink.