external/CLI/FormatterFwd.hpp

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