Skip to content
Closed
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
155 changes: 147 additions & 8 deletions docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,139 @@ to `false`).
negative positionals after `--` (`./app -1 -- -1.5 -10`). An option still
takes a negative number as its value (`-n -5`).

## Lists and repeated options

A field that is read as a list (`std::vector`, `std::set`, `std::deque` and
the like, `std::array`, `rfl::Array`, tuples and pairs, inside any of the
wrappers above) takes comma-separated items. Its option can also be
repeated, like Boost's composing options and argparse's `extend`: every
occurrence is split at the commas, and the items are added in argv order.

```cpp
struct Config {
rfl::Short<"r", std::vector<std::string>> report;
};

// ./app --report a,b --report c -> report = {"a", "b", "c"}
// ./app -r a --report b --rep=c -> report = {"a", "b", "c"}
```

- Long, abbreviated and short spellings of a field all add to it.
- Repeating is the same as joining with a comma, so the size of a
`std::array` and validators such as `rfl::Size` see all items. An empty
occurrence (`--report=`) adds none.
- A bare occurrence of an `rfl::ImplicitValue` list adds its implicit value:
with `rfl::ImplicitValue<std::optional<std::vector<std::string>>, "all">`,
`--help-reports --help-reports=cpu` gives `{"all", "cpu"}`.
- Nested lists (`--database.replicas a --database.replicas b`) and map
entries whose values are lists (`--groups.x a --groups.x b`) work the
same way.

Any other option can be given only once. That includes nested
fields and map entries: `Duplicate argument: --output`,
`Duplicate short argument: -o`, `Conflict: '-o' and '--output' both provided.`

### List delimiter

`rfl::cli::ListDelimiter<"x">` splits lists at another character, and
`rfl::cli::ListDelimiter<"">` does not split them at all:

```cpp
rfl::cli::read<Config, rfl::cli::ListDelimiter<";">>(argc, argv);
// ./app --report 'a;b' --report c,d -> report = {"a", "b", "c,d"}

rfl::cli::read<Config, rfl::cli::ListDelimiter<"">>(argc, argv);
// ./app --report a,b --report '' -> report = {"a,b", ""}
```

- The delimiter is a single ASCII character, such as `;`, `:` or a space,
as in clap and CLI11. A longer one would make values such as `a;;;b`
ambiguous; repeat the option instead.
- It applies to every list option and list positional argument of the
struct. Other fields are never split.
- Without a delimiter, each occurrence, and each positional argument, is
exactly one item, even if it is empty.
- Other formats ignore it: `rfl::json::write`, `rfl::json::read` and
`rfl::json::to_schema` give the same results with it.

### A list as the last positional argument

If the last positional field is a list, it takes all remaining positional
arguments (last in the order of [Combining wrappers](#combining-wrappers),
which is declaration order unless some `Positional`s are wrapped), like
argparse's `nargs='+'` (or `'*'` if it is optional), and each argument is
split at the commas:

```cpp
struct Config {
rfl::Positional<std::string> command;
rfl::Positional<std::vector<std::string>> files;
};

// ./app run a,b -> files = {"a", "b"}
// ./app run a b -> files = {"a", "b"}
// ./app run a,b c -> files = {"a", "b", "c"}
```

- A plain list needs at least one argument. With `std::optional` or
`rfl::DefaultVal`, no arguments give `std::nullopt` or the default.
- Options can still come anywhere (`./app run a --verbose b`), unless the
struct is read with `rfl::cli::OptionsFirst` (below).
- The long form works as for any list: `--files=a,b`, or
`--files a --files b`. It cannot be mixed with bare arguments:
`Conflict: positional argument and '--files' both provided.`
- Only the last positional field takes the remaining arguments. A list
before other positional fields, such as `std::vector`, `std::set`, a
pair or a `std::array`, takes one argument, split at the commas.
- `resolve_args<T, ProcessorsType>`, for arguments parsed without the
option table, cannot repeat list options, so there a list as the last
positional field takes one argument.

### Options first

`rfl::cli::OptionsFirst` ends the options at the first positional argument,
like getopt's `+` mode (`POSIXLY_CORRECT`), argparse's `REMAINDER` and
clap's `trailing_var_arg`. Every later token is a positional argument, taken
as it is, even `--x`, `-x`, `--` and unknown options. With
`rfl::cli::ListDelimiter<"">`, a list as the last positional field gets the
rest of the command line unchanged, for example to pass it on to another
program:

```cpp
struct Recipe {
rfl::Short<"v", std::optional<bool>> verbose;
rfl::Positional<std::string> name;
rfl::Positional<rfl::DefaultVal<std::vector<std::string>>> args;
};

const auto result =
rfl::cli::read<Recipe, rfl::cli::OptionsFirst, rfl::cli::ListDelimiter<"">>(
argc, argv);

// ./recipe -v build --jobs 4 -v -- a,b
// -> verbose = true, name = "build",
// args = {"--jobs", "4", "-v", "--", "a,b"}
```

**Without `ListDelimiter<"">`, the passed-through arguments are lists like
any other:** each one is split at the commas and empty items are dropped.
`rfl::cli::read<Recipe, rfl::cli::OptionsFirst>` reads
`./recipe build --jobs 4,5 "" x` as
`args = {"--jobs", "4", "5", "x"}`. Pass `ListDelimiter<"">` to get the
arguments unchanged.

- Before the first positional argument, options work as usual, and `--`
ends them and is dropped (`./recipe -- -v` makes `-v` the name).
- After it, `--` is an argument like any other, as in getopt's `+` mode.
argparse drops a `--` that is the first token of a `REMAINDER`
(`recipe build -- x` gives `["x"]`); rfl keeps it.
- A token such as `-5` that is read as a positional argument (see
[grouped short options](#grouped-short-options)) also ends the options.
- `rfl::NoExtraFields` rejects unknown options before the first
positional argument.
- Without `OptionsFirst`, options and positional arguments can be mixed.
Other formats ignore the setting.

## Combining wrappers

`Short`, `Positional` and `ImplicitValue` can be nested with each other and
Expand Down Expand Up @@ -335,11 +468,11 @@ leaving out `-o` gives `"out"`.
| `bool` | `--flag` or `--flag=true` | No `=` implies `true` |
| `enum` | `--key=value_name` | Via `rfl::string_to_enum` |
| `std::optional<T>` | omit for `nullopt` | |
| `std::vector<T>` | `--key=a,b,c` | Comma-separated; empty elements skipped |
| `std::vector<T>` | `--key=a,b,c` or `--key a --key b,c` | Comma-separated; empty elements skipped; [repeatable](#lists-and-repeated-options) |
| Nested struct | `--parent.child=val` | Dot-separated path |
| `rfl::Flatten<T>` | fields inlined | No prefix needed |
| `rfl::Rename<"x", T>` | `--x=val` | Bypasses kebab conversion |
| `rfl::Positional<T>` | bare token | Matched in declaration order |
| `rfl::Positional<T>` | bare token | Matched in declaration order; a list last takes the rest |
| `rfl::Short<"x", T>` | `-x value`, `-x=value` or `-xvalue` | Single-character alias, can be grouped (`-qv`) |
| `rfl::ImplicitValue<T, "x">` | `--key` or `--key=value` | Bare means `x` |

Expand All @@ -350,14 +483,18 @@ Parsing proceeds in three stages:
1. **`parse_argv`** — categorizes raw tokens into `named`, `short_args`,
and `positional` buckets (`ParsedArgs` struct). `rfl::cli::read` gives
it an internal option table derived from the target struct, which says
which long and short options are flags, take a value or have an implicit
value, so that `--key value`, grouped short options and abbreviated long
options work, and whether a short option's name looks like a number. The
public `parse_argv`, which has no table, does none of these: `-abc` is the
one short option `abc`, and `-5` the short option `5`.
which long and short options are flags, take a value, have an implicit
value or are lists, so that `--key value`, grouped short options,
abbreviated long options and repeated list options work, and whether a
short option's name looks like a number. The public `parse_argv`, which
has no table, does none of these: `-abc` is the one short option `abc`,
and `-5` the short option `5`.
2. **`resolve_args`** — uses the same table to map short aliases to long
names and to merge positional arguments. Produces a flat
`map<string, string>`.
`map<string, string>`. A list option given more than once keeps its
first occurrence there and the others, in argv order, beside it. The
public `resolve_args<T, ProcessorsType>(parsed)`, for arguments parsed
without the table, returns the flat map alone.
3. **`Reader`** — implements reflect-cpp's `IsReader` concept by presenting
virtual tree nodes over the flat map. Each node is a `{map*, path}` pair —
no data copying, just prefix-based lookup via `lower_bound`.
Expand All @@ -370,6 +507,8 @@ Parsing proceeds in three stages:
- `include/rfl/cli/parse_argv.hpp` — `argv` -> `ParsedArgs`
- `include/rfl/cli/options.hpp` — the internal option table: the long, short and positional options of a struct
- `include/rfl/cli/NoAbbreviations.hpp` — `NoAbbreviations` processor
- `include/rfl/cli/ListDelimiter.hpp` — `ListDelimiter<"x">` processor
- `include/rfl/cli/OptionsFirst.hpp` — `OptionsFirst` processor
- `include/rfl/cli/resolve_args.hpp` — `ParsedArgs` -> `map<string, string>`
- `include/rfl/cli.hpp` — aggregator header
- `include/rfl/SnakeCaseToKebabCase.hpp` — processor
Expand Down
2 changes: 2 additions & 0 deletions include/rfl/cli.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
#define RFL_CLI_HPP_

#include "../rfl.hpp"
#include "cli/ListDelimiter.hpp"
#include "cli/NoAbbreviations.hpp"
#include "cli/OptionsFirst.hpp"
#include "cli/Parser.hpp"
#include "cli/Reader.hpp"
#include "cli/options.hpp"
Expand Down
91 changes: 91 additions & 0 deletions include/rfl/cli/ListDelimiter.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
#ifndef RFL_CLI_LISTDELIMITER_HPP_
#define RFL_CLI_LISTDELIMITER_HPP_

#include <cstddef>
#include <optional>
#include <type_traits>

#include "../Processors.hpp"
#include "../internal/StringLiteral.hpp"

namespace rfl::cli {

/// A setting for rfl::cli::read that sets the character at which the values
/// of list options and list positional arguments are split into items. The
/// default is ",": `--report=a,b` gives two items. ListDelimiter<";">
/// splits at ';' instead, and ListDelimiter<""> does not split, so every
/// value, and every positional argument, is exactly one item. The setting
/// applies to every list in the struct.
/// The delimiter is a single ASCII character, as in clap and CLI11. Several
/// characters would make the splitting of a value such as "a;;;b" with ";;"
/// ambiguous; repeat the option instead.
/// This is a marker type (doesn't modify data) that only rfl::cli::read looks
/// at. Other formats ignore it.
/// Usage: rfl::cli::read<Config, rfl::cli::ListDelimiter<";">>(argc, argv)
template <rfl::internal::StringLiteral _delimiter>
struct ListDelimiter {
static_assert(_delimiter.length == 0
|| (_delimiter.length == 1 && _delimiter.arr_[0] != '\0'
&& static_cast<unsigned char>(_delimiter.arr_[0])
< 0x80),
"rfl::cli::ListDelimiter takes a single ASCII character, "
"such as \";\", or \"\" to not split lists.");

/// The character at which list values are split, or std::nullopt if they
/// are not split.
static constexpr std::optional<char> delimiter =
_delimiter.length == 0 ? std::nullopt
: std::optional<char>(_delimiter.arr_[0]);

/// Identity process function - returns the named tuple unchanged.
/// @tparam StructType The struct type being processed
/// @param _named_tuple The named tuple representation of the struct
/// @return The same named tuple (unchanged)
template <class StructType>
static auto process(auto&& _named_tuple) {
return _named_tuple;
}
};

namespace internal {

/// `count` is the number of ListDelimiters in T, and `value` the delimiter
/// of the one there is.
template <class T>
struct list_delimiter {
static constexpr size_t count = 0;
static constexpr std::optional<char> value = std::nullopt;
};

template <rfl::internal::StringLiteral _delimiter>
struct list_delimiter<ListDelimiter<_delimiter>> {
static constexpr size_t count = 1;
static constexpr std::optional<char> value =
ListDelimiter<_delimiter>::delimiter;
};

template <class... Ps>
struct list_delimiter<Processors<Ps...>> {
static constexpr size_t count = (list_delimiter<Ps>::count + ... + 0);
static_assert(count <= 1, "Pass at most one rfl::cli::ListDelimiter.");
// The other processors have no value, so this is the one ListDelimiter's.
static constexpr char code = static_cast<char>(
(list_delimiter<Ps>::value.value_or('\0') + ... + 0));
static constexpr std::optional<char> value =
code == '\0' ? std::nullopt : std::optional<char>(code);
};

/// The character at which the processors say to split list values (',',
/// rfl::cli::array_delimiter, by default), or std::nullopt if they are not
/// split (ListDelimiter<"">).
template <class T>
constexpr std::optional<char> list_delimiter_v =
list_delimiter<std::remove_cvref_t<std::remove_pointer_t<T>>>::count == 0
? std::optional<char>(',')
: list_delimiter<std::remove_cvref_t<std::remove_pointer_t<T>>>::value;

} // namespace internal

} // namespace rfl::cli

#endif
66 changes: 66 additions & 0 deletions include/rfl/cli/OptionsFirst.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
#ifndef RFL_CLI_OPTIONSFIRST_HPP_
#define RFL_CLI_OPTIONSFIRST_HPP_

#include <type_traits>

#include "../Processors.hpp"

namespace rfl::cli {

/// A setting for rfl::cli::read that ends the options at the first
/// positional argument, like getopt's '+' mode (POSIXLY_CORRECT),
/// argparse's REMAINDER and clap's trailing_var_arg. Every later token is a
/// positional argument, taken as it is, even if it looks like an option:
/// `--x`, `-x`, unknown options and `--`. A `--` before the first
/// positional argument still ends the options and is dropped. Without
/// OptionsFirst, options and positional arguments can be mixed.
/// With a list as the last rfl::Positional field and ListDelimiter<"">, the
/// list gets the remaining arguments unchanged:
/// struct Recipe {
/// rfl::Positional<std::string> name;
/// rfl::Positional<std::vector<std::string>> args;
/// };
/// rfl::cli::read<Recipe, rfl::cli::OptionsFirst, rfl::cli::ListDelimiter<"">>
/// // recipe build --jobs 4 -- x -> name = "build",
/// // args = {"--jobs", "4", "--", "x"}
/// Without ListDelimiter<"">, the list splits each argument at the commas
/// and drops empty items, like any other list:
/// rfl::cli::read<Recipe, rfl::cli::OptionsFirst>
/// // recipe build --jobs 4,5 "" x -> args = {"--jobs", "4", "5", "x"}
/// This is a marker type (doesn't modify data) that only rfl::cli::read looks
/// at. Other formats ignore it.
/// Usage: rfl::cli::read<Config, rfl::cli::OptionsFirst>(argc, argv)
struct OptionsFirst {
public:
/// Identity process function - returns the named tuple unchanged.
/// @tparam StructType The struct type being processed
/// @param _named_tuple The named tuple representation of the struct
/// @return The same named tuple (unchanged)
template <class StructType>
static auto process(auto&& _named_tuple) {
return _named_tuple;
}
};

namespace internal {

template <class T>
struct options_first : std::false_type {};

template <>
struct options_first<OptionsFirst> : std::true_type {};

template <class... Ps>
struct options_first<Processors<Ps...>>
: std::bool_constant<(options_first<Ps>::value || ...)> {};

/// Whether the processors contain rfl::cli::OptionsFirst.
template <class T>
constexpr bool options_first_v =
options_first<std::remove_cvref_t<std::remove_pointer_t<T>>>::value;

} // namespace internal

} // namespace rfl::cli

#endif
Loading