Compilation

The Ferret compiler is also written entirely in Perl. Compilation is a
multi-stage process.

Stages

1. Tokenizer

The source code is tokenized into a flat list of labels and values. This step
involves very minimal error checking. In fact, the only error that can occur
during this process is a failure to tokenize a certain byte or string.

2. Constructor

The most significant step is the construction of the document model. The
tokens are processed into a hierarchical tree of elements. Elements are
represented by Perl objects which may belong to several categories such as
List, Node, Expression, etc. Throughout this process, the constructor is
checking that grammatical rules are met and aborts compilation if it
encounters nonsense.

(Un)expected elements

Hopefully, the error message is descriptive enough for you to find the issue.
If not, it helps to know a little Perl. Ferret will tell you where the
exception occurred in the compiler's Perl source code. That may help you nail
it down.

If the error says it was raised by a rule, it will provide the name of the rule.
Eventually, all rules will be documented, but for the time being, it may be
helpful to manually check the rule definition to see what it means.

Let's say, for example, that you wrote $x = 1 1 and got an error message
which ends with Exception raised by rule Instruction[0]. This is because there
is a rule that says instructions can only contain one element. You could then
search Rules.pm and
Constructor.pm for Instruction[0].

Compiler process "exited prematurely"

The Ferret compiler is multi-process and asynchronous. Put another way, the
ferret executable is more like make than cc. These errors occur when a
child process exits unexpectedly, but the parent process survives it.

Try running ferret with the -y flag. This tells the compiler to use only
one process and one thread. Usually it will then provide a Perl error message.