Loading...
Searching...
No Matches
FormatterFwd.hpp
Go to the documentation of this file.
// Copyright (c) 2017-2025, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause
#pragma once
// IWYU pragma: private, include "CLI/CLI.hpp"
// [CLI11:public_includes:set]
#include <functional>
#include <map>
#include <string>
#include <utility>
#include <vector>
// [CLI11:public_includes:end]
#include "StringTools.hpp"
namespace CLI {
// [CLI11:formatter_fwd_hpp:verbatim]
class Option;
class App;
enum class AppFormatMode : std::uint8_t {
Normal,
All,
Sub,
};
class FormatterBase {
protected:
std::size_t column_width_{30};
float long_option_alignment_ratio_{1 / 3.f};
std::size_t right_column_width_{65};
std::size_t description_paragraph_width_{80};
std::size_t footer_paragraph_width_{80};
bool enable_description_formatting_{true};
bool enable_footer_formatting_{true};
std::map<std::string, std::string> labels_{};
public:
FormatterBase() = default;
FormatterBase(const FormatterBase &) = default;
FormatterBase(FormatterBase &&) = default;
FormatterBase &operator=(const FormatterBase &) = default;
FormatterBase &operator=(FormatterBase &&) = default;
virtual ~FormatterBase() noexcept {} // NOLINT(modernize-use-equals-default)
virtual std::string make_help(const App *, std::string, AppFormatMode) const = 0;
void label(std::string key, std::string val) { labels_[key] = val; }
void column_width(std::size_t val) { column_width_ = val; }
void long_option_alignment_ratio(float ratio) { long_option_alignment_ratio_ = ratio; }
void right_column_width(std::size_t val) { right_column_width_ = val; }
void description_paragraph_width(std::size_t val) { description_paragraph_width_ = val; }
void footer_paragraph_width(std::size_t val) { footer_paragraph_width_ = val; }
void enable_description_formatting(bool value = true) { enable_description_formatting_ = value; }
void enable_footer_formatting(bool value = true) { enable_footer_formatting_ = value; }
CLI11_NODISCARD std::string get_label(std::string key) const {
if(labels_.find(key) == labels_.end())
return key;
return labels_.at(key);
}
CLI11_NODISCARD std::size_t get_column_width() const { return column_width_; }
CLI11_NODISCARD std::size_t get_right_column_width() const { return right_column_width_; }
CLI11_NODISCARD std::size_t get_description_paragraph_width() const { return description_paragraph_width_; }
CLI11_NODISCARD std::size_t get_footer_paragraph_width() const { return footer_paragraph_width_; }
CLI11_NODISCARD bool is_description_paragraph_formatting_enabled() const { return enable_description_formatting_; }
CLI11_NODISCARD bool is_footer_paragraph_formatting_enabled() const { return enable_footer_formatting_; }
};
class FormatterLambda final : public FormatterBase {
using funct_t = std::function<std::string(const App *, std::string, AppFormatMode)>;
funct_t lambda_;
public:
explicit FormatterLambda(funct_t funct) : lambda_(std::move(funct)) {}
~FormatterLambda() noexcept override {} // NOLINT(modernize-use-equals-default)
std::string make_help(const App *app, std::string name, AppFormatMode mode) const override {
return lambda_(app, name, mode);
}
};
class Formatter : public FormatterBase {
public:
Formatter() = default;
Formatter(const Formatter &) = default;
Formatter(Formatter &&) = default;
Formatter &operator=(const Formatter &) = default;
Formatter &operator=(Formatter &&) = default;
CLI11_NODISCARD virtual std::string
make_group(std::string group, bool is_positional, std::vector<const Option *> opts) const;
virtual std::string make_positionals(const App *app) const;
std::string make_groups(const App *app, AppFormatMode mode) const;
virtual std::string make_subcommands(const App *app, AppFormatMode mode) const;
virtual std::string make_subcommand(const App *sub) const;
virtual std::string make_expanded(const App *sub, AppFormatMode mode) const;
virtual std::string make_footer(const App *app) const;
virtual std::string make_description(const App *app) const;
virtual std::string make_usage(const App *app, std::string name) const;
std::string make_help(const App *app, std::string, AppFormatMode mode) const override;
virtual std::string make_option(const Option *, bool) const;
virtual std::string make_option_name(const Option *, bool) const;
virtual std::string make_option_opts(const Option *) const;
virtual std::string make_option_desc(const Option *) const;
virtual std::string make_option_usage(const Option *opt) const;
};
// [CLI11:formatter_fwd_hpp:end]
} // namespace CLI
CLI11_NODISCARD
#define CLI11_NODISCARD
Definition Macros.hpp:58
StringTools.hpp
CLI::App
Creates a command line program, with very few defaults.
Definition App.hpp:98
CLI::FormatterBase::footer_paragraph_width
void footer_paragraph_width(std::size_t val)
Set the footer paragraph width.
Definition FormatterFwd.hpp:108
CLI::FormatterBase::column_width_
std::size_t column_width_
The width of the left column (options/flags/subcommands).
Definition FormatterFwd.hpp:48
CLI::FormatterBase::right_column_width
void right_column_width(std::size_t val)
Set the right column width (description of options/flags/subcommands).
Definition FormatterFwd.hpp:102
CLI::FormatterBase::labels_
std::map< std::string, std::string > labels_
The required help printout labels (user changeable) Values are Needs, Excludes, etc.
Definition FormatterFwd.hpp:68
CLI::FormatterBase::footer_paragraph_width_
std::size_t footer_paragraph_width_
The width of the footer paragraph.
Definition FormatterFwd.hpp:60
CLI::FormatterBase::get_column_width
CLI11_NODISCARD std::size_t get_column_width() const
Get the current left column width (options/flags/subcommands).
Definition FormatterFwd.hpp:125
CLI::FormatterBase::get_footer_paragraph_width
CLI11_NODISCARD std::size_t get_footer_paragraph_width() const
Get the current footer paragraph width.
Definition FormatterFwd.hpp:134
CLI::FormatterBase::long_option_alignment_ratio
void long_option_alignment_ratio(float ratio)
Definition FormatterFwd.hpp:99
CLI::FormatterBase::get_label
CLI11_NODISCARD std::string get_label(std::string key) const
Get the current value of a name (REQUIRED, etc.).
Definition FormatterFwd.hpp:118
CLI::FormatterBase::FormatterBase
FormatterBase(FormatterBase &&)=default
CLI::FormatterBase::get_description_paragraph_width
CLI11_NODISCARD std::size_t get_description_paragraph_width() const
Get the current description paragraph width at the top of help.
Definition FormatterFwd.hpp:131
CLI::FormatterBase::operator=
FormatterBase & operator=(FormatterBase &&)=default
CLI::FormatterBase::enable_description_formatting
void enable_description_formatting(bool value=true)
enable formatting for description paragraph
Definition FormatterFwd.hpp:110
CLI::FormatterBase::label
void label(std::string key, std::string val)
Set the "REQUIRED" or other labels.
Definition FormatterFwd.hpp:92
CLI::FormatterBase::operator=
FormatterBase & operator=(const FormatterBase &)=default
CLI::FormatterBase::enable_description_formatting_
bool enable_description_formatting_
options controlling formatting for footer and descriptions
Definition FormatterFwd.hpp:63
CLI::FormatterBase::FormatterBase
FormatterBase()=default
CLI::FormatterBase::enable_footer_formatting
void enable_footer_formatting(bool value=true)
disable formatting for footer paragraph
Definition FormatterFwd.hpp:112
CLI::FormatterBase::enable_footer_formatting_
bool enable_footer_formatting_
Definition FormatterFwd.hpp:64
CLI::FormatterBase::is_description_paragraph_formatting_enabled
CLI11_NODISCARD bool is_description_paragraph_formatting_enabled() const
Get the current status of description paragraph formatting.
Definition FormatterFwd.hpp:137
CLI::FormatterBase::FormatterBase
FormatterBase(const FormatterBase &)=default
CLI::FormatterBase::get_right_column_width
CLI11_NODISCARD std::size_t get_right_column_width() const
Get the current right column width (description of options/flags/subcommands).
Definition FormatterFwd.hpp:128
CLI::FormatterBase::~FormatterBase
virtual ~FormatterBase() noexcept
Adding a destructor in this form to work around bug in GCC 4.7.
Definition FormatterFwd.hpp:82
CLI::FormatterBase::make_help
virtual std::string make_help(const App *, std::string, AppFormatMode) const =0
This is the key method that puts together help.
CLI::FormatterBase::column_width
void column_width(std::size_t val)
Set the left column width (options/flags/subcommands).
Definition FormatterFwd.hpp:95
CLI::FormatterBase::right_column_width_
std::size_t right_column_width_
The width of the right column (description of options/flags/subcommands).
Definition FormatterFwd.hpp:54
CLI::FormatterBase::long_option_alignment_ratio_
float long_option_alignment_ratio_
The alignment ratio for long options within the left column.
Definition FormatterFwd.hpp:51
CLI::FormatterBase::description_paragraph_width_
std::size_t description_paragraph_width_
The width of the description paragraph at the top of help.
Definition FormatterFwd.hpp:57
CLI::FormatterBase::is_footer_paragraph_formatting_enabled
CLI11_NODISCARD bool is_footer_paragraph_formatting_enabled() const
Get the current status of whether footer paragraph formatting is enabled.
Definition FormatterFwd.hpp:140
CLI::FormatterBase::description_paragraph_width
void description_paragraph_width(std::size_t val)
Set the description paragraph width at the top of help.
Definition FormatterFwd.hpp:105
CLI::FormatterLambda::make_help
std::string make_help(const App *app, std::string name, AppFormatMode mode) const override
This will simply call the lambda function.
Definition FormatterFwd.hpp:160
CLI::FormatterLambda::~FormatterLambda
~FormatterLambda() noexcept override
Adding a destructor (mostly to make GCC 4.7 happy).
Definition FormatterFwd.hpp:157
CLI::FormatterLambda::FormatterLambda
FormatterLambda(funct_t funct)
Create a FormatterLambda with a lambda function.
Definition FormatterFwd.hpp:154
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.
CLI::Formatter::Formatter
Formatter(Formatter &&)=default
CLI::Formatter::make_positionals
virtual std::string make_positionals(const App *app) const
This prints out just the positionals "group".
CLI::Formatter::make_help
std::string make_help(const App *app, std::string, AppFormatMode mode) const override
This puts everything together.
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.
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.
CLI::Formatter::Formatter
Formatter(const Formatter &)=default
CLI::Formatter::make_subcommands
virtual std::string make_subcommands(const App *app, AppFormatMode mode) const
This prints out all the subcommands.
CLI::Formatter::make_description
virtual std::string make_description(const App *app) const
This displays the description line.
CLI::Formatter::make_subcommand
virtual std::string make_subcommand(const App *sub) const
This prints out a subcommand.
CLI::Formatter::make_expanded
virtual std::string make_expanded(const App *sub, AppFormatMode mode) const
This prints out a subcommand in help-all.
CLI::Formatter::Formatter
Formatter()=default
CLI::Formatter::operator=
Formatter & operator=(Formatter &&)=default
CLI::Formatter::make_footer
virtual std::string make_footer(const App *app) const
This prints out all the groups of options.
CLI::Formatter::operator=
Formatter & operator=(const Formatter &)=default
CLI::Formatter::make_option
virtual std::string make_option(const Option *, bool) const
This prints out an option help line, either positional or optional form.
CLI::Formatter::make_groups
std::string make_groups(const App *app, AppFormatMode mode) const
This prints out all the groups of options.
CLI::Formatter::make_group
virtual CLI11_NODISCARD std::string make_group(std::string group, bool is_positional, std::vector< const Option * > opts) const
CLI::Formatter::make_usage
virtual std::string make_usage(const App *app, std::string name) const
This displays the usage line.
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.
CLI::Option
Definition Option.hpp:259
CLI
Definition App.hpp:36
CLI::AppFormatMode
AppFormatMode
Definition FormatterFwd.hpp:32
CLI::AppFormatMode::Normal
@ Normal
The normal, detailed help.
Definition FormatterFwd.hpp:33
CLI::AppFormatMode::All
@ All
A fully expanded help.
Definition FormatterFwd.hpp:34
CLI::AppFormatMode::Sub
@ Sub
Used when printed as part of expanded subcommand.
Definition FormatterFwd.hpp:35