Misc

The Misc Module. More...

Collaboration diagram for Misc:

Topics
	std
	The <charconv> header from C++17's standard library.

Concepts
concept	sharg::istreamable
	Concept for types that can be parsed from a std::istream via the stream operator.
concept	sharg::ostreamable
	Concept for types that can be parsed into a std::ostream via the stream operator.
concept	sharg::parsable
	Checks whether the the type can be used in an add_(positional_)option call on the parser.
concept	sharg::detail::is_container_option
	Whether the option type is considered to be a container.
concept	sharg::named_enumeration
	Checks whether the free function sharg::enumeration_names can be called on the type.

Classes
class	sharg::detail::safe_filesystem_entry
	A safe guard to manage a filesystem entry, e.g. a file or a directory. More...
struct	sharg::custom::parsing< t >
	A type that can be specialised to provide customisation point implementations for the sharg::parser such that third party types may be adapted. More...
struct	sharg::detail::priority_tag< I >
	A tag that allows controlled overload resolution via implicit base conversion rules. More...
struct	sharg::detail::adl_only::enumeration_names_cpo< option_t >
	Customization Point Object (CPO) definition for sharg::enumeration_names. More...

Enumerations
enum class	sharg::update_notifications { update_notifications::on , update_notifications::off }
	Indicates whether application allows automatic update notifications by the sharg::parser. More...

Functions
template<typename... value_types> requires (ostreamable<value_types> && ...)
std::string	sharg::detail::to_string (value_types &&... values)
	Streams all parameters via std::ostringstream and returns a concatenated string.

Variables
template<typename type >
std::string const	sharg::detail::type_name_as_string
	Defines the human-readable name of the given type using the typeid operator.

Customisation Points
template<typename option_type >
auto const	sharg::enumeration_names = detail::adl_only::enumeration_names_cpo<option_type>{}()
	Return a conversion map from std::string_view to option_type.

Detailed Description

The Misc Module.

Enumeration Type Documentation

update_notifications

enum class sharg::update_notifications

strong

Indicates whether application allows automatic update notifications by the sharg::parser.

This entity is stable. Since version 1.0.

Enumerator
on	Automatic update notifications should be enabled.
off	Automatic update notifications should be disabled.

Function Documentation

to_string()

template<typename... value_types>
requires (ostreamable<value_types> && ...)

std::string sharg::detail::to_string

(

value_types &&...

values

)

Streams all parameters via std::ostringstream and returns a concatenated string.

Template Parameters

value_types

Must be sharg::ostreamable (stream << value).

Parameters

[in]

values

Variable number of parameters of any type that implement the stream operator.

Returns

A concatenated string of all values (no separator in between is added).

Variable Documentation

enumeration_names

template<typename option_type >

auto const sharg::enumeration_names = detail::adl_only::enumeration_names_cpo<option_type>{}()

inline

Return a conversion map from std::string_view to option_type.

Template Parameters

your_type

Type of the value to retrieve the conversion map for.

Parameters

value

The value is not accessed, only its type is used.

Returns

A std::unordered_map<std::string_view, your_type> that maps a string identifier to a value of your_type.

This is a function object. Invoke it with the parameter(s) specified above.

It acts as a wrapper and looks for two possible implementations (in this order):

1. A static member enumeration_names in sharg::custom::parsing<your_type> that is of type std::unordered_map<std::string_view, your_type>>.
2. A free function enumeration_names(your_type const a) in the namespace of your type (or as friend) which returns a std::unordered_map<std::string_view, your_type>>.

Example

If you are working on a type in your namespace, you should implement a free function like this:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <sharg/all.hpp>
 
namespace foo
{
 
enum class bar
{
    one,
    two,
    three
};
 
// Specialise a mapping from an identifying string to the respective value of your type bar.
auto enumeration_names(bar)
{
    return std::unordered_map<std::string_view, bar>{{"one", bar::one}, {"two", bar::two}, {"three", bar::three}};
}
 
} // namespace foo
 
int main(int argc, char const * argv[])
{
    foo::bar value{};
 
    sharg::parser parser{"my_program", argc, argv};
 
    // Because of the enumeration_names function
    // you can now add an option that takes a value of type bar:
    auto vali = sharg::value_list_validator{(sharg::enumeration_names<foo::bar> | std::views::values)};
    parser.add_option(
        value,
        sharg::config{.short_id = 'f', .long_id = "foo", .description = "Give me a value for foo.", .validator = vali});
 
    try
    {
        parser.parse();
    }
    catch (sharg::parser_error const & ext) // the user did something wrong
    {
        std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
        return -1;
    }
}

Only if you cannot access the namespace of your type to customize you may specialize the sharg::custom::parsing struct like this:

// SPDX-FileCopyrightText: 2006-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <system_error>
 
#include <sharg/all.hpp>
 
namespace sharg::custom
{
// Specialise the sharg::custom::parsing data structure to enable parsing of std::errc.
template <>
struct parsing<std::errc>
{
    // Specialise a mapping from an identifying string to the respective value of your type Foo.
    static inline std::unordered_map<std::string_view, std::errc> const enumeration_names{
        {"no_error", std::errc{}},
        {"timed_out", std::errc::timed_out},
        {"invalid_argument", std::errc::invalid_argument},
        {"io_error", std::errc::io_error}};
};
 
} // namespace sharg::custom
 
int main(int argc, char const * argv[])
{
    std::errc value{};
 
    sharg::parser parser{"my_program", argc, argv};
 
    // Because of the parsing struct and
    // the static member function enumeration_names
    // you can now add an option that takes a value of type std::errc:
    auto validator = sharg::value_list_validator{(sharg::enumeration_names<std::errc> | std::views::values)};
    parser.add_option(value,
                      sharg::config{.short_id = 'e',
                                    .long_id = "errc",
                                    .description = "Give me a std::errc value.",
                                    .validator = validator});
 
    try
    {
        parser.parse();
    }
    catch (sharg::parser_error const & ext) // the user did something wrong
    {
        std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
        return -1;
    }
 
    return 0;
}

Remarks

For a complete overview, take a look at Parser

Customisation point

This is a customisation point (see Customisation). To specify the behaviour for your type, simply provide one of the two functions specified above.

This entity is experimental and subject to change in the future. Experimental since version 1.0.

type_name_as_string

template<typename type >

std::string const sharg::detail::type_name_as_string

inline

Defines the human-readable name of the given type using the typeid operator.

Template Parameters

type	The type to get the human-readable name for.

On gcc and clang std::type_info only returns a mangled name. The mangled name can be converted to human-readable form using implementation-specific API such as abi::__cxa_demangle. In other implementations the name returned is already human-readable.

Note

The returned name is implementation defined and might change between different tool chains.