CLI::Formatter Class Reference

#include <CLI11.hpp>

Inheritance diagram for CLI::Formatter:

Collaboration diagram for CLI::Formatter:

Public Member Functions
	Formatter ()=default
	Formatter (const Formatter &)=default
	Formatter (Formatter &&)=default
Overridables
virtual std::string	make_group (std::string group, bool is_positional, std::vector< const Option * > opts) const
virtual std::string	make_positionals (const App *app) const
	This prints out just the positionals "group".
std::string	make_groups (const App *app, AppFormatMode mode) const
	This prints out all the groups of options.
virtual std::string	make_subcommands (const App *app, AppFormatMode mode) const
	This prints out all the subcommands.
virtual std::string	make_subcommand (const App *sub) const
	This prints out a subcommand.
virtual std::string	make_expanded (const App *sub) const
	This prints out a subcommand in help-all.
virtual std::string	make_footer (const App *app) const
	This prints out all the groups of options.
virtual std::string	make_description (const App *app) const
	This displays the description line.
virtual std::string	make_usage (const App *app, std::string name) const
	This displays the usage line.
std::string	make_help (const App *, std::string, AppFormatMode) const override
	This puts everything together.
Options
virtual std::string	make_option (const Option *opt, bool is_positional) const
	This prints out an option help line, either positional or optional form.
virtual std::string	make_option_name (const Option *, bool) const
	This is the name part of an option, Default: left column.
virtual std::string	make_option_opts (const Option *) const
	This is the options part of the name, Default: combined into left column.
virtual std::string	make_option_desc (const Option *) const
	This is the description. Default: Right column, on new line if left column too large.
virtual std::string	make_option_usage (const Option *opt) const
	This is used to print the name on the USAGE line.
Public Member Functions inherited from CLI::FormatterBase
	FormatterBase ()=default
	FormatterBase (const FormatterBase &)=default
	FormatterBase (FormatterBase &&)=default
virtual	~FormatterBase () noexcept
	Adding a destructor in this form to work around bug in GCC 4.7.
void	label (std::string key, std::string val)
	Set the "REQUIRED" label.
void	column_width (std::size_t val)
	Set the column width.
std::string	get_label (std::string key) const
	Get the current value of a name (REQUIRED, etc.)
std::size_t	get_column_width () const
	Get the current column width.

Additional Inherited Members
Protected Attributes inherited from CLI::FormatterBase
std::size_t	column_width_ {30}
	The width of the first column.
std::map< std::string, std::string >	labels_ {}
	The required help printout labels (user changeable) Values are Needs, Excludes, etc.

Detailed Description

This is the default Formatter for CLI11. It pretty prints help output, and is broken into quite a few overridable methods, to be highly customizable with minimal effort.

Definition at line 3254 of file CLI11.hpp.

Constructor & Destructor Documentation

Formatter() [1/3]

CLI::Formatter::Formatter ( )

default

Formatter() [2/3]

CLI::Formatter::Formatter ( const Formatter & )

default

Formatter() [3/3]

CLI::Formatter::Formatter ( Formatter && )

default

Member Function Documentation

make_description()

std::string CLI::Formatter::make_description ( const App * app ) const

inlinevirtual

Definition at line 8005 of file CLI11.hpp.

                                                                 {
    std::string desc = app->get_description();
    auto min_options = app->get_require_option_min();
    auto max_options = app->get_require_option_max();
    if(app->get_required()) {
        desc += " REQUIRED ";
    }
    if((max_options == min_options) && (min_options > 0)) {
        if(min_options == 1) {
            desc += " \n[Exactly 1 of the following options is required]";
        } else {
            desc += " \n[Exactly " + std::to_string(min_options) + "options from the following list are required]";
        }
    } else if(max_options > 0) {
        if(min_options > 0) {
            desc += " \n[Between " + std::to_string(min_options) + " and " + std::to_string(max_options) +
                    " of the follow options are required]";
        } else {
            desc += " \n[At most " + std::to_string(max_options) + " of the following options are allowed]";
        }
    } else if(min_options > 0) {
        desc += " \n[At least " + std::to_string(min_options) + " of the following options are required]";
    }
    return (!desc.empty()) ? desc + "\n" : std::string{};
}

Here is the caller graph for this function:

make_expanded()

std::string CLI::Formatter::make_expanded ( const App * sub ) const

inlinevirtual

Definition at line 8153 of file CLI11.hpp.

                                                              {
    std::stringstream out;
    out << sub->get_display_name() << "\n";
 
    out << make_description(sub);
    out << make_positionals(sub);
    out << make_groups(sub, AppFormatMode::Sub);
    out << make_subcommands(sub, AppFormatMode::Sub);
 
    // Drop blank spaces
    std::string tmp = detail::find_and_replace(out.str(), "\n\n", "\n");
    tmp = tmp.substr(0, tmp.size() - 1); // Remove the final '\n'
 
    // Indent all but the first line (the name)
    return detail::find_and_replace(tmp, "\n", "\n  ") + "\n";
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_footer()

std::string CLI::Formatter::make_footer ( const App * app ) const

inlinevirtual

Definition at line 8073 of file CLI11.hpp.

                                                            {
    std::string footer = app->get_footer();
    if(footer.empty()) {
        return std::string{};
    }
    return footer + "\n";
}

Here is the caller graph for this function:

make_group()

std::string CLI::Formatter::make_group ( std::string group, bool is_positional, std::vector< const Option * > opts ) const

inlinevirtual

This prints out a group of options with title

Definition at line 7960 of file CLI11.hpp.

                                                                                               {
    std::stringstream out;
 
    out << "\n" << group << ":\n";
    for(const Option *opt : opts) {
        out << make_option(opt, is_positional);
    }
 
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_groups()

std::string CLI::Formatter::make_groups ( const App * app, AppFormatMode mode ) const

inline

Definition at line 7981 of file CLI11.hpp.

                                                                                {
    std::stringstream out;
    std::vector<std::string> groups = app->get_groups();
 
    // Options
    for(const std::string &group : groups) {
        std::vector<const Option *> opts = app->get_options([app, mode, &group](const Option *opt) {
            return opt->get_group() == group                    // Must be in the right group
                   && opt->nonpositional()                      // Must not be a positional
                   && (mode != AppFormatMode::Sub               // If mode is Sub, then
                       || (app->get_help_ptr() != opt           // Ignore help pointer
                           && app->get_help_all_ptr() != opt)); // Ignore help all pointer
        });
        if(!group.empty() && !opts.empty()) {
            out << make_group(group, false, opts);
 
            if(group != groups.back())
                out << "\n";
        }
    }
 
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_help()

std::string CLI::Formatter::make_help ( const App * app, std::string name, AppFormatMode mode ) const

inlineoverridevirtual

Implements CLI::FormatterBase.

Definition at line 8081 of file CLI11.hpp.

                                                                                              {
 
    // This immediately forwards to the make_expanded method. This is done this way so that subcommands can
    // have overridden formatters
    if(mode == AppFormatMode::Sub)
        return make_expanded(app);
 
    std::stringstream out;
    if((app->get_name().empty()) && (app->get_parent() != nullptr)) {
        if(app->get_group() != "Subcommands") {
            out << app->get_group() << ':';
        }
    }
 
    out << make_description(app);
    out << make_usage(app, name);
    out << make_positionals(app);
    out << make_groups(app, mode);
    out << make_subcommands(app, mode);
    out << '\n' << make_footer(app);
 
    return out.str();
}

Here is the call graph for this function:

make_option()

virtual std::string CLI::Formatter::make_option ( const Option * opt, bool is_positional ) const

inlinevirtual

Definition at line 3299 of file CLI11.hpp.

                                                                               {
        std::stringstream out;
        detail::format_help(
            out, make_option_name(opt, is_positional) + make_option_opts(opt), make_option_desc(opt), column_width_);
        return out.str();
    }

Here is the call graph for this function:

Here is the caller graph for this function:

make_option_desc()

std::string CLI::Formatter::make_option_desc ( const Option * opt ) const

inlinevirtual

Definition at line 8208 of file CLI11.hpp.

{ return opt->get_description(); }

Here is the call graph for this function:

Here is the caller graph for this function:

make_option_name()

std::string CLI::Formatter::make_option_name ( const Option * opt, bool is_positional ) const

inlinevirtual

Definition at line 8170 of file CLI11.hpp.

                                                                                        {
    if(is_positional)
        return opt->get_name(true, false);
 
    return opt->get_name(false, true);
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_option_opts()

std::string CLI::Formatter::make_option_opts ( const Option * opt ) const

inlinevirtual

Definition at line 8177 of file CLI11.hpp.

                                                                    {
    std::stringstream out;
 
    if(opt->get_type_size() != 0) {
        if(!opt->get_type_name().empty())
            out << " " << get_label(opt->get_type_name());
        if(!opt->get_default_str().empty())
            out << "=" << opt->get_default_str();
        if(opt->get_expected_max() == detail::expected_max_vector_size)
            out << " ...";
        else if(opt->get_expected_min() > 1)
            out << " x " << opt->get_expected();
 
        if(opt->get_required())
            out << " " << get_label("REQUIRED");
    }
    if(!opt->get_envname().empty())
        out << " (" << get_label("Env") << ":" << opt->get_envname() << ")";
    if(!opt->get_needs().empty()) {
        out << " " << get_label("Needs") << ":";
        for(const Option *op : opt->get_needs())
            out << " " << op->get_name();
    }
    if(!opt->get_excludes().empty()) {
        out << " " << get_label("Excludes") << ":";
        for(const Option *op : opt->get_excludes())
            out << " " << op->get_name();
    }
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_option_usage()

std::string CLI::Formatter::make_option_usage ( const Option * opt ) const

inlinevirtual

Definition at line 8210 of file CLI11.hpp.

                                                                     {
    // Note that these are positionals usages
    std::stringstream out;
    out << make_option_name(opt, true);
    if(opt->get_expected_max() >= detail::expected_max_vector_size)
        out << "...";
    else if(opt->get_expected_max() > 1)
        out << "(" << opt->get_expected() << "x)";
 
    return opt->get_required() ? out.str() : "[" + out.str() + "]";
}

Here is the call graph for this function:

make_positionals()

std::string CLI::Formatter::make_positionals ( const App * app ) const

inlinevirtual

Definition at line 7971 of file CLI11.hpp.

                                                                 {
    std::vector<const Option *> opts =
        app->get_options([](const Option *opt) { return !opt->get_group().empty() && opt->get_positional(); });
 
    if(opts.empty())
        return std::string();
 
    return make_group(get_label("Positionals"), true, opts);
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_subcommand()

std::string CLI::Formatter::make_subcommand ( const App * sub ) const

inlinevirtual

Definition at line 8147 of file CLI11.hpp.

                                                                {
    std::stringstream out;
    detail::format_help(out, sub->get_name(), sub->get_description(), column_width_);
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_subcommands()

std::string CLI::Formatter::make_subcommands ( const App * app, AppFormatMode mode ) const

inlinevirtual

Definition at line 8105 of file CLI11.hpp.

                                                                                     {
    std::stringstream out;
 
    std::vector<const App *> subcommands = app->get_subcommands({});
 
    // Make a list in definition order of the groups seen
    std::vector<std::string> subcmd_groups_seen;
    for(const App *com : subcommands) {
        if(com->get_name().empty()) {
            if(!com->get_group().empty()) {
                out << make_expanded(com);
            }
            continue;
        }
        std::string group_key = com->get_group();
        if(!group_key.empty() &&
           std::find_if(subcmd_groups_seen.begin(), subcmd_groups_seen.end(), [&group_key](std::string a) {
               return detail::to_lower(a) == detail::to_lower(group_key);
           }) == subcmd_groups_seen.end())
            subcmd_groups_seen.push_back(group_key);
    }
 
    // For each group, filter out and print subcommands
    for(const std::string &group : subcmd_groups_seen) {
        out << "\n" << group << ":\n";
        std::vector<const App *> subcommands_group = app->get_subcommands(
            [&group](const App *sub_app) { return detail::to_lower(sub_app->get_group()) == detail::to_lower(group); });
        for(const App *new_com : subcommands_group) {
            if(new_com->get_name().empty())
                continue;
            if(mode != AppFormatMode::All) {
                out << make_subcommand(new_com);
            } else {
                out << new_com->help(new_com->get_name(), AppFormatMode::Sub);
                out << "\n";
            }
        }
    }
 
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

make_usage()

std::string CLI::Formatter::make_usage ( const App * app, std::string name ) const

inlinevirtual

Definition at line 8031 of file CLI11.hpp.

                                                                           {
    std::stringstream out;
 
    out << get_label("Usage") << ":" << (name.empty() ? "" : " ") << name;
 
    std::vector<std::string> groups = app->get_groups();
 
    // Print an Options badge if any options exist
    std::vector<const Option *> non_pos_options =
        app->get_options([](const Option *opt) { return opt->nonpositional(); });
    if(!non_pos_options.empty())
        out << " [" << get_label("OPTIONS") << "]";
 
    // Positionals need to be listed here
    std::vector<const Option *> positionals = app->get_options([](const Option *opt) { return opt->get_positional(); });
 
    // Print out positionals if any are left
    if(!positionals.empty()) {
        // Convert to help names
        std::vector<std::string> positional_names(positionals.size());
        std::transform(positionals.begin(), positionals.end(), positional_names.begin(), [this](const Option *opt) {
            return make_option_usage(opt);
        });
 
        out << " " << detail::join(positional_names, " ");
    }
 
    // Add a marker if subcommands are expected or optional
    if(!app->get_subcommands(
               [](const CLI::App *subc) { return ((!subc->get_disabled()) && (!subc->get_name().empty())); })
            .empty()) {
        out << " " << (app->get_require_subcommand_min() == 0 ? "[" : "")
            << get_label(app->get_require_subcommand_max() < 2 || app->get_require_subcommand_min() > 1 ? "SUBCOMMAND"
                                                                                                        : "SUBCOMMANDS")
            << (app->get_require_subcommand_min() == 0 ? "]" : "");
    }
 
    out << std::endl;
 
    return out.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

---

The documentation for this class was generated from the following file:

• programs/clio/CLI11.hpp