From f73ab84e263835bf365a1dc9fe363fe35188b39d Mon Sep 17 00:00:00 2001 From: sttk Date: Mon, 22 Jul 2024 18:27:17 +0900 Subject: [PATCH] doc,comment: added descriptions about Cmd#parse_for --- README.md | 77 +++++++++++++++++++++++++++++++++++++++-- src/lib.rs | 2 ++ tests/parse_for_test.rs | 5 ++- 3 files changed, 80 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e5d0c9d..0c8f29a 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This library provides the following functionalities: - This library doesn't support numeric short option. - This library supports not `-ofoo` but `-o=foo` as an alternative to `-o foo` for short option. - Supports parsing with option configurations. -- Supports parsing with an object which stores option values and has annotations of fields. *(To be added)* +- Supports parsing with option configurations made from struct fields and attributes, and setting the option values to them. - Is able to parse command line arguments including sub commands. *(To be added)* - Generates help text from option configurations. *(To be added)* @@ -119,6 +119,10 @@ If you want to prioritize the output of short option name first in the help text `validator` field is to set a function pointer which validates an option argument. This crate provides the validator `cliargs::validators::validate_number` which validates whether an option argument is valid format as a number. +The ownership of the vector of option configurations which is passed as an argument of this method +is moved to this method and set to the public field `cfgs` of [Cmd] instance. +If you want to access the option configurations after parsing, get them from this field. + ``` use cliargs::{Cmd, OptCfg}; use cliargs::OptCfgParam::{names, has_arg, defaults, validator, desc, arg_in_help}; @@ -141,7 +145,7 @@ let opt_cfgs = vec![ ]), ]; -match cmd.parse_with(&opt_cfgs) { +match cmd.parse_with(opt_cfgs) { Ok(_) => { /* ... */ }, Err(InvalidOption::OptionContainsInvalidChar { option }) => { /* ... */ }, Err(InvalidOption::UnconfiguredOption { option }) => { /* ... */ }, @@ -153,6 +157,73 @@ match cmd.parse_with(&opt_cfgs) { } ``` +### Parse for a OptStore struct + +The `Cmd` struct has the method `parse_for` which parses command line arguments and set their +option values to the option store which is passed as an argument. + +This method divides command line arguments to command arguments and options, then sets +each option value to a curresponding field of the option store. + +Within this method, a vector of `OptCfg` is made from the fields of the option store. +This [OptCfg] vector is set to the public field `cfgs` of the `Cmd` instance. +If you want to access this option configurations, get them from this field. + +An option configuration corresponding to each field of an option store is determined by +its type and `opt` field attribute. +If the type is bool, the option takes no argument. +If the type is integer, floating point number or string, the option can takes single option +argument, therefore it can appear once in command line arguments. +If the type is a vector, the option can takes multiple option arguments, therefore it can +appear multiple times in command line arguments. + +A `opt` field attribute can have the following pairs of name and value: one is `cfg` to +specify `names` and `defaults` fields of `OptCfg` struct, another is `desc` to specify +`desc` field, and yet another is `arg` to specify `arg_in_help` field. + +The format of `cfg` is like `cfg="f,foo=123"`. +The left side of the equal sign is the option name(s), and the right side is the default +value(s). +If there is no equal sign, it is determined that only the option name is specified. +If you want to specify multiple option names, separate them with commas. +If you want to specify multiple default values, separate them with commas and round them +with square brackets, like `[1,2,3]`. +If you want to use your favorite carachter as a separator, you can use it by putting it on +the left side of the open square bracket, like `/[1/2/3]`. + +NOTE: A default value of empty string array option in a field attribute is `[]`, like +`#[opt(cfg="=[]")]`, but it doesn't represent an array which contains only one empty +string. +If you want to specify an array which contains only one emtpy string, write nothing after +`=` symbol, like `#[opt(cfg="=")]`. + +``` +use cliargs::Cmd; +use cliargs::errors::InvalidOption; + +#[derive(cliargs::OptStore)] +struct MyOptions { + #[opt(cfg = "f,foo-bar", desc="The description of foo_bar.")] + foo_bar: bool, + #[opt(cfg = "b,baz", desc="The description of baz.", arg="")] + baz: String, +} +let mut my_options = MyOptions::with_defaults(); + +let mut cmd = Cmd::with_strings(vec![ /* ... */ ]); +match cmd.parse_for(&mut my_options) { + 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()), +} + +let opt_cfgs = &cmd.cfgs; +``` ## Supporting Rust versions @@ -163,7 +234,7 @@ This crate supports Rust 1.74.1 or later. 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 + Finished The MSRV is: 1.74.1 █████████████████████████████████████████████████████████ 00:00:04 ``` diff --git a/src/lib.rs b/src/lib.rs index 2d7afc6..4b1e0a8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,6 +12,8 @@ //! - This library supports not `-ofoo` but `-o=foo` as an alternative to //! `-o foo` for short option. //! - Supports parsing with option configurations. +//! - Supports parsing with option configurations made from struct fields and attributes, and +//! setting the option values to them. //! //! [posix]: https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html#Argument-Syntax //! [gnu]: https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html diff --git a/tests/parse_for_test.rs b/tests/parse_for_test.rs index 90f03ec..2b52d61 100644 --- a/tests/parse_for_test.rs +++ b/tests/parse_for_test.rs @@ -50,7 +50,10 @@ mod tests_of_parse_for { assert_eq!(cmd.cfgs.len(), 1); assert_eq!(cmd.cfgs[0].store_key, "foo_bar"); - assert_eq!(cmd.cfgs[0].names, ["f".to_string(), "b".to_string(), "foo-bar".to_string()]); + assert_eq!( + cmd.cfgs[0].names, + ["f".to_string(), "b".to_string(), "foo-bar".to_string()] + ); assert_eq!(cmd.cfgs[0].has_arg, false); assert_eq!(cmd.cfgs[0].is_array, false); assert_eq!(cmd.cfgs[0].defaults, None);