Formatters

.codecov.yml

@@ -1,3 +1,4 @@
 
 ignore:
   - "tests"
+  - "examples"

CHANGELOG.md

@@ -1,3 +1,29 @@
+### Version 1.6: Formatting
+
+Added a new formatting system. You can now set the formatter on Apps.
+
+* Added `CLI::Formatter` and `formatter` slot for apps, inherited.
+* Added `help_all` support (not added by default)
+* Added filter argument to `get_subcommands`, `get_options`; use empty filter `{}` to avoid filtering
+* Added `get_groups()` to get groups
+* Added getters for the missing parts of options (help no longer uses any private parts)
+
+Changes to the help system (most normal users will not notice this):
+
+* Renamed `single_name` to `get_name(false, false)` (the default)
+* The old `get_name()` is now `get_name(false, true)`
+* The old `get_pname()` is now `get_name(true, false)`
+* Removed `help_*` functions
+* Protected function `_has_help_positional` removed
+* `format_help` can now be chained
+
+
+Other small changes:
+
+* Testing (only) now uses submodules.
+* Removed `requires` in favor of `needs` (deprecated in last version)
+* Better CMake policy handling
+
 ### Version 1.5.3: Compiler compatibility
 This version fixes older AppleClang compilers by removing the optimization for casting. The minimum version of Boost Optional supported has been clarified to be 1.58. CUDA 7.0 NVCC is now supported.
 

CMakeLists.txt

@@ -61,11 +61,6 @@ include(CMakeDependentOption)
 # Allow IDE's to group targets into folders
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
-if(CMAKE_BUILD_TYPE STREQUAL Coverage)
-    include(CodeCoverage)
-    setup_target_for_coverage(CLI11_coverage ctest coverage)
-endif()
-
 file(GLOB CLI11_headers "${CMAKE_CURRENT_SOURCE_DIR}/include/CLI/*")
 # To see in IDE, must be listed for target
 

README.md

@@ -247,13 +247,16 @@ There are several options that are supported on the main app and subcommands. Th
 * `.get_parent()`: Get the parent App or nullptr if called on master App.
 * `.get_options()`: Get the list of all defined option pointers (useful for processing the app for custom output formats).
 * `.parse_order()`: Get the list of option pointers in the order they were parsed (including duplicates).
+* `.formatter(fmt)`: Set a formatter, with signature `std::string(const App*, std::string, AppFormatMode)`. See Formatting for more details.
 * `.get_description()`: Access the description.
 * `.parsed()`: True if this subcommand was given on the command line.
 * `.set_name(name)`: Add or change the name.
 * `.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.
 * `.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.
 * `.set_footer(message)`: Set text to appear at the bottom of the help string.
+* `.set_help_flag(name, message)`: Set the help flag name and message, returns a pointer to the created option.
+* `.set_help_all_flag(name, message)`: Set the help all flag name and message, returns a pointer to the created option. Expands subcommands.
 * `.set_failure_message(func)`: Set the failure message function. Two provided: `CLI::FailureMessage::help` and `CLI::FailureMessage::simple` (the default).
 * `.group(name)`: Set a group name, defaults to `"Subcommands"`. Setting `""` will be hide the subcommand.
 
@@ -300,11 +303,20 @@ app.option_defaults()->required();
 
 The default settings for options are inherited to subcommands, as well.
 
+## Formatting
+
+The job of formatting help printouts is delegated to a formatter callable object on Apps and Options. You are free to replace either formatter by calling `formatter(fmt)` on an `App`, where fmt is any copyable callable with the correct signature. 
+CLI11 comes with a default App formatter functional, `Formatter`. It is customizable; you can set `label(key, value)` to replace the default labels like `REQUIRED`, and `column_width(n)` to set the width of the columns before you add the functional to the app or option. You can also override almost any stage of the formatting process in a subclass of either formatter. If you want to make a new formatter from scratch, you can do
+that too; you just need to implement the correct signature. The first argument is a const pointer to the in question. The formatter will get a `std::string` usage name as the second option, and a `AppFormatMode` mode for the final option. It should return a `std::string`.
+
+The `AppFormatMode` can be `Normal`, `All`, or `Sub`, and it indicates the situation the help was called in. `Sub` is optional, but the default formatter uses it to make sure expanded subcommands are called with
+their own formatter since you can't access anything but the call operator once a formatter has been set.
+
 ## Subclassing
 
-The App class was designed allow toolkits to subclass it, to provide preset default options (see above) and setup/teardown code. Subcommands remain an unsubclassed `App`, since those are not expected to need setup and teardown. The default `App` only adds a help flag, `-h,--help`, than can removed/replaced using `.set_help_flag(name, help_string)`. You can remove options if you have pointers to them using `.remove_option(opt)`. You can add a `pre_callback` override to customize the after parse
+The App class was designed allow toolkits to subclass it, to provide preset default options (see above) and setup/teardown code. Subcommands remain an unsubclassed `App`, since those are not expected to need setup and teardown. The default `App` only adds a help flag, `-h,--help`, than can removed/replaced using `.set_help_flag(name, help_string)`. You can also set a help-all flag with `.set_help_all_flag(name, help_string)`; this will expand the subcommands (one level only). You can remove options if you have pointers to them using `.remove_option(opt)`. You can add a `pre_callback` override to customize the after parse
 but before run behavior, while
-still giving the user freedom to `set_callback` on the main app.  
+still giving the user freedom to `set_callback` on the main app.
 
 The most important parse function is `parse(std::vector<std::string>)`, which takes a reversed list of arguments (so that `pop_back` processes the args in the correct order). `get_help_ptr` and `get_config_ptr` give you access to the help/config option pointers. The standard `parse` manually sets the name from the first argument, so it should not be in this vector.