doc,comment: added descriptions about Cmd#parse_for (#21)

Author: sttk

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<T>` 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="<s>")]
+    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
 ```
 
 

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

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);