general/CLI11
2
0
Fork 0
mirror of https://github.com/CLIUtils/CLI11.git synced 2026-01-19 04:52:08 +00:00
Code Issues Projects Releases Wiki Activity

update version and changelog for 2.5 release (#1121)

Browse Source 
update readme, changelog, and version for 2.5 release

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
This commit is contained in:
Philip Top
2025-02-27 04:25:31 -08:00
committed by GitHub
parent a48f049365
commit 4160d259d9
3 changed files with 100 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
README.md
View File

@@ -165,6 +165,9 @@ this library:
option to disable it).
- Autocomplete: This might eventually be added to both Plumbum and CLI11, but it
is not supported yet.
- While not recommended, CLI11 does now support non standard option names such
as `-option`. 🆕. This is enabled through `allow_non_standard_option_names()`
modifier on an app.
## Install
@@ -203,9 +206,8 @@ int main(int argc, char** argv) {
}
```
For more information about 🆕`ensure_utf8` the section on
[Unicode support](#unicode-support) below. The 🆕`ensure_utf8` function is only
available in main currently and not in a release.
For more information about `ensure_utf8` the section on
[Unicode support](#unicode-support) below.
<details><summary>Note: If you don't like macros, this is what that macro expands to: (click to expand)</summary><p>
@@ -415,7 +417,7 @@ Before parsing, you can set the following options:
option. Options can be removed from the excludes list with
`->remove_excludes(opt)`
- `->envname(name)`: Gets the value from the environment if present and not
passed on the command line. 🆕 The value must also pass any validators to be
passed on the command line. The value must also pass any validators to be
used.
- `->group(name)`: The help group to put the option in. No effect for positional
options. Defaults to `"Options"`. Options given an empty string will not show
@@ -451,7 +453,7 @@ Before parsing, you can set the following options:
are `CLI::MultiOptionPolicy::Throw`, `CLI::MultiOptionPolicy::Throw`,
`CLI::MultiOptionPolicy::TakeLast`, `CLI::MultiOptionPolicy::TakeFirst`,
`CLI::MultiOptionPolicy::Join`, `CLI::MultiOptionPolicy::TakeAll`,
`CLI::MultiOptionPolicy::Sum`, and `CLI::MultiOptionPolicy::Reverse` 🆕.
`CLI::MultiOptionPolicy::Sum`, and `CLI::MultiOptionPolicy::Reverse`.
- `->check(std::string(const std::string &), validator_name="",validator_description="")`:
Define a check function. The function should return a non empty string with
the error message if the check fails
@@ -701,8 +703,8 @@ filters on the key values is performed.
`CLI::FileOnDefaultPath(default_path, false)`. This allows multiple paths to
be chained using multiple transform calls.
- `CLI::EscapedString`: 🆕 can be used to process an escaped string. The
processing is equivalent to that used for TOML config files, see
- `CLI::EscapedString`: can be used to process an escaped string. The processing
is equivalent to that used for TOML config files, see
[TOML strings](https://toml.io/en/v1.0.0#string). With 2 notable exceptions.
\` can also be used as a literal string notation, and it also allows binary
string notation see
@@ -859,7 +861,9 @@ triggered once unless the `.immediate_callback()` flag is set or the callback is
specified through the `parse_complete_callback()` function. The
`final_callback()` is triggered only once. In which case the callback executes
on completion of the subcommand arguments but after the arguments for that
subcommand have been parsed, and can be triggered multiple times.
subcommand have been parsed, and can be triggered multiple times. Note that the
`parse_complete_callback()` is executed prior to processing any config files.
The `final_callback()` is executed after config file processing.
Subcommands may also have an empty name either by calling `add_subcommand` with
an empty string for the name or with no arguments. Nameless subcommands function
@@ -873,7 +877,7 @@ nameless subcommands are allowed. Callbacks for nameless subcommands are only
triggered if any options from the subcommand were parsed. Subcommand names given
through the `add_subcommand` method have the same restrictions as option names.
🆕 Options or flags in a subcommand may be directly specified using dot notation
Options or flags in a subcommand may be directly specified using dot notation
- `--subcommand.long=val` (long subcommand option)
- `--subcommand.long val` (long subcommand option)
@@ -885,8 +889,8 @@ through the `add_subcommand` method have the same restrictions as option names.
The use of dot notation in this form is equivalent `--subcommand.long <args>` =>
`subcommand --long <args> ++`. Nested subcommands also work `sub1.subsub` would
trigger the subsub subcommand in `sub1`. This is equivalent to "sub1 subsub".
Quotes around the subcommand names are permitted 🆕 following the TOML standard
for such specification. This includes allowing escape sequences. For example
Quotes around the subcommand names are permitted following the TOML standard for
such specification. This includes allowing escape sequences. For example
`"subcommand".'f'` or `"subcommand.with.dots".arg1 = value`.
#### Subcommand options
@@ -902,7 +906,7 @@ option_groups. These are:
the form of `/s /long /file:file_name.ext` This option does not change how
options are specified in the `add_option` calls or the ability to process
options in the form of `-s --long --file=file_name.ext`.
- `.allow_non_standard_option_names()`:🚧 Allow specification of single `-` long
- `.allow_non_standard_option_names()`:🆕 Allow specification of single `-` long
form option names. This is not recommended but is available to enable
reworking of existing interfaces. If this modifier is enabled on an app or
subcommand, options or flags can be specified like normal but instead of
@@ -914,8 +918,8 @@ option_groups. These are:
through" and be matched on a parent option. Subcommands by default are allowed
to "fall through" as in they will first attempt to match on the current
subcommand and if they fail will progressively check parents for matching
subcommands. This can be disabled through `subcommand_fallthrough(false)` 🚧.
- `.subcommand_fallthrough()`: 🚧 Allow subcommands to "fall through" and be
subcommands. This can be disabled through `subcommand_fallthrough(false)` 🆕.
- `.subcommand_fallthrough()`: 🆕 Allow subcommands to "fall through" and be
matched on a parent option. Disabling this prevents additional subcommands at
the same level from being matched. It can be useful in certain circumstances
where there might be ambiguity between subcommands and positionals. The
@@ -1027,10 +1031,10 @@ option_groups. These are:
the first unrecognized item. All subsequent arguments are placed in the
remaining_arg list. It is ideal for allowing your app or subcommand to be a
"prefix" to calling another app.
- `.usage(message)`: 🆕 Replace text to appear at the start of the help string
- `.usage(message)`: Replace text to appear at the start of the help string
after description.
- `.usage(std::string())`: 🆕 Set a callback to generate a string that will
appear at the start of the help string after description.
- `.usage(std::string())`: Set a callback to generate a string that will appear
at the start of the help string after description.
- `.footer(message)`: Set text to appear at the bottom of the help string.
- `.footer(std::string())`: Set a callback to generate a string that will appear
at the end of the help string.
@@ -1113,8 +1117,8 @@ A subcommand is considered terminated when one of the following conditions are
met.
1. There are no more arguments to process
2. Another subcommand is encountered that would not fit in an optional slot of
the subcommand
2. Another subcommand is encountered that would not fit in an optional
positional slot of the subcommand
3. The `positional_mark` (`--`) is encountered and there are no available
positional slots in the subcommand.
4. The `subcommand_terminator` mark (`++`) is encountered
@@ -1246,11 +1250,11 @@ is present, it will be read along with the normal command line arguments. The
file will be read if it exists, and does not throw an error unless `required` is
`true`. Configuration files are in [TOML][] format by default, though the
default reader can also accept files in INI format as well. The config reader
can read most aspects of TOML files including strings both literal 🆕 and with
potential escape sequences 🆕, digit separators 🆕, and multi-line strings 🆕,
and run them through the CLI11 parser. Other formats can be added by an adept
user, some variations are available through customization points in the default
formatter. An example of a TOML file:
can read most aspects of TOML files including strings both literal and with
potential escape sequences, digit separators, and multi-line strings, and run
them through the CLI11 parser. Other formats can be added by an adept user, some
variations are available through customization points in the default formatter.
An example of a TOML file:
```toml
# Comments are supported, using a #