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
21 changes: 11 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,6 @@ this:
```cpp
int main(int argc, char** argv) {
CLI::App app{"App description"};
argv = app.ensure_utf8(argv);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this removed? This is by far the best way to do this - parse() / parse_from_cli_args() does black magic on some operating systems, while this reliably works everywhere.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this section of the documentation it is covering the most basic application, in a vast majority of applications this is not necessary. I can add it back if you think it valuable, but to me it creates a lot of potentially unnecessary questions when just getting started.


std::string filename = "default";
app.add_option("-f,--file", filename, "A help string");
Expand All @@ -206,9 +205,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 unicode and operations with CLI11 see
[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>

Expand Down Expand Up @@ -1413,7 +1411,7 @@ app.add_option("--fancy-count", [](std::vector<std::string> val){

### Unicode support

CLI11 supports Unicode and wide strings as defined in the
🆕 CLI11 supports Unicode and wide strings as defined in the
[UTF-8 Everywhere](http://utf8everywhere.org/) manifesto. In particular:

- The library can parse a wide version of command-line arguments on Windows,
Expand Down Expand Up @@ -1445,10 +1443,9 @@ int main(int argc, char** 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_from_cli_args()` instead of `app.parse(argc, argv)`. The library will
find correct arguments by itself, through OS calls and operations.

> [!NOTE]
>
Expand All @@ -1460,7 +1457,11 @@ itself.
> int main() {
> CLI::App app;
> // ...
> CLI11_PARSE(app);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point of CLI11_PARSE(one arg) was to make this simpler to type, encouraging people to support unicode. This makes this "short" but magical method four lines long instead! It would better to just use the more reliable and safe method then (argv = app.ensure_utf8(argv);), which is only one line longer.

> try{
> app.parse_from_cli_args();
> catch (const CLI::ParseError &e) {
> return app.exit(e);
> }
> }
> ```

Expand Down
5 changes: 3 additions & 2 deletions include/CLI/App.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -849,8 +849,9 @@ class App {
void clear();

/// Parse the command-line arguments passed to the main function of the executable.
/// This overload will correctly parse unicode arguments on Windows.
void parse();
/// This method will extract the arguments given to the main from the command line and parse them
/// It will correctly support unicode wide string arguments on Windows
void parse_from_cli_args();

/// Parses the command line - throws errors.
/// This must be called after the options are in but before the rest of the program.
Expand Down
2 changes: 1 addition & 1 deletion include/CLI/impl/App_inl.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -529,7 +529,7 @@ CLI11_INLINE void App::clear() {
}
}

CLI11_INLINE void App::parse() { parse(argc(), argv()); } // LCOV_EXCL_LINE
CLI11_INLINE void App::parse_from_cli_args() { parse(argc(), argv()); } // LCOV_EXCL_LINE

CLI11_INLINE void App::parse(int argc, const char *const *argv) { parse_char_t(argc, argv); }
CLI11_INLINE void App::parse(int argc, const wchar_t *const *argv) { parse_char_t(argc, argv); }
Expand Down