docs: add detailed description for commander

commander-stdout
sammyette 2023-01-20 19:03:41 -04:00
parent 4584d3be22
commit dd478b9c90
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
2 changed files with 70 additions and 1 deletions

View File

@ -8,7 +8,41 @@ menu:
--- ---
## Introduction ## Introduction
Commander is a library for writing custom commands in Lua. Commander is a library for writing custom commands in Lua.
In order to make it easier to write commands for Hilbish,
not require separate scripts and to be able to use in a config,
the Commander library exists. This is like a very simple wrapper
that works with Hilbish for writing commands. Example:
```lua
local commander = require 'commander'
commander.register('hello', function(args, sinks)
sinks.out:writeln 'Hello world!'
end)
```
In this example, a command with the name of `hello` is created
that will print `Hello world!` to output. One question you may
have is: What is the `sinks` parameter?
A sink is a writable/readable pipe, or you can imagine a Lua
file. It's used in this case to write to the proper output,
incase a user either pipes to another command or redirects somewhere else.
So, the `sinks` parameter is a table containing 3 sinks:
`in`, `out`, and `err`.
- `in` is the standard input. You can read from this sink
to get user input. (**This is currently unimplemented.**)
- `out` is standard output. This is usually where text meant for
output should go.
- `err` is standard error. This sink is for writing errors, as the
name would suggest.
A sink has 2 methods:
- `write(str)` will write to the sink.
- `writeln(str)` will write to the sink with a newline at the end.
## Functions ## Functions
### deregister(name) ### deregister(name)

View File

@ -1,5 +1,40 @@
// library for custom commands // library for custom commands
// Commander is a library for writing custom commands in Lua. /*
Commander is a library for writing custom commands in Lua.
In order to make it easier to write commands for Hilbish,
not require separate scripts and to be able to use in a config,
the Commander library exists. This is like a very simple wrapper
that works with Hilbish for writing commands. Example:
```lua
local commander = require 'commander'
commander.register('hello', function(args, sinks)
sinks.out:writeln 'Hello world!'
end)
```
In this example, a command with the name of `hello` is created
that will print `Hello world!` to output. One question you may
have is: What is the `sinks` parameter?
A sink is a writable/readable pipe, or you can imagine a Lua
file. It's used in this case to write to the proper output,
incase a user either pipes to another command or redirects somewhere else.
So, the `sinks` parameter is a table containing 3 sinks:
`in`, `out`, and `err`.
- `in` is the standard input. You can read from this sink
to get user input. (**This is currently unimplemented.**)
- `out` is standard output. This is usually where text meant for
output should go.
- `err` is standard error. This sink is for writing errors, as the
name would suggest.
A sink has 2 methods:
- `write(str)` will write to the sink.
- `writeln(str)` will write to the sink with a newline at the end.
*/
package commander package commander
import ( import (