Crate gameshell

GameShell - A fast and lightweight shell for interactive work in Rust

GameShell is a little lisp-like command shell made to be embedded in rust programs. It has no runtime and attempts to call given handlers as fast as possible. This means that GameShell is made for one-time commands, where the heavy lifting is done in your specified handler functions. It does not do any JIT/compilation or bytecode conversion, but goes straight to a handler and calls it.

Language

The language is just

command argument (subcommand argument ...) (#literal string inside here) argument ...

If an opened parenthesis is not closed on a newline, the next line is also considered part of the command:

command (
    subcommand
    argument
    ...
) argument ...

Example

This example sets up a basic interpreter and a single handler for a single command. More commands and handlers can be added.

use gameshell::{
    predicates::*, types::Type, Evaluator, GameShell, IncConsumer,
};
use std::str::from_utf8;

fn main() {
    // This is the input stream, GameShell will handle anything that implements
    // std::io::Read, and will efficiently acquire data from such a stream.
    let read = b"Lorem ipsum 1.23\n";
    // This is the output stream, GameShell will use this to write messages out.
    let mut write = [0u8; 12];

    // A gameshell is created by supplying a context object (here 0u8), and an IO stream.
    let mut eval = GameShell::new(0u8, &read[..], &mut write[..]);

    // We then register command handler functions to GameShell, such that it can run commands
    // when reading from the input stream
    //
    // Each command handler takes a `&mut Context` (here u8), and a list of arguments.
    // It returns a result, `Ok` indicating a successful computation,
    // and an `Err` indicating an error, aborting any nested computation and writing out the
    // error message to the writer.
    fn handler(context: &mut u8, args: &[Type]) -> Result<String, String> {
        *context += 1;
        println!["Got types: {:?}", args[0]];
        Ok("Hello world!".into())
    }

    // Register the handler and associate it with the command "Lorem ipsum <f32>".
    // The first element in the pair is a string literal on which we match the command tree,
    // and the second argument is an arbitrary `Decider` which parses our input data into a
    // `Type`. Deciders can consume as many elements as they like.
    eval.register((&[("Lorem", None), ("ipsum", ANY_F32)], handler)).unwrap();

    // Run the command loop, keeps reading from the tcp buffer until the buffer has no more
    // elements. When reading from a `TcpStream` this call will block until the stream is
    // closed. The `buffer` provided here is the buffer for parsing a single incoming whole
    // command. If the command exceeds this size, the command will be discarded and the
    // connection severed.
    let buffer = &mut [0u8; 1024];
    eval.run(buffer);

    // Ensure that we have run at least once, our starting context was 0, which should now be 1
    assert_eq![1, *eval.context()];
    // Our Ok message has been written to the writer
    assert_eq!["Hello world!", from_utf8(&write[..]).unwrap()];
}

Why does a command handler return a string instead of a type?

Because nested commands may reinterpret the string in any way they like, according to an arbitrary decider. Thus, we can't return types. This is an inefficiency to allow for proper error checking in nested calls.

As unfortunate as that is, this library is not meant to sacrifice usability for speed. If you want speed, you can just collapse two commands into one and use a single handler, since pure Rust will always beat this library at speed.

Builtin commands

GameShell has 2 builtin commands:

?

List all registered commands and their potential arguments. An argument to this command will regex filter the output: ? lorem. and

autocomplete

Autocomplete a query.

These commands return strings that contain useful information to be displayed to the user.

Re-exports

pub use crate::evaluator::Evaluator;

pub use cmdmat;

Modules

evaluator	Core virtual machine used by GameShell
predicates	Contains pre-built predicates for use outside this library for creating command specifications.
types	Basic types used by the gameshell for input to handlers

Structs

GameShell	The main virtual machine wrapper for a game shell
PartialParse	A partial parse is a parse where we send single bytes into the parser and get back a complete parsing state. This is useful when reading TCP streams or other streams that may yield at any point in time.

Enums

PartialParseOp

Description of the parsing state

Traits

Evaluate	Interpreter trait
IncConsumer	Incremental consumer of bytes

Type Definitions

Feedback	Feedback provided by the interpreter. All results are either a success string or an error string.
Spec	The command specification format