From 25cca2dcb9cc01948f519db556dd9296de02950a Mon Sep 17 00:00:00 2001
From: Philip Top <phlptp@gmail.com>
Date: Thu, 17 Jun 2021 14:44:19 -0700
Subject: [PATCH] docs: add custom parse example (#603)

---
 README.md                 |  3 ++-
 examples/CMakeLists.txt   |  5 +++++
 examples/custom_parse.cpp | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 examples/custom_parse.cpp

diff --git a/README.md b/README.md
index b6e12b6..ef17b49 100644
--- a/README.md
+++ b/README.md
@@ -799,7 +799,7 @@ Every `add_` option you have seen so far depends on one method that takes a lamb
 
 Other values can be added as long as they support `operator>>` (and defaults can be printed if they support `operator<<`). To add a new type, for example, provide a custom `operator>>` with an `istream` (inside the CLI namespace is fine if you don't want to interfere with an existing `operator>>`).
 
-If you wanted to extend this to support a completely new type, use a lambda or add a specialization of the `lexical_cast` function template in the namespace `CLI::detail` with the type you need to convert to. Some examples of some new parsers for `complex<double>` that support all of the features of a standard `add_options` call are in [one of the tests](./tests/NewParseTest.cpp). A simpler example is shown below:
+If you wanted to extend this to support a completely new type, use a lambda or add a specialization of the `lexical_cast` function template in the namespace of the type you need to convert to. Some examples of some new parsers for `complex<double>` that support all of the features of a standard `add_options` call are in [one of the tests](./tests/NewParseTest.cpp). A simpler example is shown below:
 
 #### Example
 
@@ -871,6 +871,7 @@ The API is [documented here][api-docs]. Also see the [CLI11 tutorial GitBook][gi
 Several short examples of different features are included in the repository. A brief description of each is included here
 
  - [callback_passthrough](https://github.com/CLIUtils/CLI11/blob/master/examples/callback_passthrough.cpp): Example of directly passing remaining arguments through to a callback function which generates a CLI11 application based on existing arguments.
+ - [custom_parse](https://github.com/CLIUtils/CLI11/blob/master/examples/custom_parse.cpp):  Based on [Issue #566](https://github.com/CLIUtils/CLI11/issues/566), example of custom parser
  - [digit_args](https://github.com/CLIUtils/CLI11/blob/master/examples/digit_args.cpp):  Based on [Issue #123](https://github.com/CLIUtils/CLI11/issues/123), uses digit flags to pass a value
  - [enum](https://github.com/CLIUtils/CLI11/blob/master/examples/enum.cpp):  Using enumerations in an option, and the use of [CheckedTransformer](#transforming-validators)
  - [enum_ostream](https://github.com/CLIUtils/CLI11/blob/master/examples/enum_ostream.cpp):  In addition to the contents of example enum.cpp, this example shows how a custom ostream operator overrides CLI11's enum streaming.
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index aee80f8..d0d45c6 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -242,3 +242,8 @@ set_property(TEST retired_retired_test2 PROPERTY PASS_REGULAR_EXPRESSION "WARNIN
 set_property(TEST retired_retired_test3 PROPERTY PASS_REGULAR_EXPRESSION "WARNING.*retired")
 
 set_property(TEST retired_deprecated PROPERTY PASS_REGULAR_EXPRESSION "deprecated.*not_deprecated")
+
+#--------------------------------------------
+add_cli_exe(custom_parse custom_parse.cpp)
+add_test(NAME cp_test COMMAND custom_parse --dv 1.7)
+set_property(TEST cp_test PROPERTY PASS_REGULAR_EXPRESSION "called correct")
diff --git a/examples/custom_parse.cpp b/examples/custom_parse.cpp
new file mode 100644
index 0000000..a14d7bd
--- /dev/null
+++ b/examples/custom_parse.cpp
@@ -0,0 +1,39 @@
+// Copyright (c) 2017-2020, University of Cincinnati, developed by Henry Schreiner
+// under NSF AWARD 1414736 and by the respective contributors.
+// All rights reserved.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+
+// from Issue #566 on github https://github.com/CLIUtils/CLI11/issues/566
+
+#include <CLI/CLI.hpp>
+#include <iostream>
+#include <sstream>
+
+// example file to demonstrate a custom lexical cast function
+
+template <class T = int> struct Values {
+    T a;
+    T b;
+    T c;
+};
+
+// in C++20 this is constructible from a double due to the new aggregate initialization in C++20.
+using DoubleValues = Values<double>;
+
+// the lexical cast operator should be in the same namespace as the type for ADL to work properly
+bool lexical_cast(const std::string &input, Values<double> &v) {
+    std::cout << "called correct lexical_cast function ! val: " << input << std::endl;
+    return true;
+}
+
+DoubleValues doubles;
+void argparse(CLI::Option_group *group) { group->add_option("--dv", doubles)->default_str("0"); }
+
+int main(int argc, char **argv) {
+    CLI::App app;
+
+    argparse(app.add_option_group("param"));
+    CLI11_PARSE(app, argc, argv);
+    return 0;
+}
--
libgit2 0.21.4