The format that prints the help page to std::cout. More...
#include <seqan3/argument_parser/detail/format_help.hpp>
Classes | |
struct | console_layout_struct |
Stores the relevant parameters of the documentation on the screen. More... | |
Public Member Functions | |
void | add_flag (bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec) |
Adds a seqan3::print_list_item call to be evaluated later on. More... | |
void | add_line (std::string const &text, bool is_paragraph, option_spec const spec) |
Adds a print_line call to parser_set_up_calls. More... | |
void | add_list_item (std::string const &key, std::string const &desc, option_spec const spec) |
Adds a seqan3::print_list_item call to parser_set_up_calls. More... | |
void | add_option (option_type &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec, validator_type &&option_validator) |
Adds a seqan3::print_list_item call to be evaluated later on. More... | |
void | add_positional_option (option_type &value, std::string const &desc, validator_type &option_validator) |
Adds a seqan3::print_list_item call to be evaluated later on. More... | |
void | add_section (std::string const &title, option_spec const spec) |
Adds a print_section call to parser_set_up_calls. More... | |
void | add_subsection (std::string const &title, option_spec const spec) |
Adds a print_subsection call to parser_set_up_calls. More... | |
void | parse (argument_parser_meta_data &parser_meta) |
Initiates the printing of the help page to std::cout. More... | |
Constructors, destructor and assignment | |
format_help ()=default | |
Defaulted. | |
format_help (format_help const &pf)=default | |
Defaulted. | |
format_help & | operator= (format_help const &)=default |
Defaulted. | |
format_help (format_help &&)=default | |
Defaulted. | |
format_help & | operator= (format_help &&)=default |
Defaulted. | |
~format_help ()=default | |
Defaulted. | |
format_help (std::vector< std::string > const &names, bool const advanced=false) | |
Initializes a format_help_base object. More... | |
Public Attributes | |
friend | derived_type |
Befriend the derived type so it can access private functions. | |
argument_parser_meta_data | meta |
Stores all meta information about the application. More... | |
Protected Member Functions | |
format_help & | derived_t () |
Returns the derived type. | |
std::string | escape_special_xml_chars (std::string const &original) |
Escapes certain characters for correct output. More... | |
void | print_legal () |
Prints the legal information. | |
void | print_line (std::string const &text) |
Delegates to seqan3::print_line(std::string const & text, true) of each format. More... | |
void | print_synopsis () |
Prints a synopsis in any format. | |
void | print_version () |
Prints the version information. | |
Static Protected Member Functions | |
static std::string | expand_multiple_flags (std::string const &flag_cluster) |
Expands multiple one character flag identifiers for pretty help output. More... | |
template<sequence_container container_type> | |
static std::string | get_type_name_as_string (container_type const &) |
Returns the value_type of the input container as a string (reflection). More... | |
template<typename value_type > | |
static std::string | get_type_name_as_string (value_type const &) |
Returns the input type as a string (reflection). More... | |
template<typename container_type > | |
static std::string | option_type_and_list_info (container_type const &container) |
Formats the container and its value_type for the help page printing. More... | |
template<typename option_value_type > | |
static std::string | option_type_and_list_info (option_value_type const &value) |
Formats the type of a value for the help page printing. More... | |
static std::string | prep_id_for_help (char const short_id, std::string const &long_id) |
Formats the option/flag identifier pair for the help page printing. More... | |
Protected Attributes | |
std::vector< std::string > | command_names |
The names of subcommand programs. | |
std::vector< std::function< void()> > | parser_set_up_calls |
Vector of functions that stores all calls except add_positional_option. | |
std::vector< std::function< void()> > | positional_option_calls |
Vector of functions that stores add_positional_option calls. | |
unsigned | positional_option_count |
Keeps track of the number of positional options. | |
bool | show_advanced_options |
Whether to show advanced options or not. | |
Private Types | |
using | base_type = format_help_base< format_help > |
The CRTP base class type. | |
Private Member Functions | |
std::string | in_bold (std::string const &str) |
Format string in bold. More... | |
void | print_footer () |
Prints a help page footer to std::cout. | |
void | print_header () |
Prints a help page header to std::cout. | |
void | print_line (std::string const &text, bool const line_is_paragraph) |
Prints a text to std::cout. More... | |
void | print_list_item (std::string const &term, std::string const &desc) |
Prints a help page list_item to std::cout. More... | |
void | print_section (std::string const &title) |
Prints a help page section to std::cout. More... | |
void | print_subsection (std::string const &title) |
Prints a help page subsection to std::cout. More... | |
void | print_text (std::string const &text, unsigned const tab) |
Prints text with correct line wrapping to the command line (std::cout). More... | |
void | store_help_page_element (std::function< void()> printer, option_spec const spec) |
Adds a function object to parser_set_up_calls if the annotation in spec does not prevent it. More... | |
unsigned | text_width (std::string const &text) |
Returns width of text if printed. More... | |
std::string | to_text (std::string const &str) |
Formats text for pretty command line printing. More... | |
Private Attributes | |
friend | base_type |
Befriend the base class to give access to the private member functions. | |
console_layout_struct | layout {} |
Stores the relevant parameters of the documentation on the screen. | |
bool | prev_was_paragraph {false} |
Needed for correct formatting while calling different print functions. | |
Friends | |
struct | ::seqan3::detail::test_accessor |
Befriend seqan3::detail::test_accessor to grant access to layout. | |
The format that prints the help page to std::cout.
The help page printing is not done immediately, because the user might not provide meta information, positional options, etc. in the correct order. In addition the needed order would be different from the parse format. Thus the calls are stored (parser_set_up_calls and positional_option_calls) and only evaluated when calling format_help::parse().
|
inline |
Initializes a format_help_base object.
[in] | names | A list of subcommands (see subcommand parsing ). |
[in] | advanced | Set to true to show advanced options. |
|
inlineinherited |
Adds a seqan3::print_list_item call to be evaluated later on.
[in,out] | value | The variable in which to store the given command line argument. |
[in] | short_id | The short identifier for the flag (e.g. 'i'). |
[in] | long_id | The long identifier for the flag (e.g. "integer"). |
[in] | desc | The description of the flag to be shown in the help page. |
[in] | spec | Advanced flag specification, see seqan3::option_spec. |
|
inlineinherited |
Adds a print_line call to parser_set_up_calls.
[in] | text | The text to print. |
[in] | is_paragraph | Whether to insert as paragraph or just a line (Default: false). |
[in] | spec | Whether to always display this line (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden). |
If the line is not a paragraph (false), only one line break is appended, otherwise two line breaks are appended. This only affects the help page and other output formats.
|
inlineinherited |
Adds a seqan3::print_list_item call to parser_set_up_calls.
[in] | key | The key of the key-value pair of the list item. |
[in] | desc | The value of the key-value pair of the list item. |
[in] | spec | Whether to always display this list item (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden). |
Note: This only affects the help page and other output formats.
A list item is composed of a key (key
) and value (desc
) and usually used for option identifier-description-pairs. E.g.:
|
inlineinherited |
Adds a seqan3::print_list_item call to be evaluated later on.
option_type | Must have a formatted input function (stream >> value). If option_type is a container, its value type must have the formatted input function (exception: std::string is not regarded as a container). See FormattedInputFunction . |
validator_type | The type of validator to be applied to the option value. Must model seqan3::validator. |
[in,out] | value | The variable in which to store the given command line argument. |
[in] | short_id | The short identifier for the option (e.g. 'a'). |
[in] | long_id | The long identifier for the option (e.g. "age"). |
[in] | desc | The description of the option to be shown in the help page. |
[in] | spec | Advanced option specification, see seqan3::option_spec. |
[in] | option_validator | A seqan3::validator that verifies the value after parsing (callable). |
seqan3::design_error |
|
inlineinherited |
Adds a seqan3::print_list_item call to be evaluated later on.
option_type | Must have a formatted input function (stream >> value). If option_type is a container, its value type must have the formatted input function (exception: std::string is not regarded as a container). See FormattedInputFunction . |
validator_type | The type of validator to be applied to the option value. Must model seqan3::validator. |
[in,out] | value | The variable in which to store the given command line argument. |
[in] | desc | The description of the positional option to be shown in the help page. |
[in] | option_validator | A seqan3::validator that verifies the value after parsing (callable). |
seqan3::design_error |
The validator must be applicable to the given output variable (value
).
|
inlineinherited |
Adds a print_section call to parser_set_up_calls.
[in] | title | The title of the section. |
[in] | spec | Whether to always display this section title (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden). |
This only affects the help page and other output formats.
|
inlineinherited |
Adds a print_subsection call to parser_set_up_calls.
[in] | title | The title of the subsection. |
[in] | spec | Whether to always display this subsection title (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden). |
This only affects the help page and other output formats.
|
inlineprotectedinherited |
Escapes certain characters for correct output.
[in] | original | The string containing characters to be escaped. |
Special characters considered are "
, \
, &
, <
and >
.
|
inlinestaticprotectedinherited |
Expands multiple one character flag identifiers for pretty help output.
[in] | flag_cluster | The string of one character flags. |
e.g. "-agdg" becomes "-a, -g, -d and -g".
|
inlinestaticprotectedinherited |
Returns the value_type
of the input container as a string (reflection).
container_type | The container type for which to query it's value_type. |
|
inlinestaticprotectedinherited |
Returns the input type as a string (reflection).
value_type | The type whose name is converted std::string. |
|
inlineprivate |
Format string in bold.
[in] | str | The input string to format in bold. |
str
wrapped in bold formatting.
|
inlinestaticprotectedinherited |
Formats the container and its value_type for the help page printing.
container_type | A type that must satisfy the seqan3::sequence_container. |
[in] | container | The container to deduct the type from. |
|
inlinestaticprotectedinherited |
Formats the type of a value for the help page printing.
option_value_type | The type of the option value to get the info for. |
[in] | value | The value to deduct the type from. |
|
inlineinherited |
Initiates the printing of the help page to std::cout.
[in] | parser_meta | The meta information that are needed for a detailed help page. |
|
inlinestaticprotectedinherited |
Formats the option/flag identifier pair for the help page printing.
[in] | short_id | The short identifier of the option/flag. |
[in] | long_id | The long identifier of the option/flag. |
e.g. "-i,--integer", "-i", or "--integer".
|
inlineprotectedinherited |
Delegates to seqan3::print_line(std::string const & text, true) of each format.
[in] | text | The text to print. |
|
inlineprivate |
Prints a text to std::cout.
[in] | text | The text to print. |
[in] | line_is_paragraph | Whether to insert as paragraph or just a line (only one line break if not a paragraph). |
|
inlineprivate |
Prints a help page list_item to std::cout.
[in] | term | The key of the key-value pair of the list item. |
[in] | desc | The value of the key-value pair of the list item. |
A list item is composed of a key (term) and value (desc) and usually used for option identifier-description-pairs. E.g.:
|
inlineprivate |
Prints a help page section to std::cout.
[in] | title | The title of the subsection of the help page. |
|
inlineprivate |
Prints a help page subsection to std::cout.
[in] | title | The title of the subsection of the help page. |
|
inlineprivate |
Prints text with correct line wrapping to the command line (std::cout).
[in] | text | The string to print on the command line. |
[in] | tab | The position offset (indentation) to start printing at. |
|
inlineprivateinherited |
Adds a function object to parser_set_up_calls if the annotation in spec
does not prevent it.
[in] | printer | The invokable that, if added to parser_set_up_calls , prints information to the help page. |
[in] | spec | The option specification deciding whether to add the information to the help page. |
If spec
equals seqan3::option_spec::hidden
, the information is never added to the help page. If spec
equals seqan3::option_spec::advanced
, the information is only added to the help page if the advanced help page has been queried on the command line (show_advanced_options == true
).
|
inlineprivate |
Returns width of text if printed.
[in] | text | The string to compute the width for on the command line. /detail Note: "\-" has length 1, "\fI", "\fB", "\fP" have length 0. |
|
inlineprivate |
Formats text for pretty command line printing.
[in] | str | The input string to format for correct command line printing. |
|
inherited |
Stores all meta information about the application.
This needs to be a member of format_parse, because it needs to present (not filled) when the parser_set_up_calls vector is filled, since all printing functions need some meta information. The member variable itself is filled when copied over from the argument_parser when calling format_parse::parse. That way all the information needed are there, when the actual printing starts.
This function is not private because it is needed for short but nicely formatted (error) output to the command line.