Adding example for group and documentation

CHANGELOG.md

@@ -1,7 +1,10 @@
 ## Version 0.3 (in progress)
 
+* More tests for Help strings, improvements in formatting
+* Support type and set syntax in positionals help strings
+* Added help groups, with `->group("name")` syntax
+* Added initial support for ini file reading with `add_config` option.
 * Supports GCC 4.7 again
-* Support type and set syntax in positionals
 * Changes `setup` for an explicit help bool in constructor/`add_subcommand`
 
 

README.md

@@ -81,12 +81,19 @@ app.add_set(option_name,
             help_string="",
             default=false)
 
+app.add_config(option_name,
+               default_file_name="",
+               help_string="Read an ini file",
+               required=false)
+
 App* subcom = app.add_subcommand(name, discription);
 
 ```
 
 An option name must start with a alphabetic character or underscore. For long options, anything but an equals sign or a comma is valid after that. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form.
 
+Adding a configuration option is special. If it is present, it will be read along with the normal command line arguments. The file will be read if it exists, and does not throw an error unless required is `true`.
+
 > ### Example
 >
 > * `"one,-o,--one"`: Valid as long as not a flag, would create an option that can be specified positionally, or with `-o` or `--option`
@@ -98,11 +105,12 @@ The add commands return a pointer to an internally stored `Option`. If you set t
 
 * `->required()`: The program will quit if this option is not present
 * `->expected(N)`: Take `N` values instead of as many as possible, only for vector args
+* `->group(name)`: The help group to put the option in. No effect for positional options. Defaults to `"Options"`.
 * `->check(CLI::ExistingFile)`: Requires that the file exists if given
 * `->check(CLI::ExistingDirectory)`: Requires that the directory exists
 * `->check(CLI::NonexistentPath)`: Requires that the path does not exist
 
-These options return the `Option` pointer, so you can chain them together, and even skip storing the pointer entirely. Check takes any function that has the signature `bool(std::string)`.
+These options return the `Option` pointer, so you can chain them together, and even skip storing the pointer entirely. Check takes any function that has the signature `bool(std::string)`. If you want to change the default help option, it is available through `get_help_ptr`.
 
 
 On the command line, options can be given as:

examples/CMakeLists.txt

@@ -1,4 +1,8 @@
 add_executable(try try.cpp)
 target_link_libraries(try PUBLIC CLI)
+
 add_executable(try1 try1.cpp)
 target_link_libraries(try1 PUBLIC CLI)
+
+add_executable(try2 try2.cpp)
+target_link_libraries(try2 PUBLIC CLI)

examples/try2.cpp

@@ -0,0 +1,37 @@
+#include "CLI/CLI.hpp"
+
+
+int main (int argc, char** argv) {
+
+    CLI::App app("K3Pi goofit fitter");
+
+    std::string file;
+    CLI::Option* opt = app.add_option("-f,--file,file", file, "File name")
+        ->required()->group("Important");
+    
+    int count;
+    CLI::Option* copt = app.add_flag("-c,--count", count, "Counter")
+        ->required()->group("Important");
+
+    double value;// = 3.14;
+    app.add_option("-d,--double", value, "Some Value")
+        ->group("Other");
+
+    try {
+        app.run(argc, argv);
+    } catch (const CLI::Error &e) {
+        return app.exit(e);
+    }
+
+    std::cout << "Working on file: " << file
+              << ", direct count: " << app.count("--file")
+              << ", opt count: " << opt->count()
+              << std::endl;
+    std::cout << "Working on count: " << count
+              << ", direct count: " << app.count("--count")
+              << ", opt count: " << copt->count()
+              << std::endl;
+    std::cout << "Some value: " << value << std::endl;
+
+    return 0;
+}

include/CLI/App.hpp

@@ -85,6 +85,17 @@ public:
         }
     }
 
+    /// Get a pointer to the help flag.
+    Option* get_help_ptr() {
+        return help_flag;
+    }
+
+    /// Get a pointer to the config option.
+    Option* get_config_ptr() {
+        return ini_setting;
+    }
+
+    
     /// Create a new program. Pass in the same arguments as main(), along with a help string.
     App(std::string prog_description="", bool help=true)
         : prog_description(prog_description) {
@@ -290,22 +301,29 @@ public:
 
 
     /// Add a configuration ini file option
-    void add_config(std::string name="--config",
+    Option* add_config(std::string name="--config",
                  std::string default_filename="",
                  std::string help="Read an ini file",
                  bool required=false) {
 
         // Remove existing config if present
-        if(ini_setting != nullptr) {
-            auto iterator = std::find_if(std::begin(options), std::end(options),
-                    [this](const Option_p &v){return v.get() == ini_setting;});
-            if (iterator != std::end(options)) {
-                options.erase(iterator);
-            }
-        }
+        if(ini_setting != nullptr)
+            remove_option(ini_setting);
         ini_file = default_filename;
         ini_required = required;
         ini_setting = add_option(name, ini_file, help, default_filename!="");
+        return ini_setting;
+    }
+
+    /// Removes an option from the App. Takes an option pointer. Returns true if found and removed.
+    bool remove_option(Option* opt) {
+        auto iterator = std::find_if(std::begin(options), std::end(options),
+                [opt](const Option_p &v){return v.get() == opt;});
+        if (iterator != std::end(options)) {
+            options.erase(iterator);
+            return true;
+        }
+        return false;
     }
 
     /// This allows subclasses to inject code before callbacks but after parse