# 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: `in`, `out`, and `err`. All of them are a Sink.

- `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,

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