Struct ReplBuilder

pub struct ReplBuilder<'a> { /* private fields */ }

Builder pattern implementation for Repl.

All setter methods take owned self so the calls can be chained, for example:

let repl = Repl::builder()
    .description("My REPL")
    .prompt("repl> ")
    .build()
    .expect("Failed to build REPL");

Implementations

impl<'a> ReplBuilder<'a>

pub fn description<T: Into<String>>(self, v: T) -> Self

Repl description shown in Repl::help. Defaults to an empty string.

Examples found in repository

examples/mut_state.rs (line 9)

fn main() -> anyhow::Result<()> {
    let mut outside_x = String::from("Out x");
    let mut outside_y = String::from("Out y");

    let mut repl = Repl::builder()
        .description("Example REPL")
        .prompt("=> ")
        .text_width(60 as usize)
        .add("count", command! {
            "Count from X to Y",
            (X:i32, Y:i32) => |x, y| {
                for i in x..=y {
                    print!(" {}", i);
                }
                println!();
                Ok(CommandStatus::Done)
            }
        })
        .add("say", command! {
            "Say X",
            (:f32) => |x| {
                println!("x is equal to {}", x);
                Ok(CommandStatus::Done)
            },
        })
        .add("outx", command! {
            "Use mutably outside var x. This command has a really long description so we need to wrap it somehow, it is interesting how actually the wrapping will be performed.",
            () => || {
                outside_x += "x";
                println!("{}", outside_x);
                Ok(CommandStatus::Done)
            },
        })
        // this shows how to create Command manually with the help of the validator! macro
        // one could also implement arguments validation manually
        .add("outy", easy_repl::Command {
            description: "Use mutably outside var y".into(),
            args_info: vec!["appended".into()],
            handler: Box::new(|args| {
                let validator = validator!(i32);
                validator(args)?;
                outside_y += args[0];
                println!("{}", outside_y);
                Ok(CommandStatus::Done)
            }),
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

pub fn prompt<T: Into<String>>(self, v: T) -> Self

Prompt string, defaults to "> ".

Examples found in repository

examples/matryoshka.rs (line 19)

fn matryoshka(name: String) -> anyhow::Result<Repl<'static>> {
    let prompt = format!("{}> ", name);

    let cloned_prompt = prompt.clone();  // need to move it into closure
    let new = command! {
        "Enter new repl",
        (name:String) => |name: String| {
            let name = cloned_prompt.clone() + &name;
            let mut repl = matryoshka(name)?;
            repl.run()?;
            Ok(CommandStatus::Done)
        }
    };

    let repl = Repl::builder()
        .prompt(prompt)
        .add("new", new)
        .build()?;

    Ok(repl)
}

examples/mut_state.rs (line 10)

fn main() -> anyhow::Result<()> {
    let mut outside_x = String::from("Out x");
    let mut outside_y = String::from("Out y");

    let mut repl = Repl::builder()
        .description("Example REPL")
        .prompt("=> ")
        .text_width(60 as usize)
        .add("count", command! {
            "Count from X to Y",
            (X:i32, Y:i32) => |x, y| {
                for i in x..=y {
                    print!(" {}", i);
                }
                println!();
                Ok(CommandStatus::Done)
            }
        })
        .add("say", command! {
            "Say X",
            (:f32) => |x| {
                println!("x is equal to {}", x);
                Ok(CommandStatus::Done)
            },
        })
        .add("outx", command! {
            "Use mutably outside var x. This command has a really long description so we need to wrap it somehow, it is interesting how actually the wrapping will be performed.",
            () => || {
                outside_x += "x";
                println!("{}", outside_x);
                Ok(CommandStatus::Done)
            },
        })
        // this shows how to create Command manually with the help of the validator! macro
        // one could also implement arguments validation manually
        .add("outy", easy_repl::Command {
            description: "Use mutably outside var y".into(),
            args_info: vec!["appended".into()],
            handler: Box::new(|args| {
                let validator = validator!(i32);
                validator(args)?;
                outside_y += args[0];
                println!("{}", outside_y);
                Ok(CommandStatus::Done)
            }),
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

pub fn text_width<T: Into<usize>>(self, v: T) -> Self

Width of the text used when wrapping the help message. Defaults to 80.

Examples found in repository

examples/mut_state.rs (line 11)

fn main() -> anyhow::Result<()> {
    let mut outside_x = String::from("Out x");
    let mut outside_y = String::from("Out y");

    let mut repl = Repl::builder()
        .description("Example REPL")
        .prompt("=> ")
        .text_width(60 as usize)
        .add("count", command! {
            "Count from X to Y",
            (X:i32, Y:i32) => |x, y| {
                for i in x..=y {
                    print!(" {}", i);
                }
                println!();
                Ok(CommandStatus::Done)
            }
        })
        .add("say", command! {
            "Say X",
            (:f32) => |x| {
                println!("x is equal to {}", x);
                Ok(CommandStatus::Done)
            },
        })
        .add("outx", command! {
            "Use mutably outside var x. This command has a really long description so we need to wrap it somehow, it is interesting how actually the wrapping will be performed.",
            () => || {
                outside_x += "x";
                println!("{}", outside_x);
                Ok(CommandStatus::Done)
            },
        })
        // this shows how to create Command manually with the help of the validator! macro
        // one could also implement arguments validation manually
        .add("outy", easy_repl::Command {
            description: "Use mutably outside var y".into(),
            args_info: vec!["appended".into()],
            handler: Box::new(|args| {
                let validator = validator!(i32);
                validator(args)?;
                outside_y += args[0];
                println!("{}", outside_y);
                Ok(CommandStatus::Done)
            }),
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

pub fn editor_config<T: Into<Config>>(self, v: T) -> Self

Configuration for rustyline. Some sane defaults are used.

pub fn out<T: Into<Box<dyn Write>>>(self, v: T) -> Self

Where to print REPL output. By default std::io::Stderr is used.

Note that rustyline will always use std::io::Stderr or std::io::Stdout. These must be configured in ReplBuilder::editor_config, and currently there seems to be no way to use other output stream for rustyline (which probably also makes little sense).

pub fn with_hints<T: Into<bool>>(self, v: T) -> Self

Print command hints. Defaults to true.

Hints will show the end of a command if there is only one avaliable. For example, assuming commands "move" and "make", in the following position (| indicates the cursor):

> mo|

a hint will be shown as

> mo|ve

but when there is only

> m|

then no hints will be shown.

pub fn with_completion<T: Into<bool>>(self, v: T) -> Self

Use completion. Defaults to true.

pub fn with_filename_completion<T: Into<bool>>(self, v: T) -> Self

Add filename completion, besides command completion. Defaults to false.

pub fn predict_commands<T: Into<bool>>(self, v: T) -> Self

Execute commands when entering incomplete names. Defaults to true.

With this option commands can be executed by entering only part of command name. If there is only a single command mathing given prefix, then it will be executed. For example, with commands "make" and “move”, entering just mo will resolve to move and the command will be executed, but entering m will result in an error.

pub fn add(self, name: &str, cmd: Command<'a>) -> Self

Add a command with given name. Use along with the [command!] macro.

Examples found in repository

examples/matryoshka.rs (line 20)

fn matryoshka(name: String) -> anyhow::Result<Repl<'static>> {
    let prompt = format!("{}> ", name);

    let cloned_prompt = prompt.clone();  // need to move it into closure
    let new = command! {
        "Enter new repl",
        (name:String) => |name: String| {
            let name = cloned_prompt.clone() + &name;
            let mut repl = matryoshka(name)?;
            repl.run()?;
            Ok(CommandStatus::Done)
        }
    };

    let repl = Repl::builder()
        .prompt(prompt)
        .add("new", new)
        .build()?;

    Ok(repl)
}

examples/minimal.rs (lines 6-12)

fn main() -> anyhow::Result<()> {
    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().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/from_str.rs (lines 9-17)

fn main() -> anyhow::Result<()> {
    let mut repl = Repl::builder()
        .add("ls", command! {
            "List files in a directory",
            (dir: PathBuf) => |dir: PathBuf| {
                for entry in dir.read_dir()? {
                    println!("{}", entry?.path().to_string_lossy());
                }
                Ok(CommandStatus::Done)
            }
        })
        .add("ipaddr", command! {
            "Just parse and print the given IP address",
            (ip: IpAddr) => |ip: IpAddr| {
                println!("{}", ip);
                Ok(CommandStatus::Done)
            }
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")
}

examples/overload.rs (lines 6-12)

fn main() -> anyhow::Result<()> {
    let mut repl = Repl::builder()
        .add("describe", command! {
            "Variant 1",
            () => || {
                println!("No arguments");
                Ok(CommandStatus::Done)
            }
        })
        .add("describe", command! {
            "Variant 2",
            (a: i32, b: i32) => |a, b| {
                println!("Got two integers: {} {}", a, b);
                Ok(CommandStatus::Done)
            }
        })
        .add("describe", command! {
            "Variant 3",
            (a: i32, b: String) => |a, b| {
                println!("An integer `{}` and a string `{}`", a, b);
                Ok(CommandStatus::Done)
            }
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/shared_mut_state.rs (lines 15-22)

fn main() -> anyhow::Result<()> {
    // To use a value in multiple commands we need shared ownership
    // combined with some kind of references.
    // This could be Rc<RefCell<_>>, but in this example it's possible
    // to avoid smart pointers and just use two references &RefCell<_>.
    let counter = RefCell::new(0);
    let ref1 = &counter;
    let ref2 = &counter;

    let mut repl = Repl::builder()
        .add("inc", command! {
            "Increment counter",
            () => || {
                *ref1.borrow_mut() += 1;
                println!("counter = {}", ref1.borrow());
                Ok(CommandStatus::Done)
            },
        })
        .add("dec", command! {
            "Decrement counter",
            () => || {
                *ref2.borrow_mut() -= 1;
                println!("counter = {}", ref2.borrow());
                Ok(CommandStatus::Done)
            },
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/mut_state.rs (lines 12-21)

fn main() -> anyhow::Result<()> {
    let mut outside_x = String::from("Out x");
    let mut outside_y = String::from("Out y");

    let mut repl = Repl::builder()
        .description("Example REPL")
        .prompt("=> ")
        .text_width(60 as usize)
        .add("count", command! {
            "Count from X to Y",
            (X:i32, Y:i32) => |x, y| {
                for i in x..=y {
                    print!(" {}", i);
                }
                println!();
                Ok(CommandStatus::Done)
            }
        })
        .add("say", command! {
            "Say X",
            (:f32) => |x| {
                println!("x is equal to {}", x);
                Ok(CommandStatus::Done)
            },
        })
        .add("outx", command! {
            "Use mutably outside var x. This command has a really long description so we need to wrap it somehow, it is interesting how actually the wrapping will be performed.",
            () => || {
                outside_x += "x";
                println!("{}", outside_x);
                Ok(CommandStatus::Done)
            },
        })
        // this shows how to create Command manually with the help of the validator! macro
        // one could also implement arguments validation manually
        .add("outy", easy_repl::Command {
            description: "Use mutably outside var y".into(),
            args_info: vec!["appended".into()],
            handler: Box::new(|args| {
                let validator = validator!(i32);
                validator(args)?;
                outside_y += args[0];
                println!("{}", outside_y);
                Ok(CommandStatus::Done)
            }),
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

Additional examples can be found in:

• examples/errors.rs

pub fn build(self) -> Result<Repl<'a>, BuilderError>

Finalize the configuration and return the REPL or error.

Examples found in repository

examples/matryoshka.rs (line 21)

fn matryoshka(name: String) -> anyhow::Result<Repl<'static>> {
    let prompt = format!("{}> ", name);

    let cloned_prompt = prompt.clone();  // need to move it into closure
    let new = command! {
        "Enter new repl",
        (name:String) => |name: String| {
            let name = cloned_prompt.clone() + &name;
            let mut repl = matryoshka(name)?;
            repl.run()?;
            Ok(CommandStatus::Done)
        }
    };

    let repl = Repl::builder()
        .prompt(prompt)
        .add("new", new)
        .build()?;

    Ok(repl)
}

examples/minimal.rs (line 20)

fn main() -> anyhow::Result<()> {
    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().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/from_str.rs (line 25)

fn main() -> anyhow::Result<()> {
    let mut repl = Repl::builder()
        .add("ls", command! {
            "List files in a directory",
            (dir: PathBuf) => |dir: PathBuf| {
                for entry in dir.read_dir()? {
                    println!("{}", entry?.path().to_string_lossy());
                }
                Ok(CommandStatus::Done)
            }
        })
        .add("ipaddr", command! {
            "Just parse and print the given IP address",
            (ip: IpAddr) => |ip: IpAddr| {
                println!("{}", ip);
                Ok(CommandStatus::Done)
            }
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")
}

examples/overload.rs (line 27)

fn main() -> anyhow::Result<()> {
    let mut repl = Repl::builder()
        .add("describe", command! {
            "Variant 1",
            () => || {
                println!("No arguments");
                Ok(CommandStatus::Done)
            }
        })
        .add("describe", command! {
            "Variant 2",
            (a: i32, b: i32) => |a, b| {
                println!("Got two integers: {} {}", a, b);
                Ok(CommandStatus::Done)
            }
        })
        .add("describe", command! {
            "Variant 3",
            (a: i32, b: String) => |a, b| {
                println!("An integer `{}` and a string `{}`", a, b);
                Ok(CommandStatus::Done)
            }
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/shared_mut_state.rs (line 31)

fn main() -> anyhow::Result<()> {
    // To use a value in multiple commands we need shared ownership
    // combined with some kind of references.
    // This could be Rc<RefCell<_>>, but in this example it's possible
    // to avoid smart pointers and just use two references &RefCell<_>.
    let counter = RefCell::new(0);
    let ref1 = &counter;
    let ref2 = &counter;

    let mut repl = Repl::builder()
        .add("inc", command! {
            "Increment counter",
            () => || {
                *ref1.borrow_mut() += 1;
                println!("counter = {}", ref1.borrow());
                Ok(CommandStatus::Done)
            },
        })
        .add("dec", command! {
            "Decrement counter",
            () => || {
                *ref2.borrow_mut() -= 1;
                println!("counter = {}", ref2.borrow());
                Ok(CommandStatus::Done)
            },
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

examples/mut_state.rs (line 50)

fn main() -> anyhow::Result<()> {
    let mut outside_x = String::from("Out x");
    let mut outside_y = String::from("Out y");

    let mut repl = Repl::builder()
        .description("Example REPL")
        .prompt("=> ")
        .text_width(60 as usize)
        .add("count", command! {
            "Count from X to Y",
            (X:i32, Y:i32) => |x, y| {
                for i in x..=y {
                    print!(" {}", i);
                }
                println!();
                Ok(CommandStatus::Done)
            }
        })
        .add("say", command! {
            "Say X",
            (:f32) => |x| {
                println!("x is equal to {}", x);
                Ok(CommandStatus::Done)
            },
        })
        .add("outx", command! {
            "Use mutably outside var x. This command has a really long description so we need to wrap it somehow, it is interesting how actually the wrapping will be performed.",
            () => || {
                outside_x += "x";
                println!("{}", outside_x);
                Ok(CommandStatus::Done)
            },
        })
        // this shows how to create Command manually with the help of the validator! macro
        // one could also implement arguments validation manually
        .add("outy", easy_repl::Command {
            description: "Use mutably outside var y".into(),
            args_info: vec!["appended".into()],
            handler: Box::new(|args| {
                let validator = validator!(i32);
                validator(args)?;
                outside_y += args[0];
                println!("{}", outside_y);
                Ok(CommandStatus::Done)
            }),
        })
        .build().context("Failed to create repl")?;

    repl.run().context("Critical REPL error")?;

    Ok(())
}

Additional examples can be found in:

• examples/errors.rs

Trait Implementations

impl<'a> Default for ReplBuilder<'a>

fn default() -> Self

Returns the “default value” for a type.