CLI11  1.9.0
Formatter.hpp
Go to the documentation of this file.
1 #pragma once
2 
3 // Distributed under the 3-Clause BSD License. See accompanying
4 // file LICENSE or https://github.com/CLIUtils/CLI11 for details.
5 
6 #include <string>
7 
8 #include "CLI/App.hpp"
9 #include "CLI/FormatterFwd.hpp"
10 
11 namespace CLI {
12 
13 inline std::string
14 Formatter::make_group(std::string group, bool is_positional, std::vector<const Option *> opts) const {
15  std::stringstream out;
16 
17  out << "\n" << group << ":\n";
18  for(const Option *opt : opts) {
19  out << make_option(opt, is_positional);
20  }
21 
22  return out.str();
23 }
24 
25 inline std::string Formatter::make_positionals(const App *app) const {
26  std::vector<const Option *> opts =
27  app->get_options([](const Option *opt) { return !opt->get_group().empty() && opt->get_positional(); });
28 
29  if(opts.empty())
30  return std::string();
31 
32  return make_group(get_label("Positionals"), true, opts);
33 }
34 
35 inline std::string Formatter::make_groups(const App *app, AppFormatMode mode) const {
36  std::stringstream out;
37  std::vector<std::string> groups = app->get_groups();
38 
39  // Options
40  for(const std::string &group : groups) {
41  std::vector<const Option *> opts = app->get_options([app, mode, &group](const Option *opt) {
42  return opt->get_group() == group // Must be in the right group
43  && opt->nonpositional() // Must not be a positional
44  && (mode != AppFormatMode::Sub // If mode is Sub, then
45  || (app->get_help_ptr() != opt // Ignore help pointer
46  && app->get_help_all_ptr() != opt)); // Ignore help all pointer
47  });
48  if(!group.empty() && !opts.empty()) {
49  out << make_group(group, false, opts);
50 
51  if(group != groups.back())
52  out << "\n";
53  }
54  }
55 
56  return out.str();
57 }
58 
59 inline std::string Formatter::make_description(const App *app) const {
60  std::string desc = app->get_description();
61  auto min_options = app->get_require_option_min();
62  auto max_options = app->get_require_option_max();
63  if(app->get_required()) {
64  desc += " REQUIRED ";
65  }
66  if((max_options == min_options) && (min_options > 0)) {
67  if(min_options == 1) {
68  desc += " \n[Exactly 1 of the following options is required]";
69  } else {
70  desc += " \n[Exactly " + std::to_string(min_options) + "options from the following list are required]";
71  }
72  } else if(max_options > 0) {
73  if(min_options > 0) {
74  desc += " \n[Between " + std::to_string(min_options) + " and " + std::to_string(max_options) +
75  " of the follow options are required]";
76  } else {
77  desc += " \n[At most " + std::to_string(max_options) + " of the following options are allowed]";
78  }
79  } else if(min_options > 0) {
80  desc += " \n[At least " + std::to_string(min_options) + " of the following options are required]";
81  }
82  return (!desc.empty()) ? desc + "\n" : std::string{};
83 }
84 
85 inline std::string Formatter::make_usage(const App *app, std::string name) const {
86  std::stringstream out;
87 
88  out << get_label("Usage") << ":" << (name.empty() ? "" : " ") << name;
89 
90  std::vector<std::string> groups = app->get_groups();
91 
92  // Print an Options badge if any options exist
93  std::vector<const Option *> non_pos_options =
94  app->get_options([](const Option *opt) { return opt->nonpositional(); });
95  if(!non_pos_options.empty())
96  out << " [" << get_label("OPTIONS") << "]";
97 
98  // Positionals need to be listed here
99  std::vector<const Option *> positionals = app->get_options([](const Option *opt) { return opt->get_positional(); });
100 
101  // Print out positionals if any are left
102  if(!positionals.empty()) {
103  // Convert to help names
104  std::vector<std::string> positional_names(positionals.size());
105  std::transform(positionals.begin(), positionals.end(), positional_names.begin(), [this](const Option *opt) {
106  return make_option_usage(opt);
107  });
108 
109  out << " " << detail::join(positional_names, " ");
110  }
111 
112  // Add a marker if subcommands are expected or optional
113  if(!app->get_subcommands(
114  [](const CLI::App *subc) { return ((!subc->get_disabled()) && (!subc->get_name().empty())); })
115  .empty()) {
116  out << " " << (app->get_require_subcommand_min() == 0 ? "[" : "")
117  << get_label(app->get_require_subcommand_max() < 2 || app->get_require_subcommand_min() > 1 ? "SUBCOMMAND"
118  : "SUBCOMMANDS")
119  << (app->get_require_subcommand_min() == 0 ? "]" : "");
120  }
121 
122  out << std::endl;
123 
124  return out.str();
125 }
126 
127 inline std::string Formatter::make_footer(const App *app) const {
128  std::string footer = app->get_footer();
129  if(footer.empty()) {
130  return std::string{};
131  }
132  return footer + "\n";
133 }
134 
135 inline std::string Formatter::make_help(const App *app, std::string name, AppFormatMode mode) const {
136 
137  // This immediately forwards to the make_expanded method. This is done this way so that subcommands can
138  // have overridden formatters
139  if(mode == AppFormatMode::Sub)
140  return make_expanded(app);
141 
142  std::stringstream out;
143  if((app->get_name().empty()) && (app->get_parent() != nullptr)) {
144  if(app->get_group() != "Subcommands") {
145  out << app->get_group() << ':';
146  }
147  }
148 
149  out << make_description(app);
150  out << make_usage(app, name);
151  out << make_positionals(app);
152  out << make_groups(app, mode);
153  out << make_subcommands(app, mode);
154  out << '\n' << make_footer(app);
155 
156  return out.str();
157 }
158 
159 inline std::string Formatter::make_subcommands(const App *app, AppFormatMode mode) const {
160  std::stringstream out;
161 
162  std::vector<const App *> subcommands = app->get_subcommands({});
163 
164  // Make a list in definition order of the groups seen
165  std::vector<std::string> subcmd_groups_seen;
166  for(const App *com : subcommands) {
167  if(com->get_name().empty()) {
168  if(!com->get_group().empty()) {
169  out << make_expanded(com);
170  }
171  continue;
172  }
173  std::string group_key = com->get_group();
174  if(!group_key.empty() &&
175  std::find_if(subcmd_groups_seen.begin(), subcmd_groups_seen.end(), [&group_key](std::string a) {
176  return detail::to_lower(a) == detail::to_lower(group_key);
177  }) == subcmd_groups_seen.end())
178  subcmd_groups_seen.push_back(group_key);
179  }
180 
181  // For each group, filter out and print subcommands
182  for(const std::string &group : subcmd_groups_seen) {
183  out << "\n" << group << ":\n";
184  std::vector<const App *> subcommands_group = app->get_subcommands(
185  [&group](const App *sub_app) { return detail::to_lower(sub_app->get_group()) == detail::to_lower(group); });
186  for(const App *new_com : subcommands_group) {
187  if(new_com->get_name().empty())
188  continue;
189  if(mode != AppFormatMode::All) {
190  out << make_subcommand(new_com);
191  } else {
192  out << new_com->help(new_com->get_name(), AppFormatMode::Sub);
193  out << "\n";
194  }
195  }
196  }
197 
198  return out.str();
199 }
200 
201 inline std::string Formatter::make_subcommand(const App *sub) const {
202  std::stringstream out;
204  return out.str();
205 }
206 
207 inline std::string Formatter::make_expanded(const App *sub) const {
208  std::stringstream out;
209  out << sub->get_display_name() << "\n";
210 
211  out << make_description(sub);
212  out << make_positionals(sub);
213  out << make_groups(sub, AppFormatMode::Sub);
215 
216  // Drop blank spaces
217  std::string tmp = detail::find_and_replace(out.str(), "\n\n", "\n");
218  tmp = tmp.substr(0, tmp.size() - 1); // Remove the final '\n'
219 
220  // Indent all but the first line (the name)
221  return detail::find_and_replace(tmp, "\n", "\n ") + "\n";
222 }
223 
224 inline std::string Formatter::make_option_name(const Option *opt, bool is_positional) const {
225  if(is_positional)
226  return opt->get_name(true, false);
227 
228  return opt->get_name(false, true);
229 }
230 
231 inline std::string Formatter::make_option_opts(const Option *opt) const {
232  std::stringstream out;
233 
234  if(opt->get_type_size() != 0) {
235  if(!opt->get_type_name().empty())
236  out << " " << get_label(opt->get_type_name());
237  if(!opt->get_default_str().empty())
238  out << "=" << opt->get_default_str();
240  out << " ...";
241  else if(opt->get_expected_min() > 1)
242  out << " x " << opt->get_expected();
243 
244  if(opt->get_required())
245  out << " " << get_label("REQUIRED");
246  }
247  if(!opt->get_envname().empty())
248  out << " (" << get_label("Env") << ":" << opt->get_envname() << ")";
249  if(!opt->get_needs().empty()) {
250  out << " " << get_label("Needs") << ":";
251  for(const Option *op : opt->get_needs())
252  out << " " << op->get_name();
253  }
254  if(!opt->get_excludes().empty()) {
255  out << " " << get_label("Excludes") << ":";
256  for(const Option *op : opt->get_excludes())
257  out << " " << op->get_name();
258  }
259  return out.str();
260 }
261 
262 inline std::string Formatter::make_option_desc(const Option *opt) const { return opt->get_description(); }
263 
264 inline std::string Formatter::make_option_usage(const Option *opt) const {
265  // Note that these are positionals usages
266  std::stringstream out;
267  out << make_option_name(opt, true);
269  out << "...";
270  else if(opt->get_expected_max() > 1)
271  out << "(" << opt->get_expected() << "x)";
272 
273  return opt->get_required() ? out.str() : "[" + out.str() + "]";
274 }
275 
276 } // namespace CLI
CLI::detail::find_and_replace
std::string find_and_replace(std::string str, std::string from, std::string to)
Find and replace a substring with another substring.
Definition: StringTools.hpp:210
FormatterFwd.hpp
CLI::Option::get_envname
std::string get_envname() const
The environment variable associated to this value.
Definition: Option.hpp:659
CLI::Option::get_default_str
std::string get_default_str() const
The default value (for help printing)
Definition: Option.hpp:668
CLI::OptionBase::get_required
bool get_required() const
True if this is a required option.
Definition: Option.hpp:115
CLI::Formatter::make_usage
virtual std::string make_usage(const App *app, std::string name) const
This displays the usage line.
Definition: Formatter.hpp:85
CLI::detail::expected_max_vector_size
constexpr int expected_max_vector_size
Definition: StringTools.hpp:36
CLI::Option::get_needs
std::set< Option * > get_needs() const
The set of options needed.
Definition: Option.hpp:662
CLI::App::get_help_ptr
Option * get_help_ptr()
Get a pointer to the help flag.
Definition: App.hpp:1690
CLI::FormatterBase::get_label
std::string get_label(std::string key) const
Get the current value of a name (REQUIRED, etc.)
Definition: FormatterFwd.hpp:74
CLI::App::get_options
std::vector< const Option * > get_options(const std::function< bool(const Option *)> filter={}) const
Get the list of options (user facing function, so returns raw pointers), has optional filter function...
Definition: App.hpp:1533
CLI::App::get_name
const std::string & get_name() const
Get the name of the current app.
Definition: App.hpp:1711
CLI::App::get_display_name
std::string get_display_name() const
Get a display name for an app.
Definition: App.hpp:1723
CLI::App::get_group
const std::string & get_group() const
Get the group of this subcommand.
Definition: App.hpp:1646
CLI::Formatter::make_option_usage
virtual std::string make_option_usage(const Option *opt) const
This is used to print the name on the USAGE line.
Definition: Formatter.hpp:264
CLI::Option::get_positional
bool get_positional() const
True if the argument can be given directly.
Definition: Option.hpp:702
CLI::FormatterBase::column_width_
std::size_t column_width_
The width of the first column.
Definition: FormatterFwd.hpp:38
CLI::Option::get_name
std::string get_name(bool positional=false, bool all_options=false) const
Gets a comma separated list of names. Will include / prefer the positional name if positional is true...
Definition: Option.hpp:727
CLI::Option::get_expected_max
int get_expected_max() const
The max number of times the option expects to be included.
Definition: Option.hpp:688
CLI::detail::join
std::string join(const T &v, std::string delim=",")
Simple function to join a string.
Definition: StringTools.hpp:56
CLI::detail::to_string
auto to_string(T &&value) -> decltype(std::forward< T >(value))
Convert an object to a string (directly forward if this can become a string)
Definition: TypeTools.hpp:222
CLI::Formatter::make_help
std::string make_help(const App *, std::string, AppFormatMode) const override
This puts everything together.
Definition: Formatter.hpp:135
CLI::App::get_required
bool get_required() const
Get the status of required.
Definition: App.hpp:1670
CLI
Definition: App.hpp:27
CLI::App::get_help_all_ptr
const Option * get_help_all_ptr() const
Get a pointer to the help all flag. (const)
Definition: App.hpp:1696
CLI::App::get_require_subcommand_min
std::size_t get_require_subcommand_min() const
Get the required min subcommand value.
Definition: App.hpp:1652
CLI::Option::nonpositional
bool nonpositional() const
True if option has at least one non-positional name.
Definition: Option.hpp:705
CLI::Formatter::make_option_desc
virtual std::string make_option_desc(const Option *) const
This is the description. Default: Right column, on new line if left column too large.
Definition: Formatter.hpp:262
CLI::AppFormatMode::Sub
@ Sub
CLI::Formatter::make_group
virtual std::string make_group(std::string group, bool is_positional, std::vector< const Option * > opts) const
Definition: Formatter.hpp:14
CLI::Formatter::make_option
virtual std::string make_option(const Option *opt, bool is_positional) const
This prints out an option help line, either positional or optional form.
Definition: FormatterFwd.hpp:154
CLI::Formatter::make_positionals
virtual std::string make_positionals(const App *app) const
This prints out just the positionals "group".
Definition: Formatter.hpp:25
CLI::App::get_groups
std::vector< std::string > get_groups() const
Get the groups available directly from this option (in order)
Definition: App.hpp:1755
CLI::Formatter::make_subcommands
virtual std::string make_subcommands(const App *app, AppFormatMode mode) const
This prints out all the subcommands.
Definition: Formatter.hpp:159
CLI::Formatter::make_expanded
virtual std::string make_expanded(const App *sub) const
This prints out a subcommand in help-all.
Definition: Formatter.hpp:207
CLI::Formatter::make_option_name
virtual std::string make_option_name(const Option *, bool) const
This is the name part of an option, Default: left column.
Definition: Formatter.hpp:224
CLI::Formatter::make_footer
virtual std::string make_footer(const App *app) const
This prints out all the groups of options.
Definition: Formatter.hpp:127
CLI::App::get_require_subcommand_max
std::size_t get_require_subcommand_max() const
Get the required max subcommand value.
Definition: App.hpp:1655
CLI::App::get_description
std::string get_description() const
Get the app or subcommand description.
Definition: App.hpp:1524
CLI::App::get_require_option_min
std::size_t get_require_option_min() const
Get the required min option value.
Definition: App.hpp:1658
CLI::Formatter::make_subcommand
virtual std::string make_subcommand(const App *sub) const
This prints out a subcommand.
Definition: Formatter.hpp:201
CLI::detail::format_help
std::ostream & format_help(std::ostream &out, std::string name, std::string description, std::size_t wid)
Print a two part "help" string.
Definition: StringTools.hpp:155
CLI::Option
Definition: Option.hpp:228
CLI::App::get_footer
std::string get_footer() const
Generate and return the footer.
Definition: App.hpp:1649
CLI::App::get_require_option_max
std::size_t get_require_option_max() const
Get the required max option value.
Definition: App.hpp:1661
CLI::detail::to_lower
std::string to_lower(std::string str)
Return a lower case version of a string.
Definition: StringTools.hpp:196
App.hpp
CLI::AppFormatMode
AppFormatMode
Definition: FormatterFwd.hpp:22
CLI::Option::get_description
const std::string & get_description() const
Get the description.
Definition: Option.hpp:711
CLI::App::get_subcommands
std::vector< App * > get_subcommands() const
Definition: App.hpp:1340
CLI::Formatter::make_description
virtual std::string make_description(const App *app) const
This displays the description line.
Definition: Formatter.hpp:59
CLI::App
Creates a command line program, with very few defaults.
Definition: App.hpp:61
CLI::Option::get_type_size
int get_type_size() const
The number of arguments the option expects.
Definition: Option.hpp:651
CLI::AppFormatMode::All
@ All
CLI::Formatter::make_option_opts
virtual std::string make_option_opts(const Option *) const
This is the options part of the name, Default: combined into left column.
Definition: Formatter.hpp:231
CLI::OptionBase::get_group
const std::string & get_group() const
Get the group of this option.
Definition: Option.hpp:112
CLI::Formatter::make_groups
std::string make_groups(const App *app, AppFormatMode mode) const
This prints out all the groups of options.
Definition: Formatter.hpp:35
CLI::Option::get_type_name
std::string get_type_name() const
Get the full typename for this option.
Definition: Option.hpp:1108
CLI::Option::get_expected
int get_expected() const
The number of times the option expects to be included.
Definition: Option.hpp:683
CLI::Option::get_excludes
std::set< Option * > get_excludes() const
The set of options excluded.
Definition: Option.hpp:665
CLI::Option::get_expected_min
int get_expected_min() const
The number of times the option expects to be included.
Definition: Option.hpp:686
CLI::App::get_parent
App * get_parent()
Get the parent of this subcommand (or nullptr if master app)
Definition: App.hpp:1705