The format that contains all helper functions needed in all formats for printing the interface description of the application (to std::cout). More...

#include <sharg/detail/format_base.hpp>

Inheritance diagram for sharg::detail::format_help_base< derived_type >:

Classes
struct	synopsis_element
	Structure to store synopsis element information. More...

Public Member Functions
template<typename option_type , typename validator_t >
void	add_option (option_type &value, config< validator_t > const &config)
	Adds a sharg::print_list_item call to be evaluated later on.

template<typename validator_t >
void	add_flag (bool &value, config< validator_t > const &config)
	Adds a sharg::print_list_item call to be evaluated later on.

template<typename option_type , typename validator_t >
void	add_positional_option (option_type &value, config< validator_t > const &config)
	Adds a sharg::print_list_item call to be evaluated later on.

void	parse (parser_meta_data &parser_meta, std::vector< std::string > const &executable_name)
	Initiates the printing of the help page to std::cout.

void	add_section (std::string const &title, bool const advanced_only)
	Adds a print_section call to parser_set_up_calls.

void	add_subsection (std::string const &title, bool const advanced_only)
	Adds a print_subsection call to parser_set_up_calls.

void	add_line (std::string const &text, bool is_paragraph, bool const advanced_only)
	Adds a print_line call to parser_set_up_calls.

void	add_list_item (std::string const &key, std::string const &desc, bool const advanced_only)
	Adds a sharg::print_list_item call to parser_set_up_calls.

Public Attributes
parser_meta_data	meta
	Stores all meta information about the application.

friend	derived_type
	Befriend the derived type so it can access private functions.

Protected Member Functions
derived_type &	derived_t ()
	Returns the derived type.

void	print_synopsis ()
	Prints a synopsis in any format.

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

void	print_version ()
	Prints the version information.

void	print_legal ()
	Prints the legal information.

void	generate_default_synopsis (std::vector< std::string > executable_name)
	Generates default synopsis from stored elements.

Protected Attributes
update_notifications	version_check_dev_decision {}
	Set on construction and indicates whether the developer deactivated the version check calls completely.

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 {0}
	Keeps track of the number of positional options.

std::vector< std::string >	command_names {}
	The names of subcommand programs.

bool	show_advanced_options {true}
	Whether to show advanced options or not.

std::vector< synopsis_element >	synopsis_elements {}
	Stores elements for automatic synopsis generation.

Private Member Functions
void	store_help_page_element (std::function< void()> printer, bool const advanced, bool const hidden)
	Adds a function object to parser_set_up_calls if the annotation in `config` does not prevent it.

void	store_synopsis_option (detail::id_pair const &id, std::string const &type_str, bool const required, bool const is_list)
	Stores option information for synopsis generation.

void	store_synopsis_flag (detail::id_pair const &id)
	Stores flag information for synopsis generation.

void	store_synopsis_positional (std::string const &type_str, bool const is_list)
	Stores positional argument information for synopsis generation.

template<typename validator_t >
void	store_help_page_element (std::function< void()> printer, config< validator_t > const &config)
	Adds a function object to parser_set_up_calls if the annotation in `config` does not prevent it.

Constructors, destructor and assignment
	format_help_base ()=default
	Defaulted.

	format_help_base (format_help_base const &pf)=default
	Defaulted.

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

	format_help_base (format_help_base &&)=default
	Defaulted.

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

	~format_help_base ()=default
	Defaulted.

	format_help_base (std::vector< std::string > const &names, update_notifications const version_updates, bool const advanced)
	Initializes a format_help_base object.

Additional Inherited Members
Static Protected Member Functions inherited from sharg::detail::format_base
template<typename value_type , bool verbose = true>
static std::string	get_type_name_as_string ()
	Returns the input type as a string (reflection).

template<detail::is_container_option container_type, bool verbose = true>
static std::string	get_type_name_as_string ()
	Returns the `value_type` of the input container as a string (reflection).

template<typename option_value_type >
static std::string	option_type_and_list_info (option_value_type const &)
	Formats the type of a value for the help page printing.

template<detail::is_container_option container_type>
static std::string	option_type_and_list_info (container_type const &)
	Formats the container and its value_type for the help page printing.

static std::string	prep_id_for_help (detail::id_pair const &id, bool const is_synopsis=false)
	Formats the option/flag identifier pair for the help page printing.

static std::string	escape_special_xml_chars (std::string const &original)
	Escapes certain characters for correct output.

static std::string	expand_multiple_flags (std::string const &flag_cluster)
	Expands multiple one character flag identifiers for pretty help output.

template<typename option_type , typename default_type >
static std::string	get_default_message (option_type const &option, default_type const &value)
	Returns the default message for the help page.

static void	print_as_lowercase (std::string const &str)
	Prints a string to std::cout converted to lowercase.

static void	print_as_uppercase (std::string const &str)
	Prints a string to std::cout converted to uppercase.

Detailed Description

template<typename derived_type>
class sharg::detail::format_help_base< derived_type >

The format that contains all helper functions needed in all formats for printing the interface description of the application (to std::cout).

Remarks: For a complete overview, take a look at Parser

Constructor & Destructor Documentation

◆ format_help_base()

template<typename derived_type >

sharg::detail::format_help_base< derived_type >::format_help_base	(	std::vector< std::string > const &	names,
		update_notifications const	version_updates,
		bool const	advanced )

inlineprivate

Initializes a format_help_base object.

Parameters

[in]	names	A list of subcommands (see subcommand parsing ).
[in]	version_updates	Whether the developer disabled version checks when constructing the parser.
[in]	advanced	Set to `true` to show advanced options.

Member Function Documentation

◆ add_flag()

template<typename derived_type >

template<typename validator_t >

void sharg::detail::format_help_base< derived_type >::add_flag	(	bool &	value,
		config< validator_t > const &	config )

inline

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

Parameters

[in,out]	value	The variable which shows if the flag is turned off (default) or on.
[in]	config	A configuration object to customise the sharg::parser behaviour. See sharg::config.

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if `value` is true.
sharg::design_error	if the option identifier was already used.
sharg::design_error	if the option identifier is not a valid identifier.

This entity is stable. Since version 1.0.

◆ add_line()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::add_line	(	std::string const &	text,
		bool	is_paragraph,
		bool const	advanced_only )

inline

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]	advanced_only	If set to true, the section only shows when the user requested the advanced help page.

Exceptions

sharg::design_error if sharg::parser::parse was already called.

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.

This entity is stable. Since version 1.0.

◆ add_list_item()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::add_list_item	(	std::string const &	key,
		std::string const &	desc,
		bool const	advanced_only )

inline

Adds a sharg::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]	advanced_only	If set to true, the section only shows when the user requested the advanced help page.

Exceptions

sharg::design_error if sharg::parser::parse was already called.

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.

This entity is stable. Since version 1.0.

◆ add_option()

template<typename derived_type >

template<typename option_type , typename validator_t >

void sharg::detail::format_help_base< derived_type >::add_option	(	option_type &	value,
		config< validator_t > const &	config )

inline

Adds a sharg::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 sharg::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	config	A configuration object to customise the sharg::parser behaviour. See sharg::config.

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

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if the option is required and has a default_message.
sharg::design_error	if the option identifier was already used.
sharg::design_error	if the option identifier is not a valid identifier.

This entity is stable. Since version 1.0.

◆ add_positional_option()

template<typename derived_type >

template<typename option_type , typename validator_t >

void sharg::detail::format_help_base< derived_type >::add_positional_option	(	option_type &	value,
		config< validator_t > const &	config )

inline

Adds a sharg::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 sharg::validator.

Parameters

[in,out]	value	The variable in which to store the given command line argument.
[in]	config	Customise the sharg::parser behaviour. See sharg::positional_config.

Exceptions

sharg::design_error	if sharg::parser::parse was already called.
sharg::design_error	if the option has a short or long identifier.
sharg::design_error	if the option is advanced or hidden.
sharg::design_error	if the option has a default_message.
sharg::design_error	if there already is a positional list option.
sharg::design_error	if there are subcommands.

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

This entity is stable. Since version 1.0.

◆ add_section()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::add_section	(	std::string const &	title,
		bool const	advanced_only )

inline

Adds a print_section call to parser_set_up_calls.

Parameters

[in]	title	The title of the section.
[in]	advanced_only	If set to true, the section only shows when the user requested the advanced help page.

Exceptions

sharg::design_error if sharg::parser::parse was already called.

This only affects the help page and other output formats.

This entity is stable. Since version 1.0.

◆ add_subsection()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::add_subsection	(	std::string const &	title,
		bool const	advanced_only )

inline

Adds a print_subsection call to parser_set_up_calls.

Parameters

[in]	title	The title of the subsection.
[in]	advanced_only	If set to true, the section only shows when the user requested the advanced help page.

Exceptions

sharg::design_error if sharg::parser::parse was already called.

This only affects the help page and other output formats.

This entity is stable. Since version 1.0.

◆ parse()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::parse	(	parser_meta_data &	parser_meta,
		std::vector< std::string > const &	executable_name )

inline

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.
[in]	executable_name	A list of arguments that form together the call to the executable. For example: [raptor, build]

◆ print_line()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::print_line ( std::string const & text )

inlineprotected

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

Parameters

[in] text The text to print.

◆ store_help_page_element() [1/2]

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::store_help_page_element	(	std::function< void()>	printer,
		bool const	advanced,
		bool const	hidden )

inlineprivate

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

Parameters

[in]	printer	The invokable that, if added to `parser_set_up_calls`, prints information to the help page.
[in]	advanced	Whether the help page element was configured to be hidden.
[in]	hidden	Whether the help page element was configured to be hidden.

If hidden = true, the information is never added to the help page. If advanced = true, 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).

◆ store_help_page_element() [2/2]

template<typename derived_type >

template<typename validator_t >

void sharg::detail::format_help_base< derived_type >::store_help_page_element	(	std::function< void()>	printer,
		config< validator_t > const &	config )

inlineprivate

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

Parameters

[in]	printer	The invokable that, if added to `parser_set_up_calls`, prints information to the help page.
[in]	config	The sharg::config object to access `config.advanced` and `config.hidden`.

If config.hidden = true, the information is never added to the help page. If config.advanced = true, 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).

◆ store_synopsis_flag()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::store_synopsis_flag ( detail::id_pair const & id )

inlineprivate

Stores flag information for synopsis generation.

Parameters

[in] id A sharg::detail::id_pair encapsulating both short and long id.

See also: https://pubs.opengroup.org/onlinepubs/9699919799

◆ store_synopsis_option()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::store_synopsis_option	(	detail::id_pair const &	id,
		std::string const &	type_str,
		bool const	required,
		bool const	is_list )

inlineprivate

Stores option information for synopsis generation.

Parameters

[in]	id	A sharg::detail::id_pair encapsulating both short and long id.
[in]	type_str	The type string for the option value.
[in]	required	Whether the option is required.
[in]	is_list	Whether it's a list of arguments.

See also: https://pubs.opengroup.org/onlinepubs/9699919799

◆ store_synopsis_positional()

template<typename derived_type >

void sharg::detail::format_help_base< derived_type >::store_synopsis_positional	(	std::string const &	type_str,
		bool const	is_list )

inlineprivate

Stores positional argument information for synopsis generation.

Parameters

[in]	type_str	The type string for the positional argument.
[in]	is_list	Whether it's a list of arguments.

See also: https://pubs.opengroup.org/onlinepubs/9699919799

Member Data Documentation

◆ meta

template<typename derived_type >

parser_meta_data sharg::detail::format_help_base< derived_type >::meta

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

format_base.hpp

Classes

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ format_help_base()

Member Function Documentation

◆ add_flag()

◆ add_line()

◆ add_list_item()

◆ add_option()

◆ add_positional_option()

◆ add_section()

◆ add_subsection()

◆ parse()

◆ print_line()

◆ store_help_page_element() [1/2]

◆ store_help_page_element() [2/2]

◆ store_synopsis_flag()

◆ store_synopsis_option()

◆ store_synopsis_positional()

Member Data Documentation

◆ meta