CLI::HelpFormatter Class Reference

#include <Formatter.h>

Inheritance diagram for CLI::HelpFormatter:

Collaboration diagram for CLI::HelpFormatter:

Public Member Functions
	HelpFormatter ()
	~HelpFormatter () override

Private Member Functions
std::string	make_group (std::string group, bool is_positional, std::vector< const Option * > opts) const override
std::string	make_description (const App *app) const override
std::string	make_usage (const App *app, std::string name) const override
std::string	make_footer (const App *app) const override
std::string	make_subcommands (const App *app, AppFormatMode mode) const override
std::string	make_subcommand (const App *sub) const override
std::string	make_expanded (const App *sub, AppFormatMode mode) const override
std::string	make_option_opts (const Option *opt) const override

Detailed Description

Definition at line 88 of file Formatter.h.

Constructor & Destructor Documentation

HelpFormatter()

CLI::HelpFormatter::HelpFormatter ( )

inline

Definition at line 92 of file Formatter.h.

                        {
            label("SUBCOMMAND", "INSTANCE");
            label("SUBCOMMANDS", "INSTANCES");
            label("PERSISTENT", "");
            label("Persistent Options", "Options (persistent)");
            label("Nonpersistent Options", "Options (nonpersistent)");
            label("Usage", "\nUsage");
            label("bool:{true,false}", "{true,false}");
            label(":{true,false)", "{true,false}");
            label(":{standard,active,complete,required}", "{standard,active,complete,required}");
            label(":{standard,exact,expanded}", "{standard,exact,expanded}");
            column_width(7);
        }

~HelpFormatter()

CLI::HelpFormatter::~HelpFormatter ( )

override

Definition at line 193 of file Formatter.cpp.

                                  {
    }

Member Function Documentation

make_description()

CLI11_INLINE std::string CLI::HelpFormatter::make_description ( const App * app ) const

overrideprivate

Definition at line 208 of file Formatter.cpp.

                                                                               {
        std::string desc = app->get_description();
        auto min_options = app->get_require_option_min();
        auto max_options = app->get_require_option_max();
        // ############## Next line changed (if statement removed)
        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{};
    }

Referenced by make_expanded().

Here is the caller graph for this function:

make_expanded()

CLI11_INLINE std::string CLI::HelpFormatter::make_expanded ( const App * sub, AppFormatMode mode ) const

overrideprivate

Definition at line 398 of file Formatter.cpp.

                                                                                                {
        std::stringstream out;
        // ########## Next lines changed
        const Option* disabledOpt = sub->get_option_no_throw("--disabled");
        out << sub->get_display_name(true) + " [OPTIONS]" + (!sub->get_subcommands({}).empty() ? " [SECTIONS]" : "") +
                   ((disabledOpt != nullptr ? disabledOpt->as<bool>() : false) ? " " + get_label("DISABLED")
                                                                               : (sub->get_required() ? " " + get_label("REQUIRED") : ""))
            << "\n";
 
        detail::streamOutAsParagraph(out, make_description(sub), description_paragraph_width_, ""); // Format description as paragraph
 
        if (sub->get_name().empty() && !sub->get_aliases().empty()) {
            detail::format_aliases(out, sub->get_aliases(), column_width_ + 2);
        }
        out << make_positionals(sub);
        out << make_groups(sub, mode);
        out << make_subcommands(sub, mode);
 
        // Drop blank spaces
        std::string tmp = out.str();
        tmp.pop_back();
 
        // Indent all but the first line (the name)
        return detail::find_and_replace(tmp, "\n", "\n  ") + "\n";
    }

References make_description(), and make_subcommands().

Referenced by make_subcommands().

Here is the call graph for this function:

Here is the caller graph for this function:

make_footer()

CLI11_INLINE std::string CLI::HelpFormatter::make_footer ( const App * app ) const

overrideprivate

Definition at line 294 of file Formatter.cpp.

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

make_group()

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

overrideprivate

Definition at line 196 of file Formatter.cpp.

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

make_option_opts()

CLI11_INLINE std::string CLI::HelpFormatter::make_option_opts ( const Option * opt ) const

overrideprivate

Definition at line 424 of file Formatter.cpp.

                                                                                  {
        std::stringstream out;
 
        if (!opt->get_option_text().empty()) {
            out << " " << opt->get_option_text();
        } else {
            if (opt->get_type_size() != 0) {
                if (!opt->get_type_name().empty()) {
                    // ########## Next line changed
                    out << ((opt->get_items_expected_max() == 0) ? "=" : " ") << get_label(opt->get_type_name());
                }
                if (!opt->get_default_str().empty()) {
                    out << " [" << opt->get_default_str() << "]";
                }
                try {
                    if (opt->count() > 0 && opt->get_default_str() != opt->as<std::string>()) {
                        out << " {";
                        std::string completeResult;
                        for (const auto& result : opt->reduced_results()) {
                            completeResult += (!result.empty() ? result : "\"\"") + " ";
                        }
                        completeResult.pop_back();
                        out << completeResult << "}";
                    }
                } catch (CLI::ParseError& e) {
                    out << " <[" << Color::Code::FG_RED << e.get_name() << Color::Code::FG_DEFAULT << "] " << e.what() << ">";
                }
                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() && !get_label("REQUIRED").empty()) {
                    out << " " << get_label("REQUIRED");
                }
                if (opt->get_configurable() && !get_label("PERSISTENT").empty()) {
                    out << " " << get_label("PERSISTENT");
                }
            }
            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();
    }

References Color::FG_DEFAULT, and Color::FG_RED.

make_subcommand()

CLI11_INLINE std::string CLI::HelpFormatter::make_subcommand ( const App * sub ) const

overrideprivate

Definition at line 378 of file Formatter.cpp.

                                                                              {
        std::stringstream out;
        const std::string name = "  " + sub->get_display_name(true) + (sub->get_required() ? " " + get_label("REQUIRED") : "");
 
        out << std::setw(static_cast<int>(column_width_)) << std::left << name;
        const std::string desc = sub->get_description();
        if (!desc.empty()) {
            bool skipFirstLinePrefix = true;
            if (out.str().length() >= column_width_) {
                out << '\n';
                skipFirstLinePrefix = false;
            }
            detail::streamOutAsParagraph(out, desc, right_column_width_, std::string(column_width_, ' '), skipFirstLinePrefix);
        }
 
        out << '\n';
 
        return out.str();
    }

Referenced by make_subcommands().

Here is the caller graph for this function:

make_subcommands()

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

overrideprivate

Definition at line 302 of file Formatter.cpp.

                                                                                                   {
        std::stringstream out;
 
        const std::vector<const App*> subcommands = app->get_subcommands([](const App* subc) {
            if (subc->get_group() == "Instances") {
                if (subc->get_option("--disabled")->as<bool>()) {
                    const_cast<CLI::App*>(subc)->group(subc->get_group() + " (disabled)");
                }
            }
            return !subc->get_disabled() && !subc->get_name().empty();
        });
 
        // Make a list in alphabetic order of the groups seen
        std::set<std::string> subcmd_groups_seen;
        for (const App* com : subcommands) {
            if (com->get_name().empty()) {
                if (!com->get_group().empty()) {
                    out << make_expanded(com, mode);
                }
                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](const std::string& a) {
                    return detail::to_lower(a) == detail::to_lower(group_key);
                }) == subcmd_groups_seen.end()) {
                subcmd_groups_seen.insert(group_key);
            }
        }
 
        // For each group, filter out and print subcommands
        const Option* disabledOpt = app->get_option_no_throw("--disabled");
        bool disabled = false;
        if (disabledOpt != nullptr) {
            disabled = disabledOpt->as<bool>();
        }
 
        if (!disabled) {
            for (const std::string& group : subcmd_groups_seen) {
                out << "\n" << group << ":\n";
                const 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) && !sub_app->get_disabled() &&
                           !sub_app->get_name().empty();
                });
                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(disabledOpt != nullptr && (app->get_help_ptr()->as<std::string>() == "exact" ||
                                                                        app->get_help_ptr()->as<std::string>() == "expanded")
                                                 ? new_com
                                                 : nullptr,
                                             new_com->get_name(),
                                             AppFormatMode::Sub);
                        out << "\n";
                    }
                }
            }
        }
 
        // ########## Next line(s) changed
 
        std::string tmp = out.str();
        if (mode == AppFormatMode::All && !tmp.empty()) {
            tmp.pop_back();
        }
 
        out.str(tmp);
        out.clear();
 
        return out.str();
    }

References make_expanded(), and make_subcommand().

Referenced by make_expanded().

Here is the call graph for this function:

Here is the caller graph for this function:

make_usage()

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

overrideprivate

Definition at line 232 of file Formatter.cpp.

                                                                                         {
        const std::string usage = app->get_usage();
        if (!usage.empty()) {
            return usage + "\n";
        }
 
        std::stringstream out;
 
        out << get_label("Usage") << ":" << (name.empty() ? "" : " ") << name;
 
        // Print an Options badge if any options exist
        const 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 App* subc) {
                    return !subc->get_disabled() && !subc->get_name().empty();
                })
                 .empty()) {
            // ############## Next line changed
            out << " ["
                << get_label(app->get_subcommands([](const CLI::App* subc) {
                                    return ((!subc->get_disabled()) && (!subc->get_name().empty()) /*&& subc->get_required()*/);
                                }).size() <= 1
                                 ? "SUBCOMMAND"
                                 : "SUBCOMMANDS")
                << " [--help]"
                << "]";
        }
 
        const Option* disabledOpt = app->get_option_no_throw("--disabled");
        if (disabledOpt != nullptr ? disabledOpt->as<bool>() : false) {
            out << " " << get_label("DISABLED");
        } else if (app->get_required()) {
            out << " " << get_label("REQUIRED");
        }
 
        out << std::endl;
 
        return out.str();
    }

---

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

• utils/Formatter.h
• utils/Formatter.cpp