Help

Table of Contents

• help_data_type
  • help_data_type::children
  • Flattening
• Help Node
• Help Formatting

help_data_type

Help output is crucial for most application's command line interface, in arg_router this is implemented by defining a public type called help_data_type that is equivalent to:

template <bool Flatten>
struct help_data_type {
    using label = ...; // Compile-time string
    using description = ...; // Compile-time string
    using children = std::tuple<help_data_type<...>, ...>;
 
    // New in v1.4!
    template <typename OwnerNode, typename FilterFn>
    [[nodiscard]] static vector<runtime_help_data> runtime_children(const OwnerNode& owner,
                                                                    FilterFn&& f)
    {
        return ...;
    }
}

1. label which provides the node name, and may be empty
2. description which provides the help blurb, and may be empty
3. children which provides a tuple of other help_data_type compatible structure types defining child help data
4. runtime_children(..) is an optional method that is new for v1.4. It allows for runtime modification of the help output (initially to support policy::runtime_enable), via skipping child output if the filter parameter returns false for a given child - see runtime_help_data and tree_node::default_leaf_help_data_type for more information

Help data is all generated at compile-time and the result held in program static read-only memory. For parse tree leaf-level nodes (e.g. flag_t), the library provides a default alias that generates this data for you: tree_node::default_leaf_help_data_type.

help_data_type::children

The help_data_type::children type can be seen as the child nodes in a 'help tree'. Typically it will carry nothing as not flattening is the default and most nodes in the parse tree are leaves (flags, args, etc.), the most common scenario where this is not true is when defined by a mode-like type in which case children will be a tuple of the child parse tree node's help_data_types.

An outlier to the above is dependency::one_of_t and dependency::alias_group_t, where the help_data_type::children tuple elements are the still the node's children, but it will ignore the flattening NTTP.

Flattening

The boolean NTTP the help_data_type accepts is for 'flattening'. 'Flattened' help output is where all the child help data is displayed with the parent, rather than only the parent output being displayed and the children help data having to be explicitly requested through the command line - see the README.md for examples of this.

From the node developer's point of view, typically a non-flattened help_data_type would simply empty the children tuple (the parameter is ignored for the tree_node::default_leaf_help_data_type as it will never have children).

Help Node

Obviously the types don't do anything on their own, they are read by the help_t node which at runtime collects and formats the complete output. The help node is an argument-like node (e.g. arg_t), it accepts a chain of mode-like type names through the parse tree to show only the help for that node (see the README.md for examples of this). To achieve this, in the node's parse method it iteratively searches through the tree's descendents (starting at the root), the last node requested has it's help data shown.

The help_t node checks for the presence of a policy::flatten_help_t policy - flattening is determined at compile-time.

Help Formatting

By default help_t will use policy::default_help_formatter_t, which generates basic output as shown by the examples in the README. The formatter delegates much of the formatting duty to formatter components:

• LineFormatter
  As the same suggests this controls the printing of the argument output. It is called once per node. default_help_formatter_t will use policy::help_formatter_component::default_line_formatter by default.
• PreambleFormatter
  This controls the printing of the preamble, which typically consists of the program name, version, and introduction text. These are provided by policy::program_name_t, etc. that are associated with the owning help_t. default_help_formatter_t will use policy::help_formatter_component::default_preamble_formatter by default.
• AddendumFormatter
  The controls the printing of the addendum, which text printed after the argument documentation. The text is provided by the policy::program_addendum_t associated with the owning help_t. default_help_formatter_t will use policy::help_formatter_component::default_addendum_formatter by default.

You will notice that there's no API information here, that's because the API is not fixed as the formatter components belong the formatter. So minor changes can be achieved via writing your own formatter components, whilst more dramatic changes will require a new formatter.

The default line formatter (policy::help_formatter_component::default_line_formatter) is quite basic, so a colour version is provided in the library too: policy::help_formatter_component::colour_line_formatter.