The format that prints the help page as html to std::cout. More...

#include <seqan3/argument_parser/detail/format_html.hpp>

Inheritance diagram for seqan3::detail::format_html:

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_html ()=default
	Defaulted.

	format_html (format_html const &pf)=default
	Defaulted.

format_html &	operator= (format_html const &pf)=default
	Defaulted.

	format_html (format_html &&)=default
	Defaulted.

format_html &	operator= (format_html &&)=default
	Defaulted.

	~format_html ()=default
	Defaulted.

	format_html (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_html &	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_html >
	The CRTP base class type.

Private Member Functions
std::string	in_bold (std::string const &str)
	Format string as in_bold. More...

void	maybe_close_list ()
	Closes HTML list tag (dl) if needed.

void	maybe_close_paragraph ()
	Closes HTML paragraph tag (p) if needed.

void	print_footer ()
	Prints a help page footer in HTML format to std::cout.

void	print_header ()
	Prints a help page header in HTML format to std::cout.

void	print_line (std::string const &text, bool line_is_paragraph)
	Prints a text in HTML format to std::cout. More...

void	print_list_item (std::string const &term, std::string const &desc)
	Prints a help page list_item in HTML format to std::cout. More...

void	print_section (std::string const &title)
	Prints a section title in HTML format to std::cout. More...

void	print_subsection (std::string const &title)
	Prints a subsection title in HTML format to 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...

std::string	to_html (std::string const &input)
	Converts console output formatting to the HTML equivalent. More...

Private Attributes
friend	base_type
	Befriend the base class to give access to the private member functions.

bool	is_dl {false}
	Current state is either inside a html <dl> tag (true) or not (false).

bool	is_p {false}
	Current state is either inside a html <p> tag (true) or not (false).

Detailed Description

The format that prints the help page as html 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().

Constructor & Destructor Documentation

◆ format_html()

seqan3::detail::format_html::format_html	(	std::vector< std::string > const &	names,
		bool const	advanced = `false`
	)

inline

Initializes a format_help_base object.

Parameters

[in]	names	A list of subcommands (see subcommand parsing ).
[in]	advanced	Set to `true` to show advanced options.

Member Function Documentation

◆ add_flag()

void seqan3::detail::format_help_base< format_html >::add_flag	(	bool &	value,
		char const	short_id,
		std::string const &	long_id,
		std::string const &	desc,
		option_spec const	spec
	)

inlineinherited

Adds a seqan3::print_list_item call to be evaluated later on.

Parameters

[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.

◆ add_line()

void seqan3::detail::format_help_base< format_html >::add_line	(	std::string const &	text,
		bool	is_paragraph,
		option_spec const	spec
	)

inlineinherited

Adds a print_line call to parser_set_up_calls.

Parameters

[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.

◆ add_list_item()

void seqan3::detail::format_help_base< format_html >::add_list_item	(	std::string const &	key,
		std::string const &	desc,
		option_spec const	spec
	)

inlineinherited

Adds a seqan3::print_list_item call to parser_set_up_calls.

Parameters

[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.:

-a, --age LONG

Super important integer for age.

◆ add_option()

void seqan3::detail::format_help_base< format_html >::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
	)

inlineinherited

Adds a seqan3::print_list_item call to be evaluated later on.

Template Parameters

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.

Parameters

[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).

Exceptions

seqan3::design_error

◆ add_positional_option()

void seqan3::detail::format_help_base< format_html >::add_positional_option	(	option_type &	value,
		std::string const &	desc,
		validator_type &	option_validator
	)

inlineinherited

Adds a seqan3::print_list_item call to be evaluated later on.

Template Parameters

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.

Parameters

[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).

Exceptions

seqan3::design_error

The validator must be applicable to the given output variable (value).

◆ add_section()

void seqan3::detail::format_help_base< format_html >::add_section	(	std::string const &	title,
		option_spec const	spec
	)

inlineinherited

Adds a print_section call to parser_set_up_calls.

Parameters

[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.

◆ add_subsection()

void seqan3::detail::format_help_base< format_html >::add_subsection	(	std::string const &	title,
		option_spec const	spec
	)

inlineinherited

Adds a print_subsection call to parser_set_up_calls.

Parameters

[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.

◆ escape_special_xml_chars()

std::string seqan3::detail::format_base::escape_special_xml_chars ( std::string const & original )

inlineprotectedinherited

Escapes certain characters for correct output.

Parameters

[in] original The string containing characters to be escaped.

Returns: The original string as their corresponding html/xml representation.

Special characters considered are ", \, &, < and >.

◆ expand_multiple_flags()

static std::string seqan3::detail::format_base::expand_multiple_flags ( std::string const & flag_cluster )

inlinestaticprotectedinherited

Expands multiple one character flag identifiers for pretty help output.

Parameters

[in] flag_cluster The string of one character flags.

Returns: A string that lists all flags as a comma separated list.

e.g. "-agdg" becomes "-a, -g, -d and -g".

◆ get_type_name_as_string() [1/2]

template<sequence_container container_type>

static std::string seqan3::detail::format_base::get_type_name_as_string ( container_type const & )

inlinestaticprotectedinherited

Returns the value_type of the input container as a string (reflection).

Template Parameters

container_type The container type for which to query it's value_type.

Returns: The type of the container value_type as a string.

◆ get_type_name_as_string() [2/2]

template<typename value_type >

static std::string seqan3::detail::format_base::get_type_name_as_string ( value_type const & )

inlinestaticprotectedinherited

Returns the input type as a string (reflection).

Template Parameters

value_type The type whose name is converted std::string.

Returns: The type of the value as a string.

◆ in_bold()

std::string seqan3::detail::format_html::in_bold ( std::string const & str )

inlineprivate

Format string as in_bold.

Parameters

[in] str The input string to format in bold.

Returns: The string str wrapped in bold formatting.

◆ option_type_and_list_info() [1/2]

template<typename container_type >

static std::string seqan3::detail::format_base::option_type_and_list_info ( container_type const & container )

inlinestaticprotectedinherited

Formats the container and its value_type for the help page printing.

Template Parameters

container_type A type that must satisfy the seqan3::sequence_container.

Parameters

[in] container The container to deduct the type from.

Returns: The type of the container value type as a string, encapsulated in "List of".

◆ option_type_and_list_info() [2/2]

template<typename option_value_type >

static std::string seqan3::detail::format_base::option_type_and_list_info ( option_value_type const & value )

inlinestaticprotectedinherited

Formats the type of a value for the help page printing.

Template Parameters

option_value_type The type of the option value to get the info for.

Parameters

[in] value The value to deduct the type from.

Returns: The type of the value as string.

◆ parse()

void seqan3::detail::format_help_base< format_html >::parse ( argument_parser_meta_data & parser_meta )

inlineinherited

Initiates the printing of the help page to std::cout.

Parameters

[in] parser_meta The meta information that are needed for a detailed help page.

◆ prep_id_for_help()

static std::string seqan3::detail::format_base::prep_id_for_help	(	char const	short_id,
		std::string const &	long_id
	)

inlinestaticprotectedinherited

Formats the option/flag identifier pair for the help page printing.

Parameters

[in]	short_id	The short identifier of the option/flag.
[in]	long_id	The long identifier of the option/flag.

Returns: The name of the short and long id, prepended with (double)dash.

e.g. "-i,--integer", "-i", or "--integer".

◆ print_line() [1/2]

void seqan3::detail::format_help_base< format_html >::print_line ( std::string const & text )

inlineprotectedinherited

Delegates to seqan3::print_line(std::string const & text, true) of each format.

Parameters

[in] text The text to print.

◆ print_line() [2/2]

void seqan3::detail::format_html::print_line	(	std::string const &	text,
		bool	line_is_paragraph
	)

inlineprivate

Prints a text in HTML format to std::cout.

Parameters

[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).

◆ print_list_item()

void seqan3::detail::format_html::print_list_item	(	std::string const &	term,
		std::string const &	desc
	)

inlineprivate

Prints a help page list_item in HTML format to std::cout.

Parameters

[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.

◆ print_section()

void seqan3::detail::format_html::print_section ( std::string const & title )

inlineprivate

Prints a section title in HTML format to std::cout.

Parameters

[in] title The title of the section of the help page.

◆ print_subsection()

void seqan3::detail::format_html::print_subsection ( std::string const & title )

inlineprivate

Prints a subsection title in HTML format to std::cout.

Parameters

[in] title The title of the subsection of the help page.

◆ store_help_page_element()

void seqan3::detail::format_help_base< format_html >::store_help_page_element	(	std::function< void()>	printer,
		option_spec const	spec
	)

inlineprivateinherited

Adds a function object to parser_set_up_calls if the annotation in spec does not prevent it.

Parameters

[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).

◆ to_html()

std::string seqan3::detail::format_html::to_html ( std::string const & input )

inlineprivate

Converts console output formatting to the HTML equivalent.

Parameters

[in] input The text to transform.

Member Data Documentation

◆ meta

argument_parser_meta_data seqan3::detail::format_help_base< format_html >::meta

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.

The documentation for this class was generated from the following file:

seqan3/argument_parser/detail/format_html.hpp

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Types

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ format_html()

Member Function Documentation

◆ add_flag()

◆ add_line()

◆ add_list_item()

◆ add_option()

◆ add_positional_option()

◆ add_section()

◆ add_subsection()

◆ escape_special_xml_chars()

◆ expand_multiple_flags()

◆ get_type_name_as_string() [1/2]

◆ get_type_name_as_string() [2/2]

◆ in_bold()

◆ option_type_and_list_info() [1/2]

◆ option_type_and_list_info() [2/2]

◆ parse()

◆ prep_id_for_help()

◆ print_line() [1/2]

◆ print_line() [2/2]

◆ print_list_item()

◆ print_section()

◆ print_subsection()

◆ store_help_page_element()

◆ to_html()

Member Data Documentation

◆ meta