Module commander

library for custom commands

Introduction

Commander is the library which handles Hilbish commands. This makes the user able to add Lua-written commands to their shell without making a separate script in a bin folder. Instead, you may simply use the Commander library in your Hilbish config.

1local commander = require 'commander'
2
3commander.register('hello', function(args, sinks)
4	sinks.out:writeln 'Hello world!'
5end)

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?

The sinks parameter is a table with 3 keys: input, out, and err. There is an in alias to input, but it requires using the string accessor syntax (sinks['in']) as in is also a Lua keyword, so input is preferred for use. All of them are a Sink. In the future, sinks.in will be removed.

  • in is the standard input. You may use the read functions on this sink to get input from the user.
  • out is standard output. This is usually where command output should go.
  • err is standard error. This sink is for writing errors, as the name would suggest.

Functions

deregister(name)Removes the named command. Note that this will only remove Commander-registered commands.
register(name, cb)Adds a new command with the given name. When Hilbish has to run a command with a name,
registry() -> tableReturns all registered commanders. Returns a list of tables with the following keys:

commander.deregister(name)

Removes the named command. Note that this will only remove Commander-registered commands.

Parameters

string name
Name of the command to remove.


commander.register(name, cb)

Adds a new command with the given name. When Hilbish has to run a command with a name,
it will run the function providing the arguments and sinks.

Parameters

string name
Name of the command

function cb
Callback to handle command invocation

Example
1-- When you run the command `hello` in the shell, it will print `Hello world`.
2-- If you run it with, for example, `hello Hilbish`, it will print 'Hello Hilbish'
3commander.register('hello', function(args, sinks)
4	local name = 'world'
5	if #args > 0 then name = args[1] end
6
7	sinks.out:writeln('Hello ' .. name)
8end)

commander.registry() -> table

Returns all registered commanders. Returns a list of tables with the following keys:

  • exec: The function used to run the commander. Commanders require args and sinks to be passed.
Parameters

This function has no parameters.