CLI11  2.5.0
FormatterFwd.hpp
Go to the documentation of this file.
1 // Copyright (c) 2017-2025, 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 // IWYU pragma: private, include "CLI/CLI.hpp"
10 
11 // [CLI11:public_includes:set]
12 #include <functional>
13 #include <map>
14 #include <string>
15 #include <utility>
16 #include <vector>
17 // [CLI11:public_includes:end]
18 
19 #include "StringTools.hpp"
20 
21 namespace CLI {
22 // [CLI11:formatter_fwd_hpp:verbatim]
23 
24 class Option;
25 class App;
26 
31 
32 enum class AppFormatMode {
33  Normal,
34  All,
35  Sub,
36 };
37 
43  protected:
46 
48  std::size_t column_width_{30};
49 
51  std::size_t right_column_width_{65};
52 
55 
57  std::size_t footer_paragraph_width_{80};
58 
61  std::map<std::string, std::string> labels_{};
62 
66 
67  public:
68  FormatterBase() = default;
69  FormatterBase(const FormatterBase &) = default;
70  FormatterBase(FormatterBase &&) = default;
71  FormatterBase &operator=(const FormatterBase &) = default;
72  FormatterBase &operator=(FormatterBase &&) = default;
73 
75  virtual ~FormatterBase() noexcept {} // NOLINT(modernize-use-equals-default)
76 
78  virtual std::string make_help(const App *, std::string, AppFormatMode) const = 0;
79 
83 
85  void label(std::string key, std::string val) { labels_[key] = val; }
86 
88  void column_width(std::size_t val) { column_width_ = val; }
89 
91  void right_column_width(std::size_t val) { right_column_width_ = val; }
92 
95 
97  void footer_paragraph_width(std::size_t val) { footer_paragraph_width_ = val; }
98 
102 
104  CLI11_NODISCARD std::string get_label(std::string key) const {
105  if(labels_.find(key) == labels_.end())
106  return key;
107  return labels_.at(key);
108  }
109 
111  CLI11_NODISCARD std::size_t get_column_width() const { return column_width_; }
112 
115 
118 
121 
123 };
124 
126 class FormatterLambda final : public FormatterBase {
127  using funct_t = std::function<std::string(const App *, std::string, AppFormatMode)>;
128 
130  funct_t lambda_;
131 
132  public:
134  explicit FormatterLambda(funct_t funct) : lambda_(std::move(funct)) {}
135 
137  ~FormatterLambda() noexcept override {} // NOLINT(modernize-use-equals-default)
138 
140  std::string make_help(const App *app, std::string name, AppFormatMode mode) const override {
141  return lambda_(app, name, mode);
142  }
143 };
144 
147 class Formatter : public FormatterBase {
148  public:
149  Formatter() = default;
150  Formatter(const Formatter &) = default;
151  Formatter(Formatter &&) = default;
152  Formatter &operator=(const Formatter &) = default;
153  Formatter &operator=(Formatter &&) = default;
154 
157 
160  CLI11_NODISCARD virtual std::string
161  make_group(std::string group, bool is_positional, std::vector<const Option *> opts) const;
162 
164  virtual std::string make_positionals(const App *app) const;
165 
167  std::string make_groups(const App *app, AppFormatMode mode) const;
168 
170  virtual std::string make_subcommands(const App *app, AppFormatMode mode) const;
171 
173  virtual std::string make_subcommand(const App *sub) const;
174 
176  virtual std::string make_expanded(const App *sub, AppFormatMode mode) const;
177 
179  virtual std::string make_footer(const App *app) const;
180 
182  virtual std::string make_description(const App *app) const;
183 
185  virtual std::string make_usage(const App *app, std::string name) const;
186 
188  std::string make_help(const App *app, std::string, AppFormatMode mode) const override;
189 
193 
195  virtual std::string make_option(const Option *, bool) const;
196 
198  virtual std::string make_option_name(const Option *, bool) const;
199 
201  virtual std::string make_option_opts(const Option *) const;
202 
204  virtual std::string make_option_desc(const Option *) const;
205 
207  virtual std::string make_option_usage(const Option *opt) const;
208 
210 };
211 
212 // [CLI11:formatter_fwd_hpp:end]
213 } // namespace CLI
CLI11_NODISCARD std::size_t get_footer_paragraph_width() const
Get the current footer paragraph width.
Definition: FormatterFwd.hpp:120
virtual ~FormatterBase() noexcept
Adding a destructor in this form to work around bug in GCC 4.7.
Definition: FormatterFwd.hpp:75
virtual std::string make_expanded(const App *sub, AppFormatMode mode) const
This prints out a subcommand in help-all.
CLI11_NODISCARD std::size_t get_right_column_width() const
Get the current right column width (description of options/flags/subcommands)
Definition: FormatterFwd.hpp:114
~FormatterLambda() noexcept override
Adding a destructor (mostly to make GCC 4.7 happy)
Definition: FormatterFwd.hpp:137
virtual std::string make_positionals(const App *app) const
This prints out just the positionals "group".
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_subcommands(const App *app, AppFormatMode mode) const
This prints out all the subcommands.
Definition: App.hpp:36
std::string make_groups(const App *app, AppFormatMode mode) const
This prints out all the groups of options.
Formatter()=default
Formatter & operator=(const Formatter &)=default
FormatterBase & operator=(const FormatterBase &)=default
virtual std::string make_option_desc(const Option *) const
This is the description. Default: Right column, on new line if left column too large.
A fully expanded help.
virtual CLI11_NODISCARD std::string make_group(std::string group, bool is_positional, std::vector< const Option * > opts) const
CLI11_NODISCARD std::size_t get_description_paragraph_width() const
Get the current description paragraph width at the top of help.
Definition: FormatterFwd.hpp:117
Definition: Option.hpp:231
STL namespace.
void footer_paragraph_width(std::size_t val)
Set the footer paragraph width.
Definition: FormatterFwd.hpp:97
CLI11_NODISCARD std::size_t get_column_width() const
Get the current left column width (options/flags/subcommands)
Definition: FormatterFwd.hpp:111
std::map< std::string, std::string > labels_
The required help printout labels (user changeable) Values are Needs, Excludes, etc.
Definition: FormatterFwd.hpp:61
virtual std::string make_subcommand(const App *sub) const
This prints out a subcommand.
void right_column_width(std::size_t val)
Set the right column width (description of options/flags/subcommands)
Definition: FormatterFwd.hpp:91
void column_width(std::size_t val)
Set the left column width (options/flags/subcommands)
Definition: FormatterFwd.hpp:88
virtual std::string make_help(const App *, std::string, AppFormatMode) const =0
This is the key method that puts together help.
std::size_t description_paragraph_width_
The width of the description paragraph at the top of help.
Definition: FormatterFwd.hpp:54
virtual std::string make_option_name(const Option *, bool) const
This is the name part of an option, Default: left column.
FormatterLambda(funct_t funct)
Create a FormatterLambda with a lambda function.
Definition: FormatterFwd.hpp:134
std::string make_help(const App *app, std::string, AppFormatMode mode) const override
This puts everything together.
std::size_t footer_paragraph_width_
The width of the footer paragraph.
Definition: FormatterFwd.hpp:57
FormatterBase()=default
AppFormatMode
Definition: FormatterFwd.hpp:32
void label(std::string key, std::string val)
Set the "REQUIRED" label.
Definition: FormatterFwd.hpp:85
Definition: FormatterFwd.hpp:42
CLI11_NODISCARD std::string get_label(std::string key) const
Get the current value of a name (REQUIRED, etc.)
Definition: FormatterFwd.hpp:104
The normal, detailed help.
virtual std::string make_footer(const App *app) const
This prints out all the groups of options.
std::size_t column_width_
The width of the left column (options/flags/subcommands)
Definition: FormatterFwd.hpp:48
This is a specialty override for lambda functions.
Definition: FormatterFwd.hpp:126
virtual std::string make_description(const App *app) const
This displays the description line.
void description_paragraph_width(std::size_t val)
Set the description paragraph width at the top of help.
Definition: FormatterFwd.hpp:94
#define CLI11_NODISCARD
Definition: Macros.hpp:58
virtual std::string make_option(const Option *, bool) const
This prints out an option help line, either positional or optional form.
virtual std::string make_option_usage(const Option *opt) const
This is used to print the name on the USAGE line.
Definition: FormatterFwd.hpp:147
std::string make_help(const App *app, std::string name, AppFormatMode mode) const override
This will simply call the lambda function.
Definition: FormatterFwd.hpp:140
Creates a command line program, with very few defaults.
Definition: App.hpp:90
std::size_t right_column_width_
The width of the right column (description of options/flags/subcommands)
Definition: FormatterFwd.hpp:51
Used when printed as part of expanded subcommand.
virtual std::string make_usage(const App *app, std::string name) const
This displays the usage line.