Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,26 +267,34 @@ struct Database {
struct Config {
rfl::Positional<rfl::Description<"Path to the input file", std::string>>
input_file;
rfl::Short<"p", rfl::Description<"Port to listen on", int>> port;
rfl::Short<"p", rfl::Description<"Port to listen on",
rfl::Validator<int, rfl::Minimum<1>,
rfl::Maximum<65535>>>>
port;
rfl::Description<"Minimum level to log", std::optional<LogLevel>> log_level;
rfl::Description<"Tags to attach", std::vector<std::string>> tags;
rfl::Description<"Tags to attach",
rfl::Validator<std::vector<std::string>,
rfl::Size<rfl::Minimum<1>>>>
tags;
Database database;
};
```

`rfl::cli::usage<Config>("app", true).value()` is the usage line, where
optional arguments are in brackets, and one line per argument, with its
description, its default and whether it is required.
description, the constraints of its validators (`Range: 1..65535.`,
`Size: >= 1.`, `Pattern: ^[a-z]+$.`), `Deprecated: <message>.` for
`rfl::Deprecated`, its default and whether it is required.
`rfl::cli::usage<Config>("app")` gives only the usage line.

```
Usage: app <input-file> -p|--port=<value> [--log-level=<debug|info|warn>] --tags=<v1,v2,...> --database.host=<value> --database.port=<value>

Arguments:
<input-file> Path to the input file. Required.
-p, --port=<value> Port to listen on. Required.
-p, --port=<value> Port to listen on. Range: 1..65535. Required.
--log-level=<debug|info|warn> Minimum level to log
--tags=<v1,v2,...> Tags to attach. Required.
--tags=<v1,v2,...> Tags to attach. Size: >= 1. Required.
--database.host=<value> Required.
--database.port=<value> Required.
```
Expand Down
147 changes: 141 additions & 6 deletions include/rfl/cli/usage.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
#include "../parsing/is_required.hpp"
#include "../parsing/schema/Definition.hpp"
#include "../parsing/schema/Type.hpp"
#include "../parsing/schema/ValidationType.hpp"
#include "../parsing/schema/make.hpp"
#include "../to_generic.hpp"
#include "Reader.hpp"
Expand Down Expand Up @@ -66,6 +67,9 @@ struct UsageArg {
/// The allowed values of enums and literals.
std::vector<std::string> choices;
std::string description;
std::optional<std::string> deprecation;
/// Rendered constraints, such as "Range: 1..65535.".
std::vector<std::string> constraints;
std::optional<std::string> default_value;
};

Expand Down Expand Up @@ -135,6 +139,17 @@ inline std::string usage_number_to_string(const double _value) {
return stream.str();
}

inline std::string usage_number_to_string(
const rfl::Variant<double, int>& _value) {
return _value.visit([](const auto _v) -> std::string {
if constexpr (std::is_same_v<std::remove_cvref_t<decltype(_v)>, int>) {
return std::to_string(_v);
} else {
return usage_number_to_string(_v);
}
});
}

/// Renders a default value the way it would be passed on the command line.
/// Returns nullopt for values that cannot be rendered sensibly (null,
/// objects, empty arrays).
Expand Down Expand Up @@ -175,6 +190,110 @@ inline std::optional<std::string> usage_default_to_string(
_value.variant());
}

/// Renders a numeric bound such as ">= 1", "1..10" or "< 0 or > 10".
/// Returns nullopt if the validation is not purely numeric.
inline std::optional<std::string> usage_bounds_to_string(
const parsing::schema::ValidationType& _validation) {
using ValidationType = parsing::schema::ValidationType;
const auto join = [](const std::vector<ValidationType>& _types,
const std::string& _sep) -> std::optional<std::string> {
std::string joined;
for (const auto& t : _types) {
const auto str = usage_bounds_to_string(t);
if (!str) {
return std::nullopt;
}
joined += (joined.empty() ? "" : _sep) + *str;
}
return joined;
};
return _validation.variant_.visit(
[&](const auto& _v) -> std::optional<std::string> {
using V = std::remove_cvref_t<decltype(_v)>;
if constexpr (std::is_same_v<V, ValidationType::AllOf>) {
if (_v.types_.size() == 2) {
using Min = ValidationType::Minimum;
using Max = ValidationType::Maximum;
const auto& first = _v.types_[0].variant_;
const auto& second = _v.types_[1].variant_;
const auto* min = rfl::get_if<Min>(&first);
const auto* max = rfl::get_if<Max>(&second);
if (!min && !max) {
min = rfl::get_if<Min>(&second);
max = rfl::get_if<Max>(&first);
}
if (min && max) {
return usage_number_to_string(min->value_) + ".."
+ usage_number_to_string(max->value_);
}
}
return join(_v.types_, " and ");
} else if constexpr (std::is_same_v<V, ValidationType::AnyOf>
|| std::is_same_v<V, ValidationType::OneOf>) {
return join(_v.types_, " or ");
} else if constexpr (std::is_same_v<V, ValidationType::EqualTo>) {
return usage_number_to_string(_v.value_);
} else if constexpr (std::is_same_v<V, ValidationType::NotEqualTo>) {
return "!= " + usage_number_to_string(_v.value_);
} else if constexpr (std::is_same_v<V, ValidationType::Minimum>) {
return ">= " + usage_number_to_string(_v.value_);
} else if constexpr (std::is_same_v<V, ValidationType::Maximum>) {
return "<= " + usage_number_to_string(_v.value_);
} else if constexpr (std::is_same_v<V,
ValidationType::ExclusiveMinimum>) {
return "> " + usage_number_to_string(_v.value_);
} else if constexpr (std::is_same_v<V,
ValidationType::ExclusiveMaximum>) {
return "< " + usage_number_to_string(_v.value_);
} else {
return std::nullopt;
}
});
}

/// Renders a validation as one or more phrases, such as "Range: 1..10",
/// "Size: >= 1" or "Pattern: ^[a-z]+$".
inline std::vector<std::string> usage_constraints(
const parsing::schema::ValidationType& _validation) {
using ValidationType = parsing::schema::ValidationType;
if (const auto bounds = usage_bounds_to_string(_validation)) {
return {"Range: " + *bounds};
}
return _validation.variant_.visit(
[](const auto& _v) -> std::vector<std::string> {
using V = std::remove_cvref_t<decltype(_v)>;
if constexpr (std::is_same_v<V, ValidationType::AllOf>) {
std::vector<std::string> all;
for (const auto& t : _v.types_) {
const auto phrases = usage_constraints(t);
all.insert(all.end(), phrases.begin(), phrases.end());
}
return all;
} else if constexpr (std::is_same_v<V, ValidationType::AnyOf>
|| std::is_same_v<V, ValidationType::OneOf>) {
std::string joined;
for (const auto& t : _v.types_) {
std::string alternative;
for (const auto& phrase : usage_constraints(t)) {
alternative += (alternative.empty() ? "" : ", ") + phrase;
}
joined += (joined.empty() ? "" : " or ") + alternative;
}
return {joined};
} else if constexpr (std::is_same_v<V, ValidationType::Size>) {
const auto bounds = usage_bounds_to_string(*_v.size_limit_);
if (!bounds) {
return {};
}
return {"Size: " + *bounds};
} else if constexpr (std::is_same_v<V, ValidationType::Regex>) {
return {"Pattern: " + _v.pattern_};
} else {
return {};
}
});
}

/// Walks the format-agnostic schema of the struct and collects one UsageArg
/// per command-line argument, in declaration order.
class UsageCollector {
Expand Down Expand Up @@ -215,11 +334,17 @@ class UsageCollector {
// Description and Deprecated do not change how a field is read, so a
// DefaultVal inside them still makes the field optional
// (is_default_val_v). Short, Positional and Rename leave no node.
if constexpr (std::is_same_v<T, Type::Description>
|| std::is_same_v<T, Type::Deprecated>) {
if constexpr (std::is_same_v<T, Type::Description>) {
if (_arg.description.empty()) {
_arg.description = _t.description_;
}
add(*_t.type_, std::move(_arg), _default, _outermost);

} else if constexpr (std::is_same_v<T, Type::Deprecated>) {
if (_arg.description.empty()) {
_arg.description = _t.description_;
}
_arg.deprecation = _t.deprecation_message_;
add(*_t.type_, std::move(_arg), _default, _outermost);

} else if constexpr (std::is_same_v<T, Type::Optional>) {
Expand All @@ -240,6 +365,9 @@ class UsageCollector {
_t.default_value_ ? _t.default_value_ : _default, false);

} else if constexpr (std::is_same_v<T, Type::Validated>) {
const auto constraints = usage_constraints(_t.validation_);
_arg.constraints.insert(_arg.constraints.end(), constraints.begin(),
constraints.end());
add(*_t.type_, std::move(_arg), _default, false);

} else if constexpr (std::is_same_v<T, Type::Reference>) {
Expand Down Expand Up @@ -395,16 +523,23 @@ inline bool usage_ends_sentence(const std::string& _str) {
&& (_str.back() == '.' || _str.back() == '!' || _str.back() == '?');
}

/// "Port to connect on. Default: 8080. Required."
/// "Port to connect on. Range: 1..65535. Default: 8080. Required."
inline std::string usage_help_text(const UsageArg& _arg) {
auto sentences = std::vector<std::string>();
if (_arg.deprecation) {
sentences.push_back(_arg.deprecation->empty()
? std::string("Deprecated")
: "Deprecated: " + *_arg.deprecation);
}
if (_arg.positional && !_arg.choices.empty()) {
auto choices = std::string("Choices: ");
for (size_t i = 0; i < _arg.choices.size(); ++i) {
choices += (i == 0 ? "" : "|") + _arg.choices[i];
}
sentences.push_back(std::move(choices));
}
sentences.insert(sentences.end(), _arg.constraints.begin(),
_arg.constraints.end());
if (_arg.default_value) {
sentences.push_back("Default: " + *_arg.default_value);
}
Expand Down Expand Up @@ -493,9 +628,9 @@ std::optional<Generic> usage_defaults() {
/// the parser accepts (kebab-case, rfl::Rename, rfl::Flatten, nested paths).
///
/// The help text lists, where known, the description (rfl::Description), the
/// allowed values of enums and literals, the default value (rfl::DefaultVal,
/// or all fields with rfl::DefaultIfMissing) and whether the argument is
/// required.
/// allowed values of enums and literals, the constraints of validators, the
/// default value (rfl::DefaultVal, or all fields with rfl::DefaultIfMissing)
/// and whether the argument is required.
/// @tparam T The struct type that the arguments are parsed into
/// @tparam Ps The processors passed to `rfl::cli::read`
/// @param _program_name The name shown after "Usage:", usually argv[0]
Expand Down
44 changes: 43 additions & 1 deletion tests/cli/test_usage.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,47 @@ TEST(cli, test_usage_detailed) {
EXPECT_FALSE(rfl::cli::read<Described>(5, const_cast<char**>(no_verbose)));
}

struct Validated {
rfl::Description<"Port to listen on",
rfl::Validator<int, rfl::Minimum<1>, rfl::Maximum<65535>>>
port;
rfl::Validator<double, rfl::ExclusiveMinimum<0>, rfl::Maximum<1>> ratio;
rfl::Validator<int, rfl::ExclusiveMaximum<100>> percent;
rfl::Validator<int, rfl::AnyOf<rfl::Maximum<0>, rfl::Minimum<10>>> outside;
rfl::Validator<int, rfl::OneOf<rfl::EqualTo<1>, rfl::EqualTo<2>>> one_or_two;
rfl::Validator<int, rfl::NotEqualTo<0>> nonzero;
rfl::Validator<std::vector<std::string>, rfl::Size<rfl::Minimum<1>>> tags;
rfl::Validator<std::vector<int>,
rfl::Size<rfl::AllOf<rfl::Minimum<1>, rfl::Maximum<3>>>>
ids;
rfl::Validator<std::string, rfl::Size<rfl::Minimum<1>>,
rfl::PatternValidator<"^[a-z]+$", "Lowercase">>
user;
rfl::Literal<"fast", "slow"> mode;
};

TEST(cli, test_usage_validators) {
EXPECT_EQ(rfl::cli::usage<Validated>("app", true).value(),
"Usage: app --port=<value> --ratio=<value> --percent=<value> "
"--outside=<value> --one-or-two=<value> --nonzero=<value> "
"--tags=<v1,v2,...> --ids=<v1,v2,...> --user=<value> "
"--mode=<fast|slow>\n"
"\n"
"Arguments:\n"
" --port=<value> Port to listen on. Range: 1..65535. "
"Required.\n"
" --ratio=<value> Range: > 0 and <= 1. Required.\n"
" --percent=<value> Range: < 100. Required.\n"
" --outside=<value> Range: <= 0 or >= 10. Required.\n"
" --one-or-two=<value> Range: 1 or 2. Required.\n"
" --nonzero=<value> Range: != 0. Required.\n"
" --tags=<v1,v2,...> Size: >= 1. Required.\n"
" --ids=<v1,v2,...> Size: 1..3. Required.\n"
" --user=<value> Size: >= 1. Pattern: ^[a-z]+$. "
"Required.\n"
" --mode=<fast|slow> Required.\n");
}

struct WithDefaultVal {
rfl::DefaultVal<int> port = 8080;
rfl::DefaultVal<std::string> host = "localhost";
Expand Down Expand Up @@ -367,7 +408,8 @@ TEST(cli, test_usage_optionals) {
"Arguments:\n"
" <level> Choices: debug|info|warn.\n"
" -v, --verbose[=<bool>]\n"
" --old-port=<value> Old port\n"
" --old-port=<value> Old port. Deprecated: Use --port "
"instead.\n"
" --notes=<value> First line\n"
" Second line. Required.\n");
}
Expand Down