validators.cpp File Reference

The validator type and the built-in validators. More...

import cli11:encoding;
import std;

Classes
class	cli::validator_t
	A composable check applied to one command-line value. More...
class	cli::file_on_default_path_t
	Finds a file relative to a default directory when it is not found as given. More...
class	cli::range_t
	Requires the value to fall within a closed interval. More...
struct	cli::detail::program_name_t
	A command line split into the program and everything after it. More...

Typedefs
using	cli::custom_validator_t = validator_t
	A validator built from a user-supplied callable.

Enumerations
enum class	cli::detail::path_type_t : std::uint8_t { nonexistent , file , directory }
	What a path refers to on disk. More...

Functions
auto	cli::detail::check_path (std::string_view file) noexcept -> path_type_t
	Reports what a path refers to.
template<typename T> requires std::is_signed_v<T>
auto	cli::detail::overflow_check (const T &a, const T &b) -> bool
	Reports whether multiplying two signed values would overflow.
template<typename T> requires (!std::is_signed_v<T>)
auto	cli::detail::overflow_check (const T &a, const T &b) -> bool
	Reports whether multiplying two unsigned values would overflow.
template<typename T> requires std::is_integral_v<T>
auto	cli::detail::checked_multiply (T &a, T b) -> bool
	Multiplies in place, refusing to overflow.
template<typename T> requires std::is_floating_point_v<T>
auto	cli::detail::checked_multiply (T &a, T b) -> bool
	Multiplies in place, refusing to produce an infinity.
auto	cli::detail::split_program_name (std::string commandline) -> program_name_t
	Separates the program name from the rest of a command line.

Variables
const validator_t	cli::existing_file
	Requires the value to name an existing file.
const validator_t	cli::existing_directory
	Requires the value to name an existing directory.
const validator_t	cli::existing_path
	Requires the value to name something that exists.
const validator_t	cli::nonexistent_path
	Requires the value to name something that does not exist.
const validator_t	cli::escaped_string
	Resolves quoting and backslash escapes in the value.
const range_t	cli::non_negative_number ((std::numeric_limits< double >::max)(), "NONNEGATIVE")
	Requires the value to be zero or greater.
const range_t	cli::positive_number ((std::numeric_limits< double >::min)(),(std::numeric_limits< double >::max)(), "POSITIVE")
	Requires the value to be strictly greater than zero.

Detailed Description

The validator type and the built-in validators.

A cli::validator_t wraps a callable that inspects — and may rewrite — one value, returning an empty string on success or a message on failure. Attach one with option->check(...) or option->transform(...).

Validators compose. & requires both to pass, | requires either, and ! inverts, with the descriptions combined to match:

app.add_option("--f", file)->check(cli::existing_file & !cli::existing_directory);

The heavier validators — is_member, the transformers, and the unit parsers — live in the extra_validators partition.

Enumeration Type Documentation

path_type_t

enum class cli::detail::path_type_t : std::uint8_t

exportstrong

What a path refers to on disk.

Enumerator
nonexistent	Nothing exists at the path.
file	Something other than a directory exists at the path.
directory	A directory exists at the path.

Function Documentation

check_path()

auto cli::detail::check_path ( std::string_view file ) -> path_type_t

exportnoexcept

Reports what a path refers to.

Parameters

file	The path to inspect.

Returns

What the path refers to; path_type_t::nonexistent if it cannot be inspected at all.

checked_multiply() [1/2]

template<typename T>
requires std::is_floating_point_v<T>

auto cli::detail::checked_multiply ( T & a, T b ) -> bool

export

Multiplies in place, refusing to produce an infinity.

Parameters

[in,out]	a	The value to multiply; left untouched on failure.
[in]	b	The multiplier.

Returns

true if the multiplication was performed.

checked_multiply() [2/2]

template<typename T>
requires std::is_integral_v<T>

auto cli::detail::checked_multiply ( T & a, T b ) -> bool

export

Multiplies in place, refusing to overflow.

Parameters

[in,out]	a	The value to multiply; left untouched on failure.
[in]	b	The multiplier.

Returns

true if the multiplication was performed.

overflow_check() [1/2]

template<typename T>
requires (!std::is_signed_v<T>)

auto cli::detail::overflow_check ( const T & a, const T & b ) -> bool

export

Reports whether multiplying two unsigned values would overflow.

Parameters

a	The left operand.
b	The right operand.

Returns

true if the product would not be representable.

overflow_check() [2/2]

template<typename T>
requires std::is_signed_v<T>

auto cli::detail::overflow_check ( const T & a, const T & b ) -> bool

export

Reports whether multiplying two signed values would overflow.

Parameters

a	The left operand.
b	The right operand.

Returns

true if the product would not be representable.

split_program_name()

auto cli::detail::split_program_name ( std::string commandline ) -> program_name_t

export

Separates the program name from the rest of a command line.

The program name may contain spaces, so candidate prefixes are tested against the filesystem until one names a file. Quoted program names are unquoted, and escaped quotes within them are resolved.

Parameters

commandline

The full command line.

Returns

The program name and the remaining arguments.

Variable Documentation

escaped_string

const validator_t cli::escaped_string

export

Initial value:

{[](std::string &str) {
                                          try
                                          {
                                              if (str.size() > 1 &&
                                                  (str.front() == '\"' || str.front() == '\'' || str.front() == '`') &&
                                                  str.front() == str.back())
                                              {
                                                  detail::process_quoted_string(str);
                                              }
                                              else if (str.find_first_of('\\') != std::string::npos)
                                              {
                                                  if (detail::is_binary_escaped_string(str))
                                                  {
                                                      str = detail::extract_binary_string(str);
                                                  }
                                                  else
                                                  {
                                                      str = detail::remove_escaped_characters(str);
                                                  }
                                              }
                                              return std::string {};
                                          }
                                          catch (const std::invalid_argument &ia)
                                          {
                                              return std::string(ia.what());
                                          }
                                      },
                                      std::string {}}

Resolves quoting and backslash escapes in the value.

This rewrites its argument rather than only inspecting it.

existing_directory

const validator_t cli::existing_directory

export

Initial value:

{[](std::string &filename) {
                                              const auto path_result = detail::check_path(filename);
                                              if (path_result == detail::path_type_t::nonexistent)
                                              {
                                                  return "Directory does not exist: " + filename;
                                              }
                                              if (path_result == detail::path_type_t::file)
                                              {
                                                  return "Directory is actually a file: " + filename;
                                              }
                                              return std::string();
                                          },
                                          "DIR"}

Requires the value to name an existing directory.

existing_file

const validator_t cli::existing_file

export

Initial value:

{[](std::string &filename) {
                                         const auto path_result = detail::check_path(filename);
                                         if (path_result == detail::path_type_t::nonexistent)
                                         {
                                             return "File does not exist: " + filename;
                                         }
                                         if (path_result == detail::path_type_t::directory)
                                         {
                                             return "File is actually a directory: " + filename;
                                         }
                                         return std::string();
                                     },
                                     "FILE"}

Requires the value to name an existing file.

existing_path

const validator_t cli::existing_path

export

Initial value:

{[](std::string &filename) {
                                         const auto path_result = detail::check_path(filename);
                                         if (path_result == detail::path_type_t::nonexistent)
                                         {
                                             return "Path does not exist: " + filename;
                                         }
                                         return std::string();
                                     },
                                     "PATH(existing)"}

Requires the value to name something that exists.

nonexistent_path

const validator_t cli::nonexistent_path

export

Initial value:

{[](std::string &filename) {
                                            const auto path_result = detail::check_path(filename);
                                            if (path_result != detail::path_type_t::nonexistent)
                                            {
                                                return "Path already exists: " + filename;
                                            }
                                            return std::string();
                                        },
                                        "PATH(non-existing)"}

Requires the value to name something that does not exist.