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::named_enumeration
	Checks whether the free function sharg::enumeration_names can be called on the type.

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

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

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.

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.