Sharg 1.1.2-rc.1
The argument parser for bio-c++ tools.
Loading...
Searching...
No Matches
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_typesMust be sharg::ostreamable (stream << value).
Parameters
[in]valuesVariable 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_typeType of the value to retrieve the conversion map for.
Parameters
valueThe 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;
}
}
Meta-header for the Parser module .
Parser exception that is thrown whenever there is an error while parsing the command line arguments.
Definition exceptions.hpp:40
The Sharg command line parser.
Definition parser.hpp:154
A validator that checks whether a value is inside a list of valid values.
Definition validators.hpp:175
Option struct that is passed to the sharg::parser::add_option() function.
Definition config.hpp:43
char short_id
The short identifier for the option (e.g. 'a', making the option callable via -a).
Definition config.hpp:53
T what(T... args)

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.
{"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,
.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;
}
auto const enumeration_names
Return a conversion map from std::string_view to option_type.
Definition enumeration_names.hpp:214
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
typeThe 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.
Hide me