Crate ezmenulib 

Fast designing menus for your Rust CLI programs.

Caution: This library is not completely stable yet. Many changes may occur depending on versions. I am still looking for a sustainable design of the library.

This crate provides a library with structs and traits to easily build menus. It includes type-checking from the user input, and a formatting customization.

This crate is useful if you use structopt or clap crates beside it, so you can get the matches safely, and build a menu on your own after.

It can also be used as a mode selection, for a game for example.

Note

If you want to use the derive Menu macro, you must use the ezmenu crate instead. This crate may however contain features that are not available on the ezmenu crate.

Value-menus

The first type of menu this library provides is a value-menu. These menus are used to retrieve data values from the user by iterating on the next outputs. At each iteration, it prompts the user a value, parses it and prompts until it is correct, then returns it.

Example

Here is an example of how to use this menu:

use ezmenulib::prelude::*;

let mut my_menu = ValueMenu::from([
    Field::Value(ValueField::from("Give your name")),
    Field::Value(ValueField::from("Give a number")),
])
.title("Hello there!");

let name: String = my_menu.next_output().unwrap();
let number: i32 = my_menu.next_output().unwrap();

println!("values provided: name={}, number={}", name, number);

This sample code prints the standard menu like above:

Hello there!
--> Give your name
>> Ahmad

--> Give a number
>> 1000

values provided: name=Ahmad, number=1000

Format it as you wish

You can apply several formatting rules on a menu or on a field specifically. You can edit:

• the chip: "--> " by default.
• the prefix: ">> " by default.
• insert a new line before prefix and user input: true by default.
• display default values or not: true by default. These parameters are defined in the ValueFieldFormatting struct.

Example

For a custom format on a field and a main formatting rule on a menu, you can build this with:

use ezmenulib::prelude::*;

let mut license = ValueMenu::from([
    Field::Value(ValueField::from("Authors")),
    Field::Value(ValueField::from("Project name")
        .fmt(ValueFieldFormatting::chip("--- "))),
    Field::Value(ValueField::from("Date")),
])
.fmt(ValueFieldFormatting::chip("==> "));

// ...

The custom "==> " chip will be applied on every field except those with custom formatting rules, In this case, it will format the text like above:

==> Authors
>> ...

--- Project name
>> ...

==> Date
>> ...

Skip fields with default values

You can provide a default input value to a field with the ValueField::default method:

ValueField::from("Date").default_value("2022")

If the user provided an incorrect input, the program will not re-ask a value to the user, but will directly return the default value instead.

By default, the default value is visible by the user, like above:

--> Date (default: 2022)

If you want to hide it, you can do so with formatting rules:

ValueField::from("Date")
    .fmt(ValueFieldFormatting::default(false))

Use custom value types

If the user has to provide a value which corresponds to your specific type, you only need to implement the FromStr trait on that type. The error type only needs to implement Debug trait, for error displaying purposes.

If the error is infallible, you can use simple data types such as unit () or std::convert::Infallible.

Example

use std::str::FromStr;
use ezmenulib::field::ValueField;

enum Type {
    MIT,
    BSD,
    GPL,
}

impl FromStr for Type {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "mit" => Ok(Self::MIT),
            "gpl" => Ok(Self::GPL),
            "bsd" => Ok(Self::BSD),
            s => Err(format!("unknown license type: {}", s)),
        }
    }
}

let license_type: Type = ValueField::from("Give the license type")
    .build_init()
    .unwrap();

Provided custom value types

The EZMenu library already provides custom value types to handle user input. Check out the customs module to see all available custom value types.

For instance, the MenuBool is used to override the boolean parsing method, allowing “yes” or “no” as inputs.

The MenuVec<T> type allows the user to enter many values separated by spaces and collect them into a Vec<T>. Of course, T must implement FromStr trait.

Selectable menus

Beside the value-menus, there is also the selectable menus. These menus, unlike value-menus, displays the list of possible values to the user, to let him select one among them.

Example

use std::str::FromStr;
use ezmenulib::prelude::*;

enum Type {
    MIT,
    GPL,
    BSD,
}

impl FromStr for Type {
    type Err = MenuError;

    fn from_str(s: &str) -> MenuResult<Self> {
        match s.to_lowercase().as_str() {
            "mit" => Ok(Self::MIT),
            "gpl" => Ok(Self::GPL),
            "bsd" => Ok(Self::BSD),
            s => Err(MenuError::from(format!("unknown license type: {}", s))),
        }
    }
}

let license_type: Type = SelectMenu::from([
    SelectField::from("MIT"),
    SelectField::from("GPL"),
    SelectField::from("BSD"),
])
.title(SelectTitle::from("Choose a license type"))
.default(0)
.next_output()
.unwrap();

This code prints the output like above:

Choose a license type:
1 - MIT (default)
2 - GPL
3 - BSD

Note that the : character right next to the title is on purpose (check the SelectTitle for more information).

You can also use this menu on primitive types or types already implementing FromStr trait. The menu accepts an index or the literal value as input.

Formatting rules

Like the ValueMenu, you can edit many formatting rules to stylish the menu as you want.

The menu format

The selective menu itself has two editable formatting rules. Like ValueFieldFormatting, it contains a chip and a prefix:

X<chip><message>
X<chip><message>
...
<prefix>

The default chip is " - ", and the default prefix is ">> ".

The title format

The selective has also its own title format. Because the title can be seen as a field of a value-menu, it has its own instance of ValueFieldFormatting struct.

This is useful for sub-menu management, where the formatting rules of the title inherits from the formatting rules of the parent menu, for more convenience.

Skip the menu with a default field value

The user can skip the selectable menu if it has a default value provided. To do so, you must use the SelectMenu::default method.

This will mark the indexed field as "(default)".

Sub-menus

You can set a selectable menu as a field of a value-menu. This is really useful if you want to design sub-menu. The selectable field format will inherit from the formatting rules of the value-menu.

Example

use ezmenulib::prelude::*;

let mut license = ValueMenu::from([
    Field::Value(ValueField::from("Authors")),
    Field::Value(ValueField::from("Project name")),
    Field::Select(SelectMenu::from([
        SelectField::from("MIT"),
        SelectField::from("GPL"),
        SelectField::from("BSD"),
    ])
    .title(SelectTitle::from("License type"))
    .default(0)),
])
.title("Describe the project license");

Modules

customs

The module containing the default custom types implementing FromStr trait.

field

Module defining different types of fields.

menu

Module defining the different types of menus.

prelude

Module used to import common structs, to build menus with their fields.

Enums

MenuError

The error type used by the menu builder.

Type Aliases

MenuResult

The main result type used in the EZMenu library.