[−][src]Module molt::interp
The Molt Interpreter
TODO: This should be primary documentation on using the Molt Interp.
The Interp
struct is the primary API for embedding Molt into a Rust application.
Given an Interp
, the application may:
- Evaluate scripts
- Check scripts for completeness
- Extend the language by defining new Molt commands in Rust
- Set and get Molt variables in command bodies
- Interpret Molt values as a variety of data types.
- Access application data the context cache
The following describes the features of the Interp
in general; follow the links for
specifics of the various types and methods.
Interp is not Sync!
The Interp
class (and the rest of Molt) is intended for use in a single thread. It is
safe to have multiple Interps
in different threads; but use String
(or another Sync
)
when passing data between them. In particular, Value
is not Sync
.
Creating an Interpreter
There are two ways to create an interpreter. The usual way is to call
Interp::new
, which creates an interpreter and populates
it with all of the standard Molt commands. Alternatively,
Interp::empty
creates an interpreter with no commands,
allowing the application to define only those commands it needs. This is useful when the goal
is to provide the application with a simple, non-scriptable console command set.
TODO: Define a way to add various subsets of the standard commands to an initially empty interpreter.
use molt::Interp; let mut interp = Interp::new(); // ...
Evaluating Scripts
There are a number of ways to evaluate Molt scripts, all of which return MoltResult
:
pub type MoltResult = Result<Value, ResultCode>;
Value
is the type of all Molt values (i.e., values that can be passed as parameters and
stored in variables). ResultCode
is an enum that encompasses all of the kinds of
exceptional return from Molt code, including errors, return
, break
, and continue
.
Interp::eval
and
Interp::eval_value
evaluate a string as a Molt
script, and return either a normal Value
or a Molt error. The script is evaluated in
the caller's context: if called at the application level, the script will be evaluated in
the interpreter's global scope; if called by a Molt command, it will be evaluated in the
scope in which that command is executing.
Interp::eval_body
is used to evaluate the body
of loops and other control structures. Unlike Interp::eval
, it passes the
return
, break
, and continue
result codes back to the caller for handling.
Evaluating Expressions
In Molt, as in Standard Tcl, algebraic expressions are evaluated by the expr
command. At
the Rust level this feature is provided by the
Interp::expr
method, which takes the expression as a
Value
and returns the computed Value
or an error.
There are three convenience methods,
Interp::expr_bool
,
Interp::expr_int
, and
Interp::expr_float
, which streamline the computation
of a particular kind of value, and return an error if the computed result is not of that type.
Checking Scripts for Completeness
The Interp::complete
checks whether a Molt script is
complete: i.e., that it contains no unterminated quoted or braced strings that
would prevent it from being evaluated as Molt code. This is primarily useful when
implementing a Read-Eval-Print-Loop, as it allows the REPL to easily determine whether it
should evaluate the input immediately or ask for an additional line of input.
Defining New Commands
The usual reason for embedding Molt in an application is to extend it with application-specific commands. There are a number of ways to do this.
The simplest method, and the one used by most of Molt's built-in commands, is to define a
CommandFunc
and register it with the interpreter using the
Interp::add_command
method:
pub type CommandFunc = fn(&mut Interp, &[Value]) -> MoltResult;
A CommandFunc
is simply a Rust function that accepts an interpreter and a slice of Molt
Value
objects and returns a MoltResult
. The slice of Value
objects represents
the name of the command and its arguments, which the function may interpret in any way it
desires.
TODO: describe context commands and command objects.
TODO: flesh out Molt's ensemble command API, and then describe how to define ensemble commands.
Structs
Interp | The Molt Interpreter. |