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