mirror of
https://github.com/CLIUtils/CLI11.git
synced 2025-05-07 23:33:52 +00:00
docs: use gfm notes in README (#952)
A fairly new addition to GitHub Flavored Markdown. --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Philip Top <phlptp@gmail.com>
This commit is contained in:
Henry Schreiner
GitHub
parent
3b58c65c2e
commit
3bc2739c11
114
README.md
114
README.md
@ -1025,9 +1025,11 @@ option_groups. These are:
|
||||
command line for a flag. The operation will throw an exception if the option
|
||||
name is not valid.
|
||||
|
||||
> Note: if you have a fixed number of required positional options, that will
|
||||
> match before subcommand names. `{}` is an empty filter function, and any
|
||||
> positional argument will match before repeated subcommand names.
|
||||
> [!NOTE]
|
||||
>
|
||||
> If you have a fixed number of required positional options, that will match
|
||||
> before subcommand names. `{}` is an empty filter function, and any positional
|
||||
> argument will match before repeated subcommand names.
|
||||
|
||||
#### Callbacks
|
||||
|
||||
@ -1411,68 +1413,70 @@ function may already receive broken Unicode. Parsing `argv` at that point will
|
||||
not give you a correct string. To fix this, you have three good options and two
|
||||
bad ones:
|
||||
|
||||
1. Replace `argv` with `app.ensure_utf8(argv)` before any arguments are parsed.
|
||||
`ensure_utf8` will do nothing on systems where `argv` is already in UTF-8
|
||||
(Such as Linux or macOS) and return `argv` unmodified. On Windows, it will
|
||||
discard `argv` and replace it with a correctly decoded array or arguments
|
||||
from win32 API.
|
||||
1\. Replace `argv` with `app.ensure_utf8(argv)` before any arguments are parsed.
|
||||
`ensure_utf8` will do nothing on systems where `argv` is already in UTF-8 (Such
|
||||
as Linux or macOS) and return `argv` unmodified. On Windows, it will discard
|
||||
`argv` and replace it with a correctly decoded array or arguments from win32
|
||||
API.
|
||||
|
||||
```cpp
|
||||
int main(int argc, char** argv) {
|
||||
CLI::App app;
|
||||
argv = app.ensure_utf8(argv); // new argv memory is held by app
|
||||
// ...
|
||||
CLI11_PARSE(app, argc, argv);
|
||||
}
|
||||
```
|
||||
```cpp
|
||||
int main(int argc, char** argv) {
|
||||
CLI::App app;
|
||||
argv = app.ensure_utf8(argv); // new argv memory is held by app
|
||||
// ...
|
||||
CLI11_PARSE(app, argc, argv);
|
||||
}
|
||||
```
|
||||
|
||||
2. If you pass unmodified command-line arguments to CLI11, call `app.parse()`
|
||||
instead of `app.parse(argc, argv)` (or `CLI11_PARSE(app)` instead of
|
||||
`CLI11_PARSE(app, argc, argv)`). The library will find correct arguments by
|
||||
itself.
|
||||
2\. If you pass unmodified command-line arguments to CLI11, call `app.parse()`
|
||||
instead of `app.parse(argc, argv)` (or `CLI11_PARSE(app)` instead of
|
||||
`CLI11_PARSE(app, argc, argv)`). The library will find correct arguments by
|
||||
itself.
|
||||
|
||||
Note: this approach may not work on weird OS configurations, such as when the
|
||||
`/proc` dir is missing on Linux systems (see also
|
||||
[#845](https://github.com/CLIUtils/CLI11/issues/845)).
|
||||
> [!NOTE]
|
||||
>
|
||||
> This approach may not work on weird OS configurations, such as when the
|
||||
> `/proc` dir is missing on Linux systems (see also
|
||||
> [#845](https://github.com/CLIUtils/CLI11/issues/845)).
|
||||
>
|
||||
> ```cpp
|
||||
> int main() {
|
||||
> CLI::App app;
|
||||
> // ...
|
||||
> CLI11_PARSE(app);
|
||||
> }
|
||||
> ```
|
||||
|
||||
```cpp
|
||||
int main() {
|
||||
CLI::App app;
|
||||
// ...
|
||||
CLI11_PARSE(app);
|
||||
}
|
||||
```
|
||||
3\. Get correct arguments with which the program was originally executed using
|
||||
provided functions: `CLI::argc()` and `CLI::argv()`. These three methods are the
|
||||
only cross-platform ways of handling unicode correctly.
|
||||
|
||||
3. Get correct arguments with which the program was originally executed using
|
||||
provided functions: `CLI::argc()` and `CLI::argv()`. These three methods are
|
||||
the only cross-platform ways of handling unicode correctly.
|
||||
|
||||
```cpp
|
||||
int main() {
|
||||
CLI::App app;
|
||||
// ...
|
||||
CLI11_PARSE(app, CLI::argc(), CLI::argv());
|
||||
}
|
||||
```
|
||||
```cpp
|
||||
int main() {
|
||||
CLI::App app;
|
||||
// ...
|
||||
CLI11_PARSE(app, CLI::argc(), CLI::argv());
|
||||
}
|
||||
```
|
||||
|
||||
<details><summary>Bad options (click to expand)</summary><p>
|
||||
|
||||
4. Use the Windows-only non-standard `wmain` function, which accepts
|
||||
`wchar_t *argv[]` instead of `char* argv[]`. Parsing this will allow CLI to
|
||||
convert wide strings to UTF-8 without losing information.
|
||||
4\. Use the Windows-only non-standard `wmain` function, which accepts
|
||||
`wchar_t *argv[]` instead of `char* argv[]`. Parsing this will allow CLI to
|
||||
convert wide strings to UTF-8 without losing information.
|
||||
|
||||
```cpp
|
||||
int wmain(int argc, wchar_t *argv[]) {
|
||||
CLI::App app;
|
||||
// ...
|
||||
CLI11_PARSE(app, argc, argv);
|
||||
}
|
||||
```
|
||||
```cpp
|
||||
int wmain(int argc, wchar_t *argv[]) {
|
||||
CLI::App app;
|
||||
// ...
|
||||
CLI11_PARSE(app, argc, argv);
|
||||
}
|
||||
```
|
||||
|
||||
5. Retrieve arguments yourself by using Windows APIs like
|
||||
[`CommandLineToArgvW`](https://learn.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw)
|
||||
and pass them to CLI. This is what the library is doing under the hood in
|
||||
`CLI::argv()`.
|
||||
5\. Retrieve arguments yourself by using Windows APIs like
|
||||
[`CommandLineToArgvW`](https://learn.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw)
|
||||
and pass them to CLI. This is what the library is doing under the hood in
|
||||
`CLI::argv()`.
|
||||
|
||||
</p></details>
|
||||
</br>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user