Refactor Parent Parsers documentation

This replaces the verbiage copied from the Python argparse documentation
and makes the code sample more concrete. This illustrates how to avoid the
multiple help output problem reported in #165.

Closes #165

Signed-off-by: Sean Robinson <sean.robinson@scottsdalecc.edu>
This commit is contained in:
Sean Robinson 2023-01-05 10:23:16 -07:00
parent a5ab5b0ce8
commit 04ac1fe366

View File

@ -687,25 +687,30 @@ main
### Parent Parsers ### Parent Parsers
Sometimes, several parsers share a common set of arguments. Rather than repeating the definitions of these arguments, a single parser with all the common arguments can be added as a parent to another ArgumentParser instance. The ```.add_parents``` method takes a list of ArgumentParser objects, collects all the positional and optional actions from them, and adds these actions to the ArgumentParser object being constructed: A parser may use arguments that could be used by other parsers.
These shared arguments can be added to a parser which is then used as a "parent" for parsers which also need those arguments. One or more parent parsers may be added to a parser with `.add_parents`. The positional and optional arguments in each parent is added to the child parser.
```cpp ```cpp
argparse::ArgumentParser parent_parser("main"); argparse::ArgumentParser surface_parser("surface", 1.0, argparse::default_arguments::none);
parent_parser.add_argument("--parent") parent_parser.add_argument("--area")
.default_value(0) .default_value(0)
.scan<'i', int>(); .scan<'i', int>();
argparse::ArgumentParser foo_parser("foo"); argparse::ArgumentParser floor_parser("floor");
foo_parser.add_argument("foo"); floor_parser.add_argument("tile_size").scan<'i', int>();
foo_parser.add_parents(parent_parser); floor_parser.add_parents(surface_parser);
foo_parser.parse_args({ "./main", "--parent", "2", "XXX" }); // parent = 2, foo = XXX floor_parser.parse_args({ "./main", "--area", "200", "12" }); // --area = 200, tile_size = 12
argparse::ArgumentParser bar_parser("bar"); argparse::ArgumentParser ceiling_parser("ceiling");
bar_parser.add_argument("--bar"); ceiling_parser.add_argument("--color");
bar_parser.parse_args({ "./main", "--bar", "YYY" }); // bar = YYY ceiling_parser.add_parents(surface_parser);
ceiling_parser.parse_args({ "./main", "--color", "gray" }); // --area = 0, --color = "gray"
``` ```
Note You must fully initialize the parsers before passing them via ```.add_parents```. If you change the parent parsers after the child parser, those changes will not be reflected in the child. Changes made to parents after they are added to a parser are not reflected in any child parsers. Completely initialize parent parsers before adding them to a parser.
Each parser will have the standard set of default arguments. Disable the default arguments in parent parsers to avoid duplicate help output.
### Subcommands ### Subcommands