Crates.io | cliargs |
lib.rs | cliargs |
version | 0.2.0 |
source | src |
created_at | 2024-05-27 14:00:38.080079 |
updated_at | 2024-06-17 12:23:49.753545 |
description | Parses command line arguments and prints the help. |
homepage | |
repository | https://github.com/sttk/cliargs-rust |
max_upload_size | |
id | 1253374 |
size | 225,747 |
A library to parse command line arguments and print the help for Rust application.
This library provides the following functionalities:
--
option.-ofoo
but -o=foo
as an alternative to -o foo
for short option.In Cargo.toml
, write this crate as a dependency.
[dependencies]
cliargs = "0.2.0"
This crate provides the Cmd
struct to parse command line arguments.
The usage of this Cmd
struct is as follows:
Cmd
instanceThe Cmd::new
function creates a Cmd
instance with original command line arguments.
This function uses std::env::args_os
and OsString#into_string
to read command line arguments in order to avoid panic!
call that the user cannot control.
use cliargs::Cmd;
use cliargs::errors::InvalidOsArg;
let cmd = match Cmd::new() {
Ok(cmd) => cmd,
Err(InvalidOsArg::OsArgsContainInvalidUnicode { index, os_arg }) => {
panic!("Invalid Unicode data: {:?} (index: {})", os_arg, index);
}
};
Cmd
instance with the specified String
arrayThe Cmd::with_strings
function creates a Cmd
instance with the specified String
array.
use cliargs::Cmd;
use std::env;
let cmd = Cmd::with_strings(env::args());
Cmd
instance with the specified OsString
arrayThe Cmd::with_os_strings
function creates a Cmd
instance with the specified OsString
array.
use cliargs::Cmd;
use cliargs::errors::InvalidOsArg;
use std::env;
let cmd = match Cmd::with_os_strings(env::args_os()) {
Ok(cmd) => cmd,
Err(InvalidOsArg::OsArgsContainInvalidUnicode { index, os_arg }) => {
panic!("Invalid Unicode data: {:?} (index: {})", os_arg, index);
}
};
The Cmd
struct has the method which parses command line arguments without configurations.
This method automatically divides command line arguments to command arguments, options, and option arguments.
Command line arguments starts with -
or --
are options, and others are command arguments.
If you want to specify a value to an option, follows "="
and the value after the option, like foo=123
.
All command line arguments after --
are command arguments, even they starts with -
or --
.
use cliargs::Cmd;
use cliargs::errors::InvalidOption;
let mut cmd = Cmd::with_strings(vec![ /* ... */ ]);
match cmd.parse() {
Ok(_) => { /* ... */ },
Err(InvalidOption::OptionContainsInvalidChar { option }) => {
panic!("Option contains invalid character: {option}");
},
Err(err) => panic!("Invalid option: {}", err.option()),
}
The Cmd
struct has the method parse_with
which parses command line arguments with configurations.
This method takes an array of option configurations: OptCfg
, and divides command line arguments to options and command arguments according to this configurations..
An option configuration has fields: store_key
, names
, has_arg
, is_array
, defaults
, desc
, arg_in_help
, and validator
.
store_key
field is specified the key name to store the option value to the option map in the Cmd
instance.
If this field is not specified, the first element of names
field is used instead.
names
field is a string array and specified the option names, that are both long options and short options.
The order of elements in this field is used in a help text.
If you want to prioritize the output of short option name first in the help text, like -f, --foo-bar
, but use the long option name as the key in the option map, write store_key
and names
fields as follows: OptCfg::with(&[store_key("foo-bar"), names(&["f", "foo-bar"])])
.
has_arg
field indicates the option requires one or more values.
is_array
field indicates the option can have multiple values.
defaults
field is an array of string which is used as default one or more option arguments if the option is not specified.
desc
is a description of the option for help text.
arg_n_help
field is a text which is output after option name and aliases as an option value in help text.
validator
field is to set a function pointer which validates an option argument.
This crate provides the validator cliargs::validators::validate_number<T>
which validates whether an option argument is valid format as a number.
use cliargs::{Cmd, OptCfg};
use cliargs::OptCfgParam::{names, has_arg, defaults, validator, desc, arg_in_help};
use cliargs::validators::validate_number;
use cliargs::errors::InvalidOption;
let mut cmd = Cmd::with_strings(vec![ /* ... */ ]);
let opt_cfgs = vec![
OptCfg::with(&[
names(&["foo-bar"]),
desc("This is description of foo-bar."),
]),
OptCfg::with(&[
names(&["baz", "z"]),
has_arg(true),
defaults(&["1"]),
desc("This is description of baz."),
arg_in_help("<num>"),
validator(validate_number::<u32>),
]),
];
match cmd.parse_with(&opt_cfgs) {
Ok(_) => { /* ... */ },
Err(InvalidOption::OptionContainsInvalidChar { option }) => { /* ... */ },
Err(InvalidOption::UnconfiguredOption { option }) => { /* ... */ },
Err(InvalidOption::OptionNeedsArg { option, .. }) => { /* ... */ },
Err(InvalidOption::OptionTakesNoArg { option, .. }) => { /* ... */ },
Err(InvalidOption::OptionIsNotArray { option, .. }) => { /* ... */ },
Err(InvalidOption::OptionArgIsInvalid { option, opt_arg, details, .. }) => { /* ... */ },
Err(err) => panic!("Invalid option: {}", err.option()),
}
This crate supports Rust 1.74.1 or later.
% cargo msrv --no-check-feedback
Fetching index
Determining the Minimum Supported Rust Version (MSRV) for toolchain x86_64-apple-darwin
Using check command cargo check
Finished The MSRV is: 1.74.1 █████████████████████████████████████ 00:00:02
Copyright (C) 2024 Takayuki Sato
This program is free software under MIT License.
See the file LICENSE in this distribution for more details.