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
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -382,6 +382,14 @@ if (argc > 1 && std::string_view(argv[1]) == "--help") {
}
```

`rfl::ImplicitValue<T, "text">` lets an option be given without a value, which then stands for the text:

```cpp
rfl::ImplicitValue<std::optional<std::string>, "auto"> color;
// ./app --color -> color = "auto"
// ./app --color=never -> color = "never"
```

Nested structs, `std::optional`, `std::vector`, enums, `rfl::Flatten` and `rfl::Rename` are all supported. Refer to the [documentation](https://munich-data-engineering.github.io/reflect-cpp/cli) for details.

### Error messages
Expand Down
6 changes: 3 additions & 3 deletions docs/content/default_val.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ const auto homer = rfl::json::read<Person, rfl::NoFieldNames>(R"(["Homer"])").va
// homer.town == ""
```

An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description`, `rfl::Deprecated` or `rfl::Rename`, in any order, works like a bare one: a field `rfl::Description<"Worker threads", rfl::DefaultVal<int>> jobs = 4;` may be omitted and is then 4.
An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description`, `rfl::Deprecated` or `rfl::Rename`, in any order, works like a bare one: a field `rfl::Description<"Worker threads", rfl::DefaultVal<int>> jobs = 4;` may be omitted and is then 4. `rfl::ImplicitValue` is read as its inner type by every format but the command line, so an `rfl::DefaultVal` inside it counts as a bare one in all of the following.

## All fields need a valid default value

Expand Down Expand Up @@ -90,9 +90,9 @@ The field is still required. If `favorite_foods` is missing in the input, you ge

The same restriction applies to every struct that is read with the `rfl::DefaultIfMissing` processor, whether it contains an `rfl::DefaultVal` or not.

An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description` or `rfl::Deprecated` gets its default only if the struct can be default-constructed. If all its `rfl::DefaultVal` fields are wrapped and the struct cannot be default-constructed, because a field's type has no default constructor or the default constructor throws, the struct is read without its default values, so those fields must be present in the input. With a bare `rfl::DefaultVal`, such a struct does not compile, or you get the error above.
An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description` or `rfl::Deprecated` (but not one inside only `rfl::ImplicitValue`, which is a bare one) gets its default only if the struct can be default-constructed. If all its `rfl::DefaultVal` fields are wrapped and the struct cannot be default-constructed, because a field's type has no default constructor or the default constructor throws, the struct is read without its default values, so those fields must be present in the input. With a bare `rfl::DefaultVal`, such a struct does not compile, or you get the error above.

An `rfl::NamedTuple` has no in-class initializers. A missing bare `rfl::DefaultVal<T>` field in it is set to `T{}`. If `T` has no default constructor, or `T{}` throws (for instance a validator that rejects its zero value), the field must be present in the input. An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description` or `rfl::Deprecated` must always be present in an `rfl::NamedTuple`.
An `rfl::NamedTuple` has no in-class initializers. A missing bare `rfl::DefaultVal<T>` field in it, also inside `rfl::ImplicitValue`, is set to `T{}`. If `T` has no default constructor, or `T{}` throws (for instance a validator that rejects its zero value), the field must be present in the input. An `rfl::DefaultVal` inside `rfl::Short`, `rfl::Positional`, `rfl::Description` or `rfl::Deprecated` must always be present in an `rfl::NamedTuple`.

## When to use

Expand Down
70 changes: 54 additions & 16 deletions docs/content/supported_formats/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ as `rfl::Short`, `rfl::Description` or `rfl::DefaultVal`. The next token is
the value unless it looks like an option (`-` followed by anything except a
digit or `.`), so `--offset -5` works. If the value is missing, parsing
fails with `Missing value for option '--sql'.` Use `=` to pass an empty
value or one that starts with `-`: `--sql=`, `--pattern=-x`.
value or one that starts with `-`: `--sql=`, `--pattern=-x`. For an option
whose value may be left out, use `rfl::ImplicitValue` (below).

Boolean fields (`bool`, `std::optional<bool>` and wrapped bools) are flags
and never consume the next token: `--verbose input.txt` sets `verbose` and
Expand All @@ -105,6 +106,35 @@ Without the processor, `--sql SELECT` sets `sql` to an empty string and
passes `SELECT` as a positional argument. The public `rfl::cli::parse_argv`
does not know the struct, so it always reads it that way.

## Implicit values

Wrap a field with `rfl::ImplicitValue<T, "text">` to let its option be given
without a value, like Boost's `implicit_value`:

```cpp
struct Config {
rfl::Short<"h", rfl::ImplicitValue<std::optional<std::string>>> help;
rfl::ImplicitValue<std::optional<std::string>, "all"> help_reports;
rfl::ImplicitValue<rfl::DefaultVal<int>, "2"> verbosity = 0;
rfl::Positional<std::optional<std::string>> input;
};

// ./app --help-reports -> help_reports = "all"
// ./app --help-reports=memory -> help_reports = "memory"
// ./app --help-reports in.txt -> help_reports = "all", input = "in.txt"
// ./app -h / -h=tag / -htag -> help = "" / "tag" / "tag"
// ./app --verbosity -> verbosity = 2
```

A bare option stands for the text, which is parsed like any other value;
the next token is never taken. The text may be left out (it is then empty)
only for a `bool`, a `std::string` or a list, where an empty value means
something; any other type needs one, such as `rfl::ImplicitValue<int, "1">`. If the option is
absent, the field is read as usual: `std::optional` gives `std::nullopt`,
`rfl::DefaultVal` its default, and any other field is required. Other formats
read and write `rfl::ImplicitValue` as its inner type, as they do
`rfl::Short`.

## Unknown options

By default, long options that match no field are ignored, and they do not
Expand All @@ -128,9 +158,9 @@ rfl::cli::read<Config, rfl::cli::AllowAbbreviations>(argc, argv);

A long option can then be shortened to a prefix that matches only one option:
with fields `report` and `format`, `--rep=a` and `--form` stand for
`--report=a` and `--format`. This works for flags,
positional fields given by name and nested fields, where only the last part
of the dotted name is shortened: `--database.h` stands for
`--report=a` and `--format`. This works for flags, `rfl::ImplicitValue`
options, positional fields given by name and nested fields, where only the
last part of the dotted name is shortened: `--database.h` stands for
`--database.host`, but `--data` and `--database.` stand for nothing.

- An exact name always wins: `--format` is `--format` even when
Expand Down Expand Up @@ -242,9 +272,11 @@ struct Config {
```

Flags are set up to the first option that takes a value. That option takes
the rest of the token, or the next token if nothing is left. The last
option in a token treats the next token as it would alone (`-qv false` sets
`verbose` to `false`).
the rest of the token, or the next token if nothing is left. An
`rfl::ImplicitValue` option takes the rest of the token if there is any and
its implicit value otherwise, never the next token. The last option in a
token treats the next token as it would alone (`-qv false` sets `verbose`
to `false`).

- `-f=csv` and `-qf=csv` give `csv`: the `=` is not part of the value.
- A flag inside a group takes no value: `-vq=false` is an error.
Expand Down Expand Up @@ -280,6 +312,9 @@ struct Config {
- 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.
Expand Down Expand Up @@ -316,8 +351,8 @@ struct Config {

## Combining wrappers

`Short` and `Positional` can be nested with `DefaultVal`, `std::optional`,
`Description`, `Rename` and `Deprecated` in any order:
`Short`, `Positional` and `ImplicitValue` can be nested with `DefaultVal`,
`std::optional`, `Description`, `Rename` and `Deprecated` in any order:
`rfl::Description<"...", rfl::Short<"o", T>>` is `-o`, and
`rfl::DefaultVal<rfl::Positional<T>>` is positional. Put `rfl::Rename`
outermost, as in `rfl::Rename<"out", rfl::Short<"o", T>>`; inside other
Expand All @@ -327,8 +362,8 @@ Bare arguments go to the `Positional` fields in declaration order. Two fields
with the same `Short` name make every read fail with
`Duplicate short name '-o' in struct definition.` A field with more than one
`Short` or `Positional`, such as `rfl::Positional<rfl::Short<"o", T>>` or
`rfl::Short<"o", rfl::Description<"...", rfl::Positional<T>>>`, is a
compile-time error:
`rfl::Short<"o", rfl::Description<"...", rfl::Positional<T>>>`, and a
`Positional` field with an `ImplicitValue`, are compile-time errors:

```cpp
struct Config {
Expand Down Expand Up @@ -428,11 +463,12 @@ Arguments:

Each argument is shown as the option table that `read` parses with (see
[Architecture](#architecture)) reads it: a `bool`, also inside a nested
struct, is a flag whose value can be left out (`--verbose[=<bool>]`), a list
takes comma-separated items and can be repeated (`--tags=<v1,v2,...>`, with
`Can be repeated.` in its row), a list as the last `rfl::Positional` takes
the remaining arguments (`<files>...`), and every other option takes a value
(`--port=<value>`).
struct, is a flag whose value can be left out (`--verbose[=<bool>]`), so is
an `rfl::ImplicitValue` option (`--color[=<never|always>]`, with
`Without a value: always.` in its row), a list takes comma-separated items
and can be repeated (`--tags=<v1,v2,...>`, with `Can be repeated.` in its
row), a list as the last `rfl::Positional` takes the remaining arguments
(`<files>...`), and every other option takes a value (`--port=<value>`).

`rfl::Positional` and `rfl::Short` are found through the other wrappers, as
the parser does (see [Combining wrappers](#combining-wrappers)), so
Expand Down Expand Up @@ -468,6 +504,7 @@ int main(int argc, char* argv[]) {
| `rfl::Rename<"x", T>` | `--x=val` | Bypasses kebab conversion |
| `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` |

## Architecture

Expand Down Expand Up @@ -502,3 +539,4 @@ Parsing proceeds in three stages:
- `include/rfl/SnakeCaseToKebabCase.hpp` — processor
- `include/rfl/Positional.hpp` — `Positional<T>` wrapper
- `include/rfl/Short.hpp` — `Short<"x", T>` wrapper
- `include/rfl/ImplicitValue.hpp` — `ImplicitValue<T, "x">` wrapper
1 change: 1 addition & 0 deletions include/rfl.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
#include "rfl/Flatten.hpp"
#include "rfl/Generic.hpp"
#include "rfl/Hex.hpp"
#include "rfl/ImplicitValue.hpp"
#include "rfl/Literal.hpp"
#include "rfl/NamedTuple.hpp"
#include "rfl/NoExtraFields.hpp"
Expand Down
Loading