.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright 2021 Filip Strömbäck <filip@fprg.se>,
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH STORM 1 "October 15 2023"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
storm - a language system for extensible languages
.SH SYNOPSIS
.B storm
[\fIoptions\fR] [\-l \fIlanguage\fR] [\fIpath\fR] [--] <\fIarguments\fR>
.br
.rj
Launch an interactive REPL.
.br
.B storm
[\fIfile/directory\fR]
.br
.rj
Import file as package, try to run \fImain\fR.
.br
.B storm
[\fIoptions\fR] \-f \fIfunction\fR
.br
.rj
Run a function and exit.
.br
.B storm
[\fIoptions\fR] \-t/\-T \fIpackage\fR
.br
.rj
Run tests in the specified package and exit.
.br
.B storm
[\fIoptions\fR] \-c \fIexpr\fR
.br
.rj
Evaluate the expression \fIexpr\fR and exit.
.br
.B storm
\-\-server
.br
.rj
Start the language server.
.br
.B storm
.RI \-\-version
.br
.rj
Print version information and exit.
.br
.B storm
.RI \-\-help
.br
.rj
Print help on command-line options and exit.
.SH DESCRIPTION
Storm itself is a language system for extensible languages. It is
bundled with two languages, the general purpose language Basic Storm
and the syntax language for specifying context-free grammars. Normal
usage of Storm is typically confined to the lanugage Basic Storm.
.PP
The easiest way to get started with Storm is to launch the interactive
REPL:
.sp 1
.RS
$ \fBstorm\fR
.br
bs> \fB"Testing: " + 1.toS\fR
.br
=> Testing: 1
.RE
.sp 1
To write programs, create a file, \fImyprogram.bs\fR for example, and
write code there. It can then be loaded as follows:
.sp 1
.RS
$ \fBstorm myprogram.bs\fR
.br
bs> \fBuse myprogram\fR
.br
using myprogram
.br
bs> \fBmain()\fR
.br
\[char46]..
.RE
.sp 1
As the above example attempts illustrate, this loads the contents
of the file into the package \fImyprogram\fR. That package may then be
imported and functions may be executed from there. To execute the
functions automatically, one can invoke storm as follows:
.sp 1
.RS
$ \fBstorm myprogram.bs \-f myprogram.main\fR
.RE
.sp 1
For larger programs, it is useful to put all files inside a directory
and point storm to the directory rather than an individual file. In
that case, the entire directory will be loaded as a package.
.PP
If the \fI\-i\fR flag is not used to specify imports (as above), Storm
will automatically try to execute the \fImain\fR function in the
imported package(s). As such, the above example can be simplified
further as follows:
.sp 1
.RS
$ \fBstorm myprogram.bs\fR
.RE
.sp 1
If a double dash is present (\fI--\fR), then any parameters that appear
after the double dash are treated as parameters to the Storm program,
and are made available to the Storm program without further processing.
.sp 1
.SH OPTIONS
\fBstorm\fP recognizes the following command-line options.
.TP
.B \-l \fIlanguage\fR
Launch the interactive REPL for \fIlanguage\fR. The default is to
launch the \fIbs\fR REPL.
.TP
.B \-f \fIfunction\fR
Execute \fIfunction\fR. The function may not require any formal
parameters.
.TP
.B \-c \fIexpr\fR
Evaluate \fIexpr\fR in the specified REPL.
.TP
.B \-t \fIpackage\fR
Execute all tests in \fIpackage\fR.
.TP
.B \-T \fIpackage\fR
Execute all tests in \fIpackage\fR and any sub-packages.
.TP
.B \-i \fIpath\fR
Import the directory or file \fIpath\fR as a package in the root
namespace.
.TP
.B \-I \fIname\fR \fIpath\fR
Import the directory \fIpath\fR as a package with the name \fIname\fR.
.TP
.B \-r \fIpath\fR
Use the directory \fIpath\fR as the root of the namespace in Storm. By
default /usr/lib/storm is used.
.TP
.B \-\-version
Print version information.
.TP
.B \-\-server
Launch the language server. Communicates with an editor using
stdin/stdout using a binary protocol.
.TP
.B \-\-help
Print a summary of command-line options.
.SH SEE ALSO
For further information about Storm, see:
.UR https://storm-lang.org/
.UE