Crate easy_repl

An easy to use REPL, ideal when there is a need to crate an ad-hoc shell.

This library provides a fast and convenient way to generate a REPL for your application. It comes with easy to use command! macro that will automatically validate and parse command arguments, doing all the type checking for you. The REPL comes with handy help messages, input validation, hints and TAB-completion. Many REPL features can be configured.

Example

This is a basic example corresponding to examples/minimal.rs. For more examples see the examples/ directory, which among others shows how to handle errors, access variables outside of handler closures and how to create REPL inside REPL, inside REPL, inside…

use easy_repl::{Repl, CommandStatus, command};

let mut repl = Repl::builder()
    .add("hello", command! {
        "Say hello",
        (name: String) => |name| {
            println!("Hello {}!", name);
            Ok(CommandStatus::Done)
        }
    })
    .add("add", command! {
        "Add X to Y",
        (X:i32, Y:i32) => |x, y| {
            println!("{} + {} = {}", x, y, x + y);
            Ok(CommandStatus::Done)
        }
    })
    .build().expect("Failed to create repl");

repl.run().expect("Critical REPL error");

The generated REPL can be used as:

> hello world
Hello world!

It comes with argument number checking…

> add 1
Error: wrong number of arguments: got 1, expected 2
Usage: add X:i32 Y:i32
> hello easy repl
Error: wrong number of arguments: got 2, expected 1
Usage: hello name:String
> hello "easy repl"
Hello easy repl!

…and type checking!

> add 1 world
Error: failed to parse argument value 'world': invalid digit found in string
Usage: add X:i32 Y:i32

It includes automatic help and quit commands. The help message is auto-generated:

> help
Available commands:
  add X:i32 Y:i32    Add X to Y
  hello name:String  Say hello

Other commands:
  help  Show this help message
  quit  Quit repl

By default user does not have to use full command names, if the command name can be resloved unambigiously (i.e. prefix matches only a single command), e.g.

> a 1 2
1 + 2 = 3

but if the input is ambigious, an error will be printed with command suggestions:

> h world
Command not found: h
Candidates:
  hello
  help
Use 'help' to see available commands.

The REPL also by default automatically implements command hints and TAB-completion (see rustyline::hint, rustyline::completion).

Re-exports

pub use command::Command;
pub use command::CommandStatus;
pub use command::Critical;
pub use command::CriticalError;
pub use repl::Repl;

Modules

command	Implementation of Commands with utilities that help to crate them.
repl	Main REPL logic.

Macros

command	Generate Command based on desctiption, list of arg types and a closure used in handler.
validator	Generate argument validator based on a list of types (used by command!).