3 releases
0.1.3 | Mar 7, 2023 |
---|---|
0.1.2 | Mar 7, 2023 |
0.1.1 | Mar 7, 2023 |
#424 in Command-line interface
1MB
467 lines
Cartographer-rs
Cartographer is a small library using Console and macros to bring “just add water” TUI menus to your programs.
Utilizing the power of macros, you can create an interactive menu in less than 10 lines of code.
The main reason I created this crate, is that other, less menu-specific crates, like Dialoguer, don’t support menu-options that only show up in search results.
See examples for some… Examples of Cartographer’s offerings
Example
(You can find more examples in the examples directory)
A basic example of a multi select menu:
// ./examples/example_menu.rs
use cartographer::{menu, menu_item, MenuOptions};
fn main() {
let options = MenuOptions::new().cursor('➤').selected_indicator('✓');
let menu = menu!(
"So you should try it!: ",
options,
[
menu_item!("Using Cartographer", true, 1),
menu_item!("Making TUI menus", true, 2),
menu_item!("Is easy", true, 3),
menu_item!("Read on for more!", false, 0, ["Ok"])
]
);
let usr_selection = menu.serve().unwrap().unwrap();
println!("\nYou Selected:\n{:?}", usr_selection);
}
How to Use
Adding it to your project dependencies
Simply run
cargo add cartographer
in your project directory, or add
"cartographer" = "the latest version"
to your Cargo.toml
.
Creating a menu!
There are two ways you can create a menu.
The macro way, and the manual way.
The macro way is demonstrated in the example above.
An example of the manual way can be found in the examples directory. The manual way uses builder notation and the cartographer::Menu
and cartographer::MenuItem
structs to manually build menus and menu items.
All types handled by this crate are of type String
. The values from prompts, and the return types are all strings, so I would suggest using a solution much like what can be found in the examples to easily match
the return value.
But returned strings will match the supplied prompts including special formatting! So just be careful if you decide to match by strings!
Serving your menu
All menu logic is handled behind the scenes once .serve()
is called on a valid Menu
, and the thread will wait for the user to make their selections.
While threading with this library is probably possible (though untested), make sure that there is no terminal output sent by other threads, or visual problems will start to crop up.
Configuration
To configure how your menu looks, you can use the cartographer::MenuOptions
struct and builder notation to create a configuration.
let options = MenuOptions::new().cursor(’➤’).selectedindicator(’✓’);
The defaults and additional options can found under the docs for MenuOptions.
Dependencies
~1.6–9MB
~48K SLoC