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 certificatespki.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 usehsh -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 usehsh -c
to load a startup a configuration.
- -A, --appconf path
Load a specific running configuration which is equivalent to
environment.appconf
, without having to usehsh -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>