5.7. Script interpreter

The hsh program is a Halon script interpreter and interactive shell (REPL). It allows you to easily write, run and test Halon script without having to deploy it into the smtpd server. It implements the full standard library, but not any smtpd server or queue hooks. It also doesn’t provide an interface for halonctl’s script commands.

5.7.1. Options

-c, --config path

In order to make the hsh script environment resemble the environment of smtpd, it supports loading smtpd’s startup configuration file (default /etc/halon/smtpd.yaml) which in turn load the running configuration. This allows all paths and permission to be set up correctly, as well as virtual files scripting.files[] and certificates pki.private[]. Since that file usually drop privileges and change user, it might require hsh -P to be run as root. If you don’t need the full environment, you may run without a startup configuration: /dev/null.

-P, --privdrop

Drop privileges (setuid / setgid) to the user specified in the startup configuration. This may allow you to have access to various sockets, but requires root permission. The recommended setup would be to have shared group permission with the smtpd server on various sockets and paths.

-F, --ffi

Enable FFI support, which is equivalent to scripting.ffi, without having to use hsh -c to load a startup a configuration.

-p, --plugin id

Load a specific HSL plugin. This option is repeatable.

-R, --rootpath path

Set the script root path, which is equivalent to scripting.rootpath, without having to use hsh -c to load a startup a configuration.

-A, --appconf path

Load a specific running configuration which is equivalent to environment.appconf, without having to use hsh -c to load a startup a configuration.

-B, --binary

Print output as binary (not as UTF-8), and also the output of echo will not automatically include a newline (\n).

-s, --syntax

Check the script syntax only.

-v, --version

Display Halon version and exit.

5.7.2. Script interpreter

The hsh program may be executed with a script file as the entry point for the script execution. It should be given as the last argument to the hsh command line.

$ cat test.hsl
echo "Hello World";
$ hsh test.hsl
Hello World

Setting the root to the current directory may be useful when implementing unit testing of modules:

$ cat module.hsl
function foo() {
   echo "Hello World";
}
$ cat test.hsl
import { foo } from "file://module.hsl";
foo();
$ hsh -R . test.hsl
Hello World

5.7.3. Interactive shell

The hsh program may be executed without a file, in which case it enters the interactive shell mode (REPL). Statements are executed line-by-line.

$ hsh
HSH> echo "Hello World";
Hello World
HSH>