Struct Input

pub struct Input<M: Display> { /* private fields */ }

Input struct

Examples

use may_clack::{cancel, input};

let answer = input("message")
    .initial_value("initial_value")
    .validate(|x| {
        if x.find(char::is_uppercase).is_some() {
            Err(Cow::Borrowed("only use lowercase characters"))
        } else {
            Ok(())
        }
    })
    .cancel(do_cancel)
    .interact()?;
println!("answer {:?}", answer);

fn do_cancel() {
    cancel!("operation cancelled");
    std::process::exit(1);
}

Implementations

impl<M: Display> Input<M>

pub fn new(message: M) -> Self

Creates a new Input struct.

Has a shorthand version in input()

Examples

use may_clack::{input, input::Input};

// these two are equivalent
let question = Input::new("message");
let question = input("message");

pub fn placeholder<S: ToString>(&mut self, placeholder: S) -> &mut Self

Specify a placeholder.

Examples

use may_clack::input;

let answer = input("message").placeholder("placeholder").required()?;
println!("answer {:?}", answer);

Examples found in repository

examples/to_string.rs (line 18)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" to_string ".reversed());

	let int = input("int").initial_value(23).parse::<i32>()?;
	let unit = input("struct").placeholder(Name).required()?;

	outro!();

	println!("int {:?}", int);
	println!("unit {:?}", unit);

	Ok(())
}

examples/full.rs (line 14)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" full ".reversed());

	info!("visit the documentation at https://docs.rs/may-clack");

	let do_input = input("input")
		.placeholder("placeholder")
		.cancel(do_cancel)
		.required()?;
	let do_multi_input = multi_input("multi input")
		.max(4)
		.cancel(do_cancel)
		.interact()?;
	let do_confirm = confirm("confirm")
		.prompts("true", "false")
		.cancel(do_cancel)
		.interact()?;
	let do_multi_select = multi_select("multi select")
		.option("opt1", "option 1")
		.option("opt2", "option 2")
		.option_hint("opt3", "option 3", "hint")
		.cancel(do_cancel)
		.interact()?;
	let do_select = select("select")
		.option("val1", "value 1")
		.option("val2", "value 2")
		.option_hint("val 3", "value 3", "hint")
		.cancel(do_cancel)
		.interact()?;

	outro!();

	println!("input {:?}", do_input);
	println!("confirm {:?}", do_confirm);
	println!("multi_input {:?}", do_multi_input);
	println!("multi_select {:?}", do_multi_select);
	println!("select {:?}", do_select);

	Ok(())
}

pub fn maybe_initial<T: Borrow<Option<S>>, S: ToString>( &mut self, initial: T, ) -> &mut Self

Maybe specify an initial value.

Examples

use may_clack::input;

let answer = input("message").maybe_initial(Some("initial")).required()?;
let answer = input("message").maybe_initial(None::<&str>).required()?;

Examples found in repository

examples/maybe_initial.rs (line 12)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" maybe_initial ".reversed());

	let opt = Some("test");

	#[allow(clippy::needless_borrows_for_generic_args)]
	let ref_opt = input("message")
		.maybe_initial(&opt)
		.cancel(do_cancel)
		.required()?;
	let opt = input("message")
		.maybe_initial(opt)
		.cancel(do_cancel)
		.required()?;
	let none = input("message")
		.maybe_initial(None::<&str>)
		.cancel(do_cancel)
		.required()?;

	outro!();

	println!("ref_opt {:?}", ref_opt);
	println!("opt {:?}", opt);
	println!("none {:?}", none);

	Ok(())
}

pub fn initial_value<S: ToString>(&mut self, initial_value: S) -> &mut Self

Specify the initial value.

Examples

use may_clack::input;

let answer = input("message").initial_value("initial_value").interact()?;
println!("answer {:?}", answer);

Examples found in repository

examples/to_string.rs (line 17)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" to_string ".reversed());

	let int = input("int").initial_value(23).parse::<i32>()?;
	let unit = input("struct").placeholder(Name).required()?;

	outro!();

	println!("int {:?}", int);
	println!("unit {:?}", unit);

	Ok(())
}

pub fn validate<F>(&mut self, validate: F) -> &mut Self

where F: Fn(&str) -> Result<(), Cow<'static, str>> + 'static,

Specify a validation function.

On a successful validation, return a None from the closure, and on an unsuccessful validation return a Some<&'static str> with the error message.

Examples

use may_clack::input;

let answer = input("message")
    .validate(|x| {
        if x.is_ascii() {
            Ok(())
        } else {
            Err(Cow::Borrowed("only use ascii characters"))
        }
    })
    .interact()?;
println!("answer {:?}", answer);

Examples found in repository

examples/validate.rs (lines 10-16)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" validate ".reversed());

	let do_validate_input = input("validate single (only use ascii)")
		.validate(|x| {
			if x.is_ascii() {
				Ok(())
			} else {
				Err(Cow::Borrowed("only use ascii characters"))
			}
		})
		.cancel(do_cancel)
		.required()?;
	let do_validate_multi_input = multi_input("validate multi (only use lowercase)")
		.validate(|x| {
			if x.find(char::is_uppercase).is_some() {
				Err(Cow::Borrowed("only use lowercase characters"))
			} else {
				Ok(())
			}
		})
		.cancel(do_cancel)
		.interact()?;
	let do_parse_input = input("parse to u8").cancel(do_cancel).parse::<u8>()?;
	let do_maybe_parse = input("maybe parse to ipv4 addr").maybe_parse::<Ipv4Addr>()?;
	let do_parse_multi = multi_input("parse multiple to u8")
		.cancel(do_cancel)
		.parse::<u8>()?;

	outro!();

	println!("single {:?}", do_validate_input);
	println!("multi {:?}", do_validate_multi_input);
	println!("parse single {:?}", do_parse_input);
	println!("maybe parse single {:?}", do_maybe_parse);
	println!("parse multi {:?}", do_parse_multi);

	Ok(())
}

pub fn cancel<F>(&mut self, cancel: F) -> &mut Self

where F: Fn() + 'static,

Specify function to call on cancel.

Examples

use may_clack::{input, cancel};

let answer = input("message").cancel(do_cancel).interact()?;
println!("answer {:?}", answer);

fn do_cancel() {
    cancel!("operation cancelled");
    panic!("operation cancelled");
}

Examples found in repository

examples/maybe_initial.rs (line 13)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" maybe_initial ".reversed());

	let opt = Some("test");

	#[allow(clippy::needless_borrows_for_generic_args)]
	let ref_opt = input("message")
		.maybe_initial(&opt)
		.cancel(do_cancel)
		.required()?;
	let opt = input("message")
		.maybe_initial(opt)
		.cancel(do_cancel)
		.required()?;
	let none = input("message")
		.maybe_initial(None::<&str>)
		.cancel(do_cancel)
		.required()?;

	outro!();

	println!("ref_opt {:?}", ref_opt);
	println!("opt {:?}", opt);
	println!("none {:?}", none);

	Ok(())
}

examples/full.rs (line 15)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" full ".reversed());

	info!("visit the documentation at https://docs.rs/may-clack");

	let do_input = input("input")
		.placeholder("placeholder")
		.cancel(do_cancel)
		.required()?;
	let do_multi_input = multi_input("multi input")
		.max(4)
		.cancel(do_cancel)
		.interact()?;
	let do_confirm = confirm("confirm")
		.prompts("true", "false")
		.cancel(do_cancel)
		.interact()?;
	let do_multi_select = multi_select("multi select")
		.option("opt1", "option 1")
		.option("opt2", "option 2")
		.option_hint("opt3", "option 3", "hint")
		.cancel(do_cancel)
		.interact()?;
	let do_select = select("select")
		.option("val1", "value 1")
		.option("val2", "value 2")
		.option_hint("val 3", "value 3", "hint")
		.cancel(do_cancel)
		.interact()?;

	outro!();

	println!("input {:?}", do_input);
	println!("confirm {:?}", do_confirm);
	println!("multi_input {:?}", do_multi_input);
	println!("multi_select {:?}", do_multi_select);
	println!("select {:?}", do_select);

	Ok(())
}

examples/validate.rs (line 17)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" validate ".reversed());

	let do_validate_input = input("validate single (only use ascii)")
		.validate(|x| {
			if x.is_ascii() {
				Ok(())
			} else {
				Err(Cow::Borrowed("only use ascii characters"))
			}
		})
		.cancel(do_cancel)
		.required()?;
	let do_validate_multi_input = multi_input("validate multi (only use lowercase)")
		.validate(|x| {
			if x.find(char::is_uppercase).is_some() {
				Err(Cow::Borrowed("only use lowercase characters"))
			} else {
				Ok(())
			}
		})
		.cancel(do_cancel)
		.interact()?;
	let do_parse_input = input("parse to u8").cancel(do_cancel).parse::<u8>()?;
	let do_maybe_parse = input("maybe parse to ipv4 addr").maybe_parse::<Ipv4Addr>()?;
	let do_parse_multi = multi_input("parse multiple to u8")
		.cancel(do_cancel)
		.parse::<u8>()?;

	outro!();

	println!("single {:?}", do_validate_input);
	println!("multi {:?}", do_validate_multi_input);
	println!("parse single {:?}", do_parse_input);
	println!("maybe parse single {:?}", do_maybe_parse);
	println!("parse multi {:?}", do_parse_multi);

	Ok(())
}

pub fn parse<T: FromStr + Display>(&self) -> Result<T, ClackError>

where T::Err: Error,

Like Input::required(), but parses the value before returning.

Useful for getting number inputs.

Examples

use may_clack::input;

let answer: i32 = input("message").parse::<i32>()?;
println!("answer {:?}", answer);

Examples found in repository

examples/to_string.rs (line 17)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" to_string ".reversed());

	let int = input("int").initial_value(23).parse::<i32>()?;
	let unit = input("struct").placeholder(Name).required()?;

	outro!();

	println!("int {:?}", int);
	println!("unit {:?}", unit);

	Ok(())
}

examples/validate.rs (line 29)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" validate ".reversed());

	let do_validate_input = input("validate single (only use ascii)")
		.validate(|x| {
			if x.is_ascii() {
				Ok(())
			} else {
				Err(Cow::Borrowed("only use ascii characters"))
			}
		})
		.cancel(do_cancel)
		.required()?;
	let do_validate_multi_input = multi_input("validate multi (only use lowercase)")
		.validate(|x| {
			if x.find(char::is_uppercase).is_some() {
				Err(Cow::Borrowed("only use lowercase characters"))
			} else {
				Ok(())
			}
		})
		.cancel(do_cancel)
		.interact()?;
	let do_parse_input = input("parse to u8").cancel(do_cancel).parse::<u8>()?;
	let do_maybe_parse = input("maybe parse to ipv4 addr").maybe_parse::<Ipv4Addr>()?;
	let do_parse_multi = multi_input("parse multiple to u8")
		.cancel(do_cancel)
		.parse::<u8>()?;

	outro!();

	println!("single {:?}", do_validate_input);
	println!("multi {:?}", do_validate_multi_input);
	println!("parse single {:?}", do_parse_input);
	println!("maybe parse single {:?}", do_maybe_parse);
	println!("parse multi {:?}", do_parse_multi);

	Ok(())
}

pub fn maybe_parse<T: FromStr + Display>(&self) -> Result<Option<T>, ClackError>

where T::Err: Error,

Like Input::parse(), but it also allows empty line submits like Input::interact().

use may_clack::input;
use std::net::Ipv4Addr;

let answer = input("message").maybe_parse::<Ipv4Addr>()?;
println!("answer {:?}", answer);

Examples found in repository

examples/validate.rs (line 30)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" validate ".reversed());

	let do_validate_input = input("validate single (only use ascii)")
		.validate(|x| {
			if x.is_ascii() {
				Ok(())
			} else {
				Err(Cow::Borrowed("only use ascii characters"))
			}
		})
		.cancel(do_cancel)
		.required()?;
	let do_validate_multi_input = multi_input("validate multi (only use lowercase)")
		.validate(|x| {
			if x.find(char::is_uppercase).is_some() {
				Err(Cow::Borrowed("only use lowercase characters"))
			} else {
				Ok(())
			}
		})
		.cancel(do_cancel)
		.interact()?;
	let do_parse_input = input("parse to u8").cancel(do_cancel).parse::<u8>()?;
	let do_maybe_parse = input("maybe parse to ipv4 addr").maybe_parse::<Ipv4Addr>()?;
	let do_parse_multi = multi_input("parse multiple to u8")
		.cancel(do_cancel)
		.parse::<u8>()?;

	outro!();

	println!("single {:?}", do_validate_input);
	println!("multi {:?}", do_validate_multi_input);
	println!("parse single {:?}", do_parse_input);
	println!("maybe parse single {:?}", do_maybe_parse);
	println!("parse multi {:?}", do_parse_multi);

	Ok(())
}

pub fn required(&self) -> Result<String, ClackError>

Like Input::interact(), but does not return an empty line.

Examples

use may_clack::input;

let answer = input("message").required()?;
println!("answer {:?}", answer);

Examples found in repository

examples/to_string.rs (line 18)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" to_string ".reversed());

	let int = input("int").initial_value(23).parse::<i32>()?;
	let unit = input("struct").placeholder(Name).required()?;

	outro!();

	println!("int {:?}", int);
	println!("unit {:?}", unit);

	Ok(())
}

examples/maybe_initial.rs (line 14)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" maybe_initial ".reversed());

	let opt = Some("test");

	#[allow(clippy::needless_borrows_for_generic_args)]
	let ref_opt = input("message")
		.maybe_initial(&opt)
		.cancel(do_cancel)
		.required()?;
	let opt = input("message")
		.maybe_initial(opt)
		.cancel(do_cancel)
		.required()?;
	let none = input("message")
		.maybe_initial(None::<&str>)
		.cancel(do_cancel)
		.required()?;

	outro!();

	println!("ref_opt {:?}", ref_opt);
	println!("opt {:?}", opt);
	println!("none {:?}", none);

	Ok(())
}

examples/full.rs (line 16)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" full ".reversed());

	info!("visit the documentation at https://docs.rs/may-clack");

	let do_input = input("input")
		.placeholder("placeholder")
		.cancel(do_cancel)
		.required()?;
	let do_multi_input = multi_input("multi input")
		.max(4)
		.cancel(do_cancel)
		.interact()?;
	let do_confirm = confirm("confirm")
		.prompts("true", "false")
		.cancel(do_cancel)
		.interact()?;
	let do_multi_select = multi_select("multi select")
		.option("opt1", "option 1")
		.option("opt2", "option 2")
		.option_hint("opt3", "option 3", "hint")
		.cancel(do_cancel)
		.interact()?;
	let do_select = select("select")
		.option("val1", "value 1")
		.option("val2", "value 2")
		.option_hint("val 3", "value 3", "hint")
		.cancel(do_cancel)
		.interact()?;

	outro!();

	println!("input {:?}", do_input);
	println!("confirm {:?}", do_confirm);
	println!("multi_input {:?}", do_multi_input);
	println!("multi_select {:?}", do_multi_select);
	println!("select {:?}", do_select);

	Ok(())
}

examples/validate.rs (line 18)

fn main() -> Result<(), ClackError> {
	println!();
	intro!(" validate ".reversed());

	let do_validate_input = input("validate single (only use ascii)")
		.validate(|x| {
			if x.is_ascii() {
				Ok(())
			} else {
				Err(Cow::Borrowed("only use ascii characters"))
			}
		})
		.cancel(do_cancel)
		.required()?;
	let do_validate_multi_input = multi_input("validate multi (only use lowercase)")
		.validate(|x| {
			if x.find(char::is_uppercase).is_some() {
				Err(Cow::Borrowed("only use lowercase characters"))
			} else {
				Ok(())
			}
		})
		.cancel(do_cancel)
		.interact()?;
	let do_parse_input = input("parse to u8").cancel(do_cancel).parse::<u8>()?;
	let do_maybe_parse = input("maybe parse to ipv4 addr").maybe_parse::<Ipv4Addr>()?;
	let do_parse_multi = multi_input("parse multiple to u8")
		.cancel(do_cancel)
		.parse::<u8>()?;

	outro!();

	println!("single {:?}", do_validate_input);
	println!("multi {:?}", do_validate_multi_input);
	println!("parse single {:?}", do_parse_input);
	println!("maybe parse single {:?}", do_maybe_parse);
	println!("parse multi {:?}", do_parse_multi);

	Ok(())
}

pub fn interact(&self) -> Result<Option<String>, ClackError>

Waits for the user to submit a line of text.

Returns None on an empty line and Some::<String> otherwise.

Examples

use may_clack::{cancel, input};

let answer = input("message")
    .initial_value("initial_value")
    .validate(|x| {
        x.parse::<u32>()
            .map(|_| ())
            .map_err(|_| Cow::Borrowed("invalid u32"))
    })
    .cancel(do_cancel)
    .interact()?;
println!("answer {:?}", answer);

fn do_cancel() {
    cancel!("operation cancelled");
    std::process::exit(1);
}