include/CLI/FormatterFwd.hpp

0001 // Copyright (c) 2017-2025, University of Cincinnati, developed by Henry Schreiner
0002 // under NSF AWARD 1414736 and by the respective contributors.
0003 // All rights reserved.
0004 //
0005 // SPDX-License-Identifier: BSD-3-Clause
0006
0007 #pragma once
0008
0009 // IWYU pragma: private, include "CLI/CLI.hpp"
0010
0011 // [CLI11:public_includes:set]
0012 #include <functional>
0013 #include <map>
0014 #include <string>
0015 #include <utility>
0016 #include <vector>
0017 // [CLI11:public_includes:end]
0018
0019 #include "StringTools.hpp"
0020
0021 namespace CLI {
0022 // [CLI11:formatter_fwd_hpp:verbatim]
0023
0024 class Option;
0025 class App;
0026
0027 /// This enum signifies the type of help requested
0028 ///
0029 /// This is passed in by App; all user classes must accept this as
0030 /// the second argument.
0031
0032 enum class AppFormatMode {
0033     Normal,  ///< The normal, detailed help
0034     All,     ///< A fully expanded help
0035     Sub,     ///< Used when printed as part of expanded subcommand
0036 };
0037
0038 /// This is the minimum requirements to run a formatter.
0039 ///
0040 /// A user can subclass this is if they do not care at all
0041 /// about the structure in CLI::Formatter.
0042 class FormatterBase {
0043   protected:
0044     /// @name Options
0045     ///@{
0046
0047     /// The width of the left column (options/flags/subcommands)
0048     std::size_t column_width_{30};
0049
0050     /// The width of the right column (description of options/flags/subcommands)
0051     std::size_t right_column_width_{65};
0052
0053     /// The width of the description paragraph at the top of help
0054     std::size_t description_paragraph_width_{80};
0055
0056     /// The width of the footer paragraph
0057     std::size_t footer_paragraph_width_{80};
0058
0059     /// @brief The required help printout labels (user changeable)
0060     /// Values are Needs, Excludes, etc.
0061     std::map<std::string, std::string> labels_{};
0062
0063     ///@}
0064     /// @name Basic
0065     ///@{
0066
0067   public:
0068     FormatterBase() = default;
0069     FormatterBase(const FormatterBase &) = default;
0070     FormatterBase(FormatterBase &&) = default;
0071     FormatterBase &operator=(const FormatterBase &) = default;
0072     FormatterBase &operator=(FormatterBase &&) = default;
0073
0074     /// Adding a destructor in this form to work around bug in GCC 4.7
0075     virtual ~FormatterBase() noexcept {}  // NOLINT(modernize-use-equals-default)
0076
0077     /// This is the key method that puts together help
0078     virtual std::string make_help(const App *, std::string, AppFormatMode) const = 0;
0079
0080     ///@}
0081     /// @name Setters
0082     ///@{
0083
0084     /// Set the "REQUIRED" label
0085     void label(std::string key, std::string val) { labels_[key] = val; }
0086
0087     /// Set the left column width (options/flags/subcommands)
0088     void column_width(std::size_t val) { column_width_ = val; }
0089
0090     /// Set the right column width (description of options/flags/subcommands)
0091     void right_column_width(std::size_t val) { right_column_width_ = val; }
0092
0093     /// Set the description paragraph width at the top of help
0094     void description_paragraph_width(std::size_t val) { description_paragraph_width_ = val; }
0095
0096     /// Set the footer paragraph width
0097     void footer_paragraph_width(std::size_t val) { footer_paragraph_width_ = val; }
0098
0099     ///@}
0100     /// @name Getters
0101     ///@{
0102
0103     /// Get the current value of a name (REQUIRED, etc.)
0104     CLI11_NODISCARD std::string get_label(std::string key) const {
0105         if(labels_.find(key) == labels_.end())
0106             return key;
0107         return labels_.at(key);
0108     }
0109
0110     /// Get the current left column width (options/flags/subcommands)
0111     CLI11_NODISCARD std::size_t get_column_width() const { return column_width_; }
0112
0113     /// Get the current right column width (description of options/flags/subcommands)
0114     CLI11_NODISCARD std::size_t get_right_column_width() const { return right_column_width_; }
0115
0116     /// Get the current description paragraph width at the top of help
0117     CLI11_NODISCARD std::size_t get_description_paragraph_width() const { return description_paragraph_width_; }
0118
0119     /// Get the current footer paragraph width
0120     CLI11_NODISCARD std::size_t get_footer_paragraph_width() const { return footer_paragraph_width_; }
0121
0122     ///@}
0123 };
0124
0125 /// This is a specialty override for lambda functions
0126 class FormatterLambda final : public FormatterBase {
0127     using funct_t = std::function<std::string(const App *, std::string, AppFormatMode)>;
0128
0129     /// The lambda to hold and run
0130     funct_t lambda_;
0131
0132   public:
0133     /// Create a FormatterLambda with a lambda function
0134     explicit FormatterLambda(funct_t funct) : lambda_(std::move(funct)) {}
0135
0136     /// Adding a destructor (mostly to make GCC 4.7 happy)
0137     ~FormatterLambda() noexcept override {}  // NOLINT(modernize-use-equals-default)
0138
0139     /// This will simply call the lambda function
0140     std::string make_help(const App *app, std::string name, AppFormatMode mode) const override {
0141         return lambda_(app, name, mode);
0142     }
0143 };
0144
0145 /// This is the default Formatter for CLI11. It pretty prints help output, and is broken into quite a few
0146 /// overridable methods, to be highly customizable with minimal effort.
0147 class Formatter : public FormatterBase {
0148   public:
0149     Formatter() = default;
0150     Formatter(const Formatter &) = default;
0151     Formatter(Formatter &&) = default;
0152     Formatter &operator=(const Formatter &) = default;
0153     Formatter &operator=(Formatter &&) = default;
0154
0155     /// @name Overridables
0156     ///@{
0157
0158     /// This prints out a group of options with title
0159     ///
0160     CLI11_NODISCARD virtual std::string
0161     make_group(std::string group, bool is_positional, std::vector<const Option *> opts) const;
0162
0163     /// This prints out just the positionals "group"
0164     virtual std::string make_positionals(const App *app) const;
0165
0166     /// This prints out all the groups of options
0167     std::string make_groups(const App *app, AppFormatMode mode) const;
0168
0169     /// This prints out all the subcommands
0170     virtual std::string make_subcommands(const App *app, AppFormatMode mode) const;
0171
0172     /// This prints out a subcommand
0173     virtual std::string make_subcommand(const App *sub) const;
0174
0175     /// This prints out a subcommand in help-all
0176     virtual std::string make_expanded(const App *sub, AppFormatMode mode) const;
0177
0178     /// This prints out all the groups of options
0179     virtual std::string make_footer(const App *app) const;
0180
0181     /// This displays the description line
0182     virtual std::string make_description(const App *app) const;
0183
0184     /// This displays the usage line
0185     virtual std::string make_usage(const App *app, std::string name) const;
0186
0187     /// This puts everything together
0188     std::string make_help(const App *app, std::string, AppFormatMode mode) const override;
0189
0190     ///@}
0191     /// @name Options
0192     ///@{
0193
0194     /// This prints out an option help line, either positional or optional form
0195     virtual std::string make_option(const Option *, bool) const;
0196
0197     /// @brief This is the name part of an option, Default: left column
0198     virtual std::string make_option_name(const Option *, bool) const;
0199
0200     /// @brief This is the options part of the name, Default: combined into left column
0201     virtual std::string make_option_opts(const Option *) const;
0202
0203     /// @brief This is the description. Default: Right column, on new line if left column too large
0204     virtual std::string make_option_desc(const Option *) const;
0205
0206     /// @brief This is used to print the name on the USAGE line
0207     virtual std::string make_option_usage(const Option *opt) const;
0208
0209     ///@}
0210 };
0211
0212 // [CLI11:formatter_fwd_hpp:end]
0213 }  // namespace CLI