light_cli/lib.rs
1//! Simple heapless command line interface parser for embedded devices
2//!
3//! This crates makes use of a serial interface that implements the read trait
4//! of the [`embedded-hal`] crate.
5//!
6//! [`embedded-hal`]: https://crates.io/crates/embedded-hal
7//!
8//! # Usage
9//!
10//! First define an instance of the CLI by initializing a [`LightCliInput`] and a
11//! [`LightCliOutput`]. The output instance requires the serial write instance
12//! which should implement the embedded-hal [`Write<u8>`] trait:
13//!
14//! [`LightCliInput`]: struct.LightCliInput.html
15//! [`LightCliOutput`]: struct.LightCliOutput.html
16//! [`Write<u8>`]: ../embedded_hal/serial/trait.Write.html
17//!
18//! ```
19//! let mut cl_in : LightCliInput<U32> = LightCliInput::new();
20//! let mut cl_out = LightCliOutput::new(tx);
21//! ```
22//!
23//! Periodically copy all contents of the serial device into the cli buffer by using
24//! the [`fill`] method, passing it the serial read instance `rx`, which implements
25//! the embedded-hal [`Read<u8>`] trait. In addition it is necessary to try to empty
26//! the output buffer, by calling the [`flush`] method on the console output instance:
27//!
28//! [`fill`]: struct.LightCliInput.html#method.fill
29//! [`flush`]: struct.LightCliOutput.html#method.flush
30//! [`Read<u8>`]: ../embedded_hal/serial/trait.Read.html
31//!
32//! ```
33//! let _ = cl_in.fill(&mut rx);
34//! let _ = cl_out.flush();
35//! ```
36//!
37//! Periodically parse the data in the buffer using the [`lightcli!`] macro:
38//!
39//! [`lightcli!`]: macro.lightcli.html
40//!
41//! ```
42//! let mut name : String<U32> = String;:new();
43//!
44//! loop {
45//! /* fill, flush, etc. */
46//!
47//! lightcli!(cl_in, cl_out, cmd, key, val, [
48//! "HELLO" => [
49//! "Name" => name = String::from(val)
50//! ] => { writeln!(cl_out, "Name set").unwrap(); };
51//! "EHLO" => [
52//! ] => { writeln!(cl_out, "EHLO Name={}", name.as_str()).unwrap(); }
53//! ]);
54//! }
55//! ```
56//!
57//! A serial communication may then look like:
58//!
59//! ```
60//! >> EHLO
61//! << EHLO Name=
62//! >> HELLO Name=Johnson
63//! << Name set
64//! >> EHLO
65//! << EHLO Name=Johnson
66//! ```
67//!
68//! # Examples
69//!
70//! See the [examples] module.
71//!
72//! [examples]: examples/index.html
73
74#![no_std]
75pub extern crate embedded_hal as hal;
76pub extern crate nb;
77pub extern crate heapless;
78
79#[macro_use]
80mod macros;
81mod tokenizer;
82mod lexer;
83mod output;
84mod input;
85
86#[cfg(feature = "doc")]
87pub mod examples;
88
89#[cfg(test)]
90mod tests;
91
92pub use lexer::CallbackCommand;
93
94pub use output::LightCliOutput;
95pub use input::LightCliInput;
96