Adding some info to docs

Henry Fredrick Schreiner · Henry Schreiner
1 parent 89c57961
Showing 3 changed files with 17 additions and 9 deletions
CHANGELOG.md
README.md
tests/SubcommandTest.cpp
+## Version 1.3 (in progress)
+* `parse` no longer returns (so `CLI11_PARSE` is always usable) [#37](https://github.com/CLIUtils/CLI11/pull/37)
+* Added `remaining()` and `remaining_size()` [#37](https://github.com/CLIUtils/CLI11/pull/37)
+* `allow_extras` and `prefix_command` are now valid on subcommands [#37](https://github.com/CLIUtils/CLI11/pull/37)
+
 ## Version 1.2
 * Added functional form of flag [#33](https://github.com/CLIUtils/CLI11/pull/33), automatic on C++14
@@ -101,7 +101,7 @@ try {
 }
 ```
-> Note: The final five lines are so common, they have a dedicated macro: `CLI11_PARSE(app, argc, argv)`. You can use that as long as you don't need the return value of `.parse`.
+> Note: The final five lines are so common, they have a dedicated macro: `CLI11_PARSE(app, argc, argv)`.
 The initialization is just one line, adding options is just two each. The try/catch block ensures that `-h,--help` or a parse error will exit with the correct return code (selected from `CLI::ExitCodes`). (The return here should be inside `main`). After the app runs, the filename will be set to the correct value if it was passed, otherwise it will be set to the default. You can check to see if this was passed on the command line with `app.count("--file")`.
@@ -176,11 +176,14 @@ On the command line, options can be given as:
 * `--file=filename` (equals)
 Extra positional arguments will cause the program to exit, so at least one positional option with a vector is recommended if you want to allow extraneous arguments.
-If you set `.allow_extras()` on the main `App`, the parse function will return the left over arguments instead of throwing an error. You can access a vector of pointers to the parsed options in the original order using `parse_order()`.
+If you set `.allow_extras()` on the main `App`, you will not get an error. You can access the missing options using `remaining` (if you have subcommands, `app.remaining(true)` will get all remaining options, subcommands included).
+
+You can access a vector of pointers to the parsed options in the original order using `parse_order()`.
 If `--` is present in the command line,
 everything after that is positional only.
+
 ## Subcommands
 Subcommands are supported, and can be nested infinitely. To add a subcommand, call the `add_subcommand` method with a name and an optional description. This gives a pointer to an `App` that behaves just like the main app, and can take options or further subcommands. Add `->ignore_case()` to a subcommand to allow any variation of caps to also be accepted. Children inherit the current setting from the parent. You cannot add multiple matching subcommand names at the same level (including ignore
@@ -205,8 +208,8 @@ There are several options that are supported on the main app and subcommands. Th
 * `.get_subcommands()`: The list of subcommands given on the command line
 * `.parsed()`: True if this subcommand was given on the command line
 * `.set_callback(void() function)`: Set the callback that runs at the end of parsing. The options have already run at this point.
-* `.allow_extras()`: Do not throw an error if extra arguments are left over (Only useful on the main `App`, as that's the one that throws errors).
-* `.prefix_command()`: Like `allow_extras`, but stop immediately on the first unrecognised item. It is ideal for allowing your app to be a "prefix" to calling another app.
+* `.allow_extras()`: Do not throw an error if extra arguments are left over
+* `.prefix_command()`: Like `allow_extras`, but stop immediately on the first unrecognised item. It is ideal for allowing your app or subcommand to be a "prefix" to calling another app.
 > Note: if you have a fixed number of required positional options, that will match before subcommand names.
@@ -345,14 +345,14 @@ TEST_F(TApp, PrefixProgram) {
 TEST_F(TApp, PrefixSubcom) {
     auto subc = app.add_subcommand("subc");
     subc->prefix_command();
-    
+
     app.add_flag("--simple");
-    
+
     args = {"--simple", "subc", "other", "--simple", "--mine"};
     run();
-    
-    EXPECT_EQ(app.remaining_size(), (size_t) 0);
-    EXPECT_EQ(app.remaining_size(true), (size_t) 3);
+
+    EXPECT_EQ(app.remaining_size(), (size_t)0);
+    EXPECT_EQ(app.remaining_size(true), (size_t)3);
     EXPECT_EQ(subc->remaining(), std::vector<std::string>({"other", "--simple", "--mine"}));
 }