Struct Shell 

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

The shell.

The type parameter 'a is the lifetime of state captured by command handlers registered with Shell::add_command.

Example

use embassy_shell::Shell;

let mut shell = Shell::new();
shell.add_command("echo", "print arguments", |args, mut io| {
    Box::pin(async move { io.println(&args.rest()).await })
});

let mut input: &[u8] = b"echo hello world\r\n";
let mut output: Vec<u8> = Vec::new();
futures::executor::block_on(shell.run(&mut input, &mut output)).unwrap();

assert!(String::from_utf8_lossy(&output).contains("hello world"));

Implementations

impl<'a> Shell<'a>

pub fn new() -> Self

Create an empty shell with default settings.

pub fn prompt(&mut self, prompt: &'static str) -> &mut Self

Set the prompt string.

pub fn max_history(&mut self, n: usize) -> &mut Self

Set the maximum number of remembered history entries.

pub fn max_history_len(&mut self, n: usize) -> &mut Self

Set the maximum length (in bytes) of a remembered history entry. Longer lines are truncated (at a character boundary) before being stored. Defaults to 64; 0 disables history storage of content beyond the empty string.

pub fn max_line_len(&mut self, n: usize) -> &mut Self

Set the maximum length (in bytes) of a line typed at the prompt. Once the buffer is full, further characters are rejected with a BEL (\x07). Defaults to 128.

pub fn add_command<F>(&mut self, name: &str, help: &'static str, handler: F)

where F: for<'x> Fn(Args<'x>, Io<'x>) -> BoxFuture<'x, Result<()>> + 'a,

Register a command.

name is what the user types at the prompt, help is the one-line description shown by help. handler receives the arguments and an output handle, and must return a boxed future (wrap an async move block in Box::pin) so that all commands share one concrete future type:

let mut shell = Shell::new();
shell.add_command("hello", "say hello", |args, mut io| {
    Box::pin(async move {
        let name = args.get(0).unwrap_or("world");
        io.println(&format!("Hello, {name}!")).await
    })
});

pub fn add_command_with_options<F>( &mut self, name: &str, help: &'static str, options: &'static [&'static str], handler: F, )

where F: for<'x> Fn(Args<'x>, Io<'x>) -> BoxFuture<'x, Result<()>> + 'a,

Register a command whose first argument is completed from a fixed list of options (e.g. led on|off|blink).

pub fn add_command_with_completer<F, C>( &mut self, name: &str, help: &'static str, handler: F, completer: C, )

where F: for<'x> Fn(Args<'x>, Io<'x>) -> BoxFuture<'x, Result<()>> + 'a, C: Fn(usize, &str) -> Vec<String> + 'a,

Register a command with a custom completer. The completer is called with the index of the argument being completed (>= 1) and the partial token, and returns candidate replacements for that token.

pub fn command_names(&self) -> impl Iterator<Item = &str>

Names of all registered user commands.

pub async fn run<R, W>(&mut self, reader: &mut R, writer: &mut W) -> Result<()>

where R: Read, W: Write,

Run the interactive shell until end of input.

reader and writer are the transport (UART, USB CDC, …). They may be any types implementing embedded_io_async::Read / embedded_io_async::Write.

Ctrl-C interrupts a running command (the handler future is dropped, so handlers should be cancel-safe). Bytes typed while a command runs are not echoed and only the most recent one is kept for the next line.

Trait Implementations

impl Default for Shell<'_>

fn default() -> Self

Returns the “default value” for a type.