Add public help API

Author: andrey-zherikov

docs/ad.tree

@@ -31,6 +31,11 @@
         <toc-element topic="ansiStylingArgument.md"/>
         <toc-element topic="CLI-API.md"/>
         <toc-element topic="Config.md"/>
+        <toc-element toc-title="Help">
+            <toc-element topic="HelpScreen.md"/>
+            <toc-element topic="HelpPrinter.md"/>
+            <toc-element topic="...HelpInfo.md"/>
+        </toc-element>
         <toc-element topic="Param-RawParam.md"/>
         <toc-element topic="Result.md"/>
         <toc-element topic="Style.md"/>

docs/code_snippets/config_helpPrinter.d

@@ -0,0 +1,20 @@
+import argparse;
+
+struct T
+{
+    string a;
+}
+
+enum Config cfg = {
+    helpPrinter:
+        (Style style, CommandHelpInfo[] cmds)
+        {
+            import std.stdio : stderr;
+            scope auto output = stderr.lockingTextWriter();
+
+            new HelpPrinter(style).printHelp(_ => output.put(_), cmds);
+        }
+};
+
+T t;
+assert(!CLI!(cfg, T).parseArgs(t, ["-h"]));

docs/topics/reference/...HelpInfo.md

@@ -0,0 +1,53 @@
+# ...HelpInfo
+
+There are few structs that describe help information for argument parsing entities.
+
+## ArgumentHelpInfo
+
+`ArgumentHelpInfo` contains data that is needed to print help for an command line argument:
+
+- `const string[] names` - all short and long names of an argument prefixed with `Config.shortNamePrefix` or
+  `Config.shortNamePrefix` respectively.
+- `string description` - description of an argument.
+- `string placeholder` - value placeholder (eg. `VALUE` for `--foo VALUE` argument).
+- `bool multipleOccurrence` - flag denoting that an argument can appear multiple times in command line.
+- `bool optionalValue` - flag denoting that the value is optional for argument.
+- `bool optionalArgument` - flag denoting that an argument itself is optional.
+- `bool positional` - flag denoting that an argument is positional (otherwise, it's named argument).
+- `bool hidden` - flag denoting that an argument should be hidden from help screen.
+- `bool booleanFlag` - flag denoting that an argument is a boolean flag.
+
+## ArgumentGroupHelpInfo
+
+`ArgumentGroupHelpInfo` contains information about arguments group:
+
+- `string name` - name of the group.
+- `string description` - group description.
+- `const size_t[] argIndex` - indexes of arguments that belong to this group. Arguments themselves are store in [`CommandHelpInfo`](#commandhelpinfo).
+
+## SubCommandHelpInfo
+
+`SubCommandHelpInfo` contains information about subcommand:
+
+- `const string[] names` - subcommand names.
+- `string description` - subcommand description.
+
+## CommandHelpInfo
+
+`CommandHelpInfo` contains information about subcommand:
+
+- `string name` - command name.
+- `string usage` - command usage.
+- `string description` - command description.
+- `string epilog` - command epilog.
+- `ArgumentHelpInfo[] arguments` - all arguments of the command.
+- `ArgumentGroupHelpInfo requiredGroup` - group of required arguments of the command.
+- `ArgumentGroupHelpInfo optionalGroup` - group of optional arguments of the command.
+- `ArgumentGroupHelpInfo[] userGroups` - user-defined groups of arguments of the command.
+- `SubCommandHelpInfo[] subCommands` - subcommands.
+
+This struct also has the following helpers to iterate over positional or named arguments only - the both return filtered
+range of arguments (`ArgumentHelpInfo` objects):
+
+- `auto positionalArguments() const`
+- `auto namedArguments() const`

docs/topics/reference/Config.md

@@ -168,6 +168,20 @@ Help text from the first part of the example code above:
 
 <img src="config_styling.png" alt="Config styling example" border-effect="rounded"/>
 
+## Help printer {id="helpPrinter"}
+
+`Config.helpPrinter` is a handler function to print help screen.
+It receives two parameters:
+- `Style style` - style that should be applied to help screen.
+- `CommandHelpInfo[] cmds` - current stack of (sub)commands starting with top-level command.
+  For example, if command line contains `tool subcmd1 subcmd2 -h` then `cmd` will contain array of `CommandHelpInfo`
+  objects that corresponds to `tool`, `subcmd1`, `subcmd2` commands respectively.
+
+Example:
+
+<code-block src="code_snippets/config_helpPrinter.d" lang="c++"/>
+
+
 ## Error handling {id="errorHandler"}
 
 `Config.errorHandler` is a handler function for all errors occurred during command line parsing.