Add method for parsing args with customizable behavior

application/argumentparser.cpp

@@ -721,11 +721,7 @@ void ArgumentParser::printHelp(ostream &os) const
  */
 void ArgumentParser::parseArgs(int argc, const char *const *argv)
 {
-    readArgs(argc, argv);
-    if (argc) {
-        checkConstraints(m_mainArgs);
-        invokeCallbacks(m_mainArgs);
-    }
+    parseArgsExt(argc, argv, ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks);
 }
 
 /*!
@@ -734,15 +730,51 @@ void ArgumentParser::parseArgs(int argc, const char *const *argv)
  *          case. Instead, it will print an error message and terminate the application with exit
  *          code 1.
  * \sa parseArgs(), readArgs()
+ * \deprecated In next major release, this method will be removed. parseArgs() can serve the same
+ *             purpose then.
  */
 void ArgumentParser::parseArgsOrExit(int argc, const char *const *argv)
+{
+    parseArgsExt(argc, argv);
+}
+
+/*!
+ * \brief Parses the specified command line arguments.
+ *
+ * The behavior is configurable by specifying the \a behavior argument. See ParseArgumentBehavior for
+ * the options. By default, all options are present.
+ *
+ * \remarks
+ *  - The results are stored in the Argument instances assigned as main arguments and sub arguments.
+ *  - This method will not return in the error case if the ParseArgumentBehavior::ExitOnFailure is present
+ *    (default).
+ *  - This method will not return in case shell completion is requested. This behavior can be altered
+ *    by overriding ApplicationUtilities::exitFunction which defaults to &std::exit.
+ * \throws Throws Failure if the specified arguments are invalid and the ParseArgumentBehavior::ExitOnFailure
+ *         flag is not present.
+ * \sa parseArgs(), readArgs(), parseArgsOrExit()
+ * \deprecated In next major release, this method will be available as parseArgs().
+ */
+void ArgumentParser::parseArgsExt(int argc, const char *const *argv, ParseArgumentBehavior behavior)
 {
     try {
-        parseArgs(argc, argv);
+        readArgs(argc, argv);
+        if (!argc) {
+            return;
+        }
+        if (behavior & ParseArgumentBehavior::CheckConstraints) {
+            checkConstraints(m_mainArgs);
+        }
+        if (behavior & ParseArgumentBehavior::InvokeCallbacks) {
+            invokeCallbacks(m_mainArgs);
+        }
     } catch (const Failure &failure) {
-        CMD_UTILS_START_CONSOLE;
-        cerr << failure;
-        exit(1);
+        if (behavior & ParseArgumentBehavior::ExitOnFailure) {
+            CMD_UTILS_START_CONSOLE;
+            cerr << failure;
+            exit(1);
+        }
+        throw;
     }
 }
 
@@ -756,6 +788,8 @@ void ArgumentParser::parseArgsOrExit(int argc, const char *const *argv)
  *    by overriding ApplicationUtilities::exitFunction which defaults to &std::exit.
  * \throws Throws Failure if the specified arguments are invalid.
  * \sa parseArgs(), parseArgsOrExit()
+ * \deprecated In next major release, this method will be private. parseArgs() can serve the same
+ *             purpose then.
  */
 void ArgumentParser::readArgs(int argc, const char *const *argv)
 {

application/argumentparser.h

@@ -65,6 +65,32 @@ enum class UnknownArgumentBehavior {
     Fail /**< Further parsing is aborted and an ApplicationUtilities::Failure instance with an error message is thrown. */
 };
 
+/*!
+ * \brief The ParseArgumentBehavior enum specifies the behavior when parsing arguments.
+ *
+ * This concerns checking constraints, invoking callbacks and handling failures. The values are supposed to be combined
+ * using the |-operator. Note that ParseArgumentBehavior::ReadArguments is always implied.
+ */
+enum class ParseArgumentBehavior {
+    ReadArguments = 0x0, /**< reads the specified CLI arguments, equivalent to simply calling readArgs() */
+    CheckConstraints = 0x1, /**< whether the constraints should be checked after reading the arguments */
+    InvokeCallbacks = 0x2, /**< whether the callbacks should be invoked after reading the arguments and (maybe) checking the constraints */
+    ExitOnFailure
+    = 0x4, /**< whether the parser should print an error message and terminate the application on failure (rather than throwing an exception) */
+};
+
+/// \cond
+constexpr ParseArgumentBehavior operator|(ParseArgumentBehavior lhs, ParseArgumentBehavior rhs)
+{
+    return static_cast<ParseArgumentBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
+}
+
+constexpr bool operator&(ParseArgumentBehavior lhs, ParseArgumentBehavior rhs)
+{
+    return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
+}
+/// \endcond
+
 /*!
  * \brief The ValueCompletionBehavior enum specifies the items to be considered when generating completion for an argument value.
  * \remarks
@@ -254,6 +280,9 @@ public:
     void printHelp(std::ostream &os) const;
     void parseArgs(int argc, const char *const *argv);
     void parseArgsOrExit(int argc, const char *const *argv);
+    void parseArgsExt(int argc, const char *const *argv,
+        ParseArgumentBehavior behavior
+        = ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks | ParseArgumentBehavior::ExitOnFailure);
     void readArgs(int argc, const char *const *argv);
     void resetArgs();
     unsigned int actualArgumentCount() const;