Trait argh::FromArgs [−][src]
pub trait FromArgs: Sized { fn from_args(
command_name: &[&str],
args: &[&str]
) -> Result<Self, EarlyExit>; fn redact_arg_values(
_command_name: &[&str],
_args: &[&str]
) -> Result<Vec<String>, EarlyExit> { ... } }
Expand description
Types which can be constructed from a set of commandline arguments.
Required methods
Construct the type from an input set of arguments.
The first argument command_name
is the identifier for the current command. In most cases,
users should only pass in a single item for the command name, which typically comes from
the first item from std::env::args()
. Implementations however should append the
subcommand name in when recursively calling FromArgs::from_args for subcommands. This
allows argh
to generate correct subcommand help strings.
The second argument args
is the rest of the command line arguments.
Examples
/// Command to manage a classroom. #[derive(Debug, PartialEq, FromArgs)] struct ClassroomCmd { #[argh(subcommand)] subcommands: Subcommands, } #[derive(Debug, PartialEq, FromArgs)] #[argh(subcommand)] enum Subcommands { List(ListCmd), Add(AddCmd), } /// list all the classes. #[derive(Debug, PartialEq, FromArgs)] #[argh(subcommand, name = "list")] struct ListCmd { /// list classes for only this teacher. #[argh(option)] teacher_name: Option<String>, } /// add students to a class. #[derive(Debug, PartialEq, FromArgs)] #[argh(subcommand, name = "add")] struct AddCmd { /// the name of the class's teacher. #[argh(option)] teacher_name: String, /// the name of the class. #[argh(positional)] class_name: String, } let args = ClassroomCmd::from_args( &["classroom"], &["list", "--teacher-name", "Smith"], ).unwrap(); assert_eq!( args, ClassroomCmd { subcommands: Subcommands::List(ListCmd { teacher_name: Some("Smith".to_string()), }) }, ); // Help returns an error, but internally returns an `Ok` status. let early_exit = ClassroomCmd::from_args( &["classroom"], &["help"], ).unwrap_err(); assert_eq!( early_exit, argh::EarlyExit { output: r#"Usage: classroom <command> [<args>] Command to manage a classroom. Options: --help display usage information Commands: list list all the classes. add add students to a class. "#.to_string(), status: Ok(()), }, ); // Help works with subcommands. let early_exit = ClassroomCmd::from_args( &["classroom"], &["list", "help"], ).unwrap_err(); assert_eq!( early_exit, argh::EarlyExit { output: r#"Usage: classroom list [--teacher-name <teacher-name>] list all the classes. Options: --teacher-name list classes for only this teacher. --help display usage information "#.to_string(), status: Ok(()), }, ); // Incorrect arguments will error out. let err = ClassroomCmd::from_args( &["classroom"], &["lisp"], ).unwrap_err(); assert_eq!( err, argh::EarlyExit { output: "Unrecognized argument: lisp\n".to_string(), status: Err(()), }, );
Provided methods
Get a String with just the argument names, e.g., options, flags, subcommands, etc, but without the values of the options and arguments. This can be useful as a means to capture anonymous usage statistics without revealing the content entered by the end user.
The first argument command_name
is the identifier for the current command. In most cases,
users should only pass in a single item for the command name, which typically comes from
the first item from std::env::args()
. Implementations however should append the
subcommand name in when recursively calling FromArgs::from_args for subcommands. This
allows argh
to generate correct subcommand help strings.
The second argument args
is the rest of the command line arguments.
Examples
/// Command to manage a classroom. #[derive(FromArgs)] struct ClassroomCmd { #[argh(subcommand)] subcommands: Subcommands, } #[derive(FromArgs)] #[argh(subcommand)] enum Subcommands { List(ListCmd), Add(AddCmd), } /// list all the classes. #[derive(FromArgs)] #[argh(subcommand, name = "list")] struct ListCmd { /// list classes for only this teacher. #[argh(option)] teacher_name: Option<String>, } /// add students to a class. #[derive(FromArgs)] #[argh(subcommand, name = "add")] struct AddCmd { /// the name of the class's teacher. #[argh(option)] teacher_name: String, /// has the class started yet? #[argh(switch)] started: bool, /// the name of the class. #[argh(positional)] class_name: String, /// the student names. #[argh(positional)] students: Vec<String>, } let args = ClassroomCmd::redact_arg_values( &["classroom"], &["list"], ).unwrap(); assert_eq!( args, &[ "classroom", "list", ], ); let args = ClassroomCmd::redact_arg_values( &["classroom"], &["list", "--teacher-name", "Smith"], ).unwrap(); assert_eq!( args, &[ "classroom", "list", "--teacher-name", ], ); let args = ClassroomCmd::redact_arg_values( &["classroom"], &["add", "--teacher-name", "Smith", "--started", "Math", "Abe", "Sung"], ).unwrap(); assert_eq!( args, &[ "classroom", "add", "--teacher-name", "--started", "class_name", "students", "students", ], ); // `ClassroomCmd::redact_arg_values` will error out if passed invalid arguments. assert_eq!( ClassroomCmd::redact_arg_values(&["classroom"], &["add", "--teacher-name"]), Err(argh::EarlyExit { output: "No value provided for option '--teacher-name'.\n".into(), status: Err(()), }), ); // `ClassroomCmd::redact_arg_values` will generate help messages. assert_eq!( ClassroomCmd::redact_arg_values(&["classroom"], &["help"]), Err(argh::EarlyExit { output: r#"Usage: classroom <command> [<args>] Command to manage a classroom. Options: --help display usage information Commands: list list all the classes. add add students to a class. "#.to_string(), status: Ok(()), }), );