mirror of
https://github.com/Hilbis/Hilbish
synced 2025-07-01 08:42:04 +00:00
fix: add docs, remove experiment changes
This commit is contained in:
parent
0d43142d5a
commit
2f79f4c56c
GPG Key ID:
904FC49417B44DCD
@ -30,6 +30,8 @@ interfaces and functions which directly relate to shell functionality.
|
||||
|<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
|
||||
|<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="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
|
||||
|<a href="#run">run(cmd, streams)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
|
||||
|
||||
## Static module fields
|
||||
|||
|
||||
@ -475,3 +477,65 @@ Writes data to a sink.
|
||||
#### writeln(str)
|
||||
Writes data to a sink with a newline at the end.
|
||||
|
||||
<hr>
|
||||
<div id='run'>
|
||||
<h4 class='heading'>
|
||||
hilbish.run(cmd, streams)
|
||||
<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
|
||||
`cmd` **`string`**
|
||||
|
||||
|
||||
`streams` **`table|boolean`**
|
||||
|
||||
|
||||
#### 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.
|
||||
**NOTE: This function is deprecated and will be removed in 3.0**
|
||||
Use `hilbish.runner.setCurrent` instead.
|
||||
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>
|
||||
|
||||
|
||||
67
docs/api/hilbish/hilbish.abbr.md
Normal file
67
docs/api/hilbish/hilbish.abbr.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Module hilbish.abbr
|
||||
description: command line abbreviations
|
||||
layout: doc
|
||||
menu:
|
||||
docs:
|
||||
parent: "API"
|
||||
---
|
||||
|
||||
|
||||
## Introduction
|
||||
The abbr module manages Hilbish abbreviations. These are words that can be replaced
|
||||
with longer command line strings when entered.
|
||||
As an example, `git push` can be abbreviated to `gp`. When the user types
|
||||
`gp` into the command line, after hitting space or enter, it will expand to `git push`.
|
||||
Abbreviations can be used as an alternative to aliases. They are saved entirely in the history
|
||||
Instead of the aliased form of the same command.
|
||||
|
||||
## Functions
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#remove">remove(abbr)</a>|Removes the named `abbr`.|
|
||||
|<a href="#add">add(abbr, expanded|function, opts)</a>|Adds an abbreviation. The `abbr` is the abbreviation itself,|
|
||||
<hr>
|
||||
<div id='add'>
|
||||
<h4 class='heading'>
|
||||
hilbish.abbr.add(abbr, expanded|function, opts)
|
||||
<a href="#add" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Adds an abbreviation. The `abbr` is the abbreviation itself,
|
||||
while `expanded` is what the abbreviation should expand to.
|
||||
It can be either a function or a string. If it is a function, it will expand to what
|
||||
the function returns.
|
||||
`opts` is a table that accepts 1 key: `anywhere`.
|
||||
`opts.anywhere` defines whether the abbr expands anywhere in the command line or not,
|
||||
whereas the default behavior is only at the beginning of the line
|
||||
#### Parameters
|
||||
`abbr` **`string`**
|
||||
|
||||
|
||||
`expanded|function` **`string`**
|
||||
|
||||
|
||||
`opts` **`table`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='remove'>
|
||||
<h4 class='heading'>
|
||||
hilbish.abbr.remove(abbr)
|
||||
<a href="#remove" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Removes the named `abbr`.
|
||||
#### Parameters
|
||||
`abbr` **`string`**
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
135
docs/api/hilbish/hilbish.messages.md
Normal file
135
docs/api/hilbish/hilbish.messages.md
Normal 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="#send">send(message)</a>|Sends a message.|
|
||||
|<a href="#readAll">readAll()</a>|Marks all messages as read.|
|
||||
|<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='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='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='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>
|
||||
|
||||
39
docs/api/hilbish/hilbish.processors.md
Normal file
39
docs/api/hilbish/hilbish.processors.md
Normal file
@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Module hilbish.processors
|
||||
description: No description.
|
||||
layout: doc
|
||||
menu:
|
||||
docs:
|
||||
parent: "API"
|
||||
---
|
||||
|
||||
<hr>
|
||||
<div id='add'>
|
||||
<h4 class='heading'>
|
||||
hilbish.processors.add()
|
||||
<a href="#add" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
<hr>
|
||||
<div id='execute'>
|
||||
<h4 class='heading'>
|
||||
hilbish.processors.execute()
|
||||
<a href="#execute" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
Run all command processors, in order by priority.
|
||||
It returns the processed command (which may be the same as the passed command)
|
||||
and a boolean which states whether to proceed with command execution.
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
@ -55,6 +55,15 @@ end)
|
||||
|||
|
||||
|----|----|
|
||||
|<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
|
||||
|<a href="#sh">sh()</a>|nil|
|
||||
|<a href="#setMode">setMode(mode)</a>|**NOTE: This function is deprecated and will be removed in 3.0**|
|
||||
|<a href="#setCurrent">setCurrent(name)</a>|Sets Hilbish's runner mode by name.|
|
||||
|<a href="#set">set(name, runner)</a>|*Sets* a runner by name. The difference between this function and|
|
||||
|<a href="#run">run(input, priv)</a>|Runs `input` with the currently set Hilbish runner.|
|
||||
|<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
|
||||
|<a href="#get">get(name)</a>|Get a runner by name.|
|
||||
|<a href="#exec">exec(cmd, runnerName)</a>|Executes `cmd` with a runner.|
|
||||
|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners.|
|
||||
|
||||
<hr>
|
||||
<div id='runner.lua'>
|
||||
@ -74,3 +83,165 @@ or `load`, but is appropriated for the runner interface.
|
||||
|
||||
</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='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>
|
||||
|
||||
<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='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='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='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='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='setMode'>
|
||||
<h4 class='heading'>
|
||||
hilbish.runner.setMode(mode)
|
||||
<a href="#setMode" 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='sh'>
|
||||
<h4 class='heading'>
|
||||
hilbish.runner.sh()
|
||||
<a href="#sh" class='heading-link'>
|
||||
<i class="fas fa-paperclip"></i>
|
||||
</a>
|
||||
</h4>
|
||||
|
||||
|
||||
#### Parameters
|
||||
This function has no parameters.
|
||||
</div>
|
||||
|
||||
|
||||
@ -95,16 +95,3 @@ end)
|
||||
bait.catch('command.not-executable', function(cmd)
|
||||
print(string.format('hilbish: %s: not executable', cmd))
|
||||
end)
|
||||
|
||||
print 'we are at the end'
|
||||
while true do
|
||||
print 'reading input'
|
||||
local ok, res = pcall(function() return hilbish.editor:read() end)
|
||||
if not ok then
|
||||
print(res)
|
||||
print(res == 'EOF')
|
||||
os.exit(0)
|
||||
end
|
||||
|
||||
print(ok, res)
|
||||
end
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user