[main] optparse: add support for prefix flags

Author: silverweed

main/src/optparse.hxx

@@ -37,28 +37,50 @@
 /// ~~~
 ///
 /// ## Additional Notes
-/// If all the short flags you pass (those starting with a single `-`) are 1 character long, the parser will accept
-/// grouped flags like "-abc" as equivalent to "-a -b -c". The last flag in the group may also accept an argument, in
-/// which case "-abc foo" will count as "-a -b -c foo" where "foo" is the argument to "-c".
 ///
-/// Multiple repeated flags, like `-vvv`, are supported but must explicitly be marked as such:
+/// ### Flag grouping
+/// By default, if all the short flags you pass (those starting with a single `-`) are 1 character long, the parser will
+/// accept grouped flags like "-abc" as equivalent to "-a -b -c". The last flag in the group may also accept an
+/// argument, in which case "-abc foo" will count as "-a -b -c foo" where "foo" is the argument to "-c". If you want to
+/// disable flag grouping, use:
+///
+/// ~~~{.cpp}
+/// ROOT::RCmdLineOpts opts({ EFlagTreatment::kSimple });
+/// ~~~
+///
+/// ### Repeated flags
+/// Multiple repeated flags, like `-vvv`, are supported but must explicitly be marked as such on a per-flag basis:
 /// ~~~{.cpp}
 /// opts.AddFlag({"-v"}, RCmdLineOpts::EFlagType::kSwitch, "", RCmdLineOpts::kFlagAllowMultiple);
 /// ~~~
 /// This works both for switches and flags with arguments. `GetSwitch` returns the number of times a specific flag
 /// appeared; for flags with arguments `GetFlagValues` and `GetFlagValuesAs<T>` can be used to access the values as
 /// vectors.
 ///
+/// ### Positional argument separator
 /// The string "--" is treated as the positional argument separator: all strings after it will be treated as positional
 /// arguments even if they start with "-".
 ///
+/// ## Prefix flags (aka no space between flag and argument)
+/// If you need your flags to support the syntax "-fXYZ" where "-f" is your flag and "XYZ" its argument, you can enable
+/// that per-flag by using `RCmdLineOpts::kFlagPrefixArg`:
+///
+/// ~~~{.cpp}
+/// opts.AddFlag({"-I", "--include"}, RCmdLineOpts::EFlagType::kWithArg, RCmdLineOpts::kFlagPrefixArg });
+/// ~~~
+///
+/// (see EFlagTreatment for more details). This will **disable** flag grouping globally, but allows the parser to
+/// interpret flags and arguments that are not separated by spaces.
+/// Note that this only makes sense for flags with arguments.
+///
 /// \author Giacomo Parolini <giacomo.parolini@cern.ch>
 /// \date 2025-10-09
 
 #ifndef ROOT_OptParse
 #define ROOT_OptParse
 
 #include <algorithm>
+#include <cassert>
 #include <charconv>
 #include <cstring>
 #include <cstdint>
@@ -75,6 +97,22 @@ namespace ROOT {
 
 class RCmdLineOpts {
 public:
+   enum class EFlagTreatment {
+      /// Will result to kGrouped if you don't define any short flag longer than 1 character, otherwise kSimple.
+      kDefault,
+      /// `-abc` will always be treated as the single flag "-abc"
+      kSimple,
+      /// `-abc` will be treated as "-a -b -c". This is only valid for short flags.
+      /// With this setting you cannot define short flags that are more than 1 character long nor ones that are marked
+      /// with kFlagPrefixArg.
+      kGrouped,
+   };
+
+   struct RSettings {
+      /// Affects how flags are parsed (\see EFlagTreatment).
+      EFlagTreatment fFlagTreatment;
+   };
+
    enum class EFlagType {
       kSwitch,
       kWithArg
@@ -90,15 +128,15 @@ public:
    enum EFlagOpt {
       /// Flag is allowed to appear multiple times (default: it's an error to see the same flag twice)
       kFlagAllowMultiple = 1 << 0,
+      /// Flag argument can appear right after this flag without a space or equal sign in between.
+      /// Note that marking any short flag with this disables flag grouping!
+      kFlagPrefixArg = 1 << 1,
    };
 
 private:
+   RSettings fSettings;
    std::vector<RFlag> fFlags;
    std::vector<std::string> fArgs;
-   // If true, many short flags may be grouped: "-abc" == "-a -b -c".
-   // This is automatically true if all short flags given are 1 character long, otherwise it's false.
-   // (a short flag is a flag with a single `-` as its prefix).
-   bool fAllowFlagGrouping = true;
 
    struct RExpectedFlag {
       EFlagType fFlagType = EFlagType::kSwitch;
@@ -116,14 +154,27 @@ private:
 
    const RExpectedFlag *GetExpectedFlag(std::string_view name) const
    {
+      const auto StartsWith = [](std::string_view string, std::string_view prefix) {
+         return string.size() >= prefix.size() && string.substr(0, prefix.size()) == prefix;
+      };
+
       for (const auto &flag : fExpectedFlags) {
-         if (flag.fName == name)
+         if (flag.fOpts & kFlagPrefixArg) {
+            if (StartsWith(name, flag.fName)) {
+               // NOTE: we can't have ambiguities here because we make sure that no flags share a common prefix in
+               // AddFlag().
+               return &flag;
+            }
+         } else if (flag.fName == name) {
             return &flag;
+         }
       }
       return nullptr;
    }
 
 public:
+   explicit RCmdLineOpts(RSettings settings = {EFlagTreatment::kDefault}) : fSettings(settings) {}
+
    /// Returns all parsing errors
    const std::vector<std::string> &GetErrors() const { return fErrors; }
    /// Retrieves all positional arguments
@@ -142,6 +193,7 @@ public:
 
    /// Defines a new flag (either a switch or a flag with argument).
    /// The flag may be referred to as any of the values inside `aliases` (e.g. { "-h", "--help" }).
+   /// You must pass at least 1 string inside `aliases`.
    /// All strings inside `aliases` must start with `-` or `--` and be at least 1 character long (aside the dashes).
    /// Flags starting with a single `-` are considered "short", regardless of their actual length.
    /// If all short flags are 1 character long, they may be collapsed into one and parsed as individual flags
@@ -155,6 +207,17 @@ public:
    void AddFlag(std::initializer_list<std::string_view> aliases, EFlagType type = EFlagType::kSwitch,
                 std::string_view help = "", std::uint32_t flagOpts = 0)
    {
+      const auto IsPrefixOf = [](std::string_view a, std::string_view b) {
+         return a.size() < b.size() && std::equal(a.begin(), a.end(), b.begin());
+      };
+
+      if (aliases.size() == 0)
+         throw std::invalid_argument("AddFlag must receive at least 1 name for the flag!");
+
+      if ((flagOpts & kFlagPrefixArg) && type != EFlagType::kWithArg)
+         throw std::invalid_argument("Flag `" + std::string(*aliases.begin()) +
+                                     "` has option kFlagPrefixArg but it's a Switch, so the option makes no sense.");
+
       int aliasIdx = -1;
       for (auto f : aliases) {
          auto prefixLen = f.find_first_not_of('-');
@@ -164,11 +227,43 @@ public:
          if (f.size() == prefixLen)
             throw std::invalid_argument("Flag name cannot be empty");
 
-         fAllowFlagGrouping = fAllowFlagGrouping && (prefixLen > 1 || f.size() == 2);
+         auto flagName = f.substr(prefixLen);
+
+         // Check that we're not introducing ambiguities with prefix flags. While we're at it, also check that none
+         // of the given aliases were already added.
+         for (const auto &expFlag : fExpectedFlags) {
+            // NOTE: we're checking against the full string, not just the flag name, to allow cases like:
+            // AddFlag({"-foo", "--foo"}).
+            if (expFlag.AsStr() == f)
+               throw std::invalid_argument("Flag `" + expFlag.AsStr() + "` was added multiple times.");
+
+            if (!(flagOpts & kFlagPrefixArg) && !(expFlag.fOpts & kFlagPrefixArg))
+               continue;
+
+            // At least one of expFlag and f is a prefix flag: this means that they must not share a common prefix.
+            if (((expFlag.fOpts & kFlagPrefixArg) && IsPrefixOf(expFlag.fName, flagName)) ||
+                ((flagOpts & kFlagPrefixArg) && IsPrefixOf(flagName, expFlag.fName))) {
+               throw std::invalid_argument("Flags `" + expFlag.AsStr() + "` and `" + std::string(f) +
+                                           "` have a common prefix. This causes ambiguity because at least one of them "
+                                           "is marked with kFlagPrefixArg.");
+            }
+         }
+
+         bool disallowsGrouping = (prefixLen == 1 && (f.size() > 2 || (flagOpts & kFlagPrefixArg)));
+         if (disallowsGrouping) {
+            if (fSettings.fFlagTreatment == EFlagTreatment::kDefault) {
+               fSettings.fFlagTreatment = EFlagTreatment::kSimple;
+            } else if (fSettings.fFlagTreatment == EFlagTreatment::kGrouped) {
+               throw std::invalid_argument(
+                  std::string("Flags starting with a single dash must be 1 character long when `FlagTreatment == "
+                              "EFlagTreatment::kGrouped'! Cannot accept given flag `") +
+                  std::string(f) + "`");
+            }
+         }
 
          RExpectedFlag expected;
          expected.fFlagType = type;
-         expected.fName = f.substr(prefixLen);
+         expected.fName = flagName;
          expected.fHelp = help;
          expected.fAlias = aliasIdx;
          expected.fShort = prefixLen == 1;
@@ -218,8 +313,7 @@ public:
       if (!exp)
          throw std::invalid_argument(std::string("Flag `") + std::string(name) + "` is not expected");
       if (exp->fFlagType != EFlagType::kWithArg)
-         throw std::invalid_argument(std::string("Flag `") + std::string(name) +
-                                     "` is a switch, use GetSwitch()");
+         throw std::invalid_argument(std::string("Flag `") + std::string(name) + "` is a switch, use GetSwitch()");
 
       std::string_view lookedUpName = name;
       if (exp->fAlias >= 0)
@@ -312,6 +406,11 @@ public:
    {
       bool forcePositional = false;
 
+      // If flag treatment is still Default by now it means we can safely group short flags (otherwise we'd have
+      // already changed it to Simple).
+      if (fSettings.fFlagTreatment == EFlagTreatment::kDefault)
+         fSettings.fFlagTreatment = EFlagTreatment::kGrouped;
+
       // Contains one or more flags coming from one of the arguments (e.g. "-abc" may be split
       // into flags "a", "b", and "c", which will be stored in `argStr`).
       std::vector<std::string_view> argStr;
@@ -336,6 +435,7 @@ public:
             // refers only to the last one).
             argStr.clear();
             std::string_view nxtArgStr;
+            // If this is false `nxtArgStr` *must* refer to the next arg, otherwise it might or might not be.
             bool nxtArgIsTentative = true;
             if (arg[0] == '-') {
                // long flag
@@ -356,7 +456,7 @@ public:
                // short flag.
                // If flag grouping is active, all flags except the last one will have an implicitly empty argument.
                auto argLen = strlen(arg);
-               while (fAllowFlagGrouping && argLen > 1) {
+               while (fSettings.fFlagTreatment == EFlagTreatment::kGrouped && argLen > 1) {
                   argStr.push_back(std::string_view{arg, 1});
                   ++arg, --argLen;
                }
@@ -370,20 +470,41 @@ public:
 
             for (auto j = 0u; j < argStr.size(); ++j) {
                std::string_view argS = argStr[j];
+
                const auto *exp = GetExpectedFlag(argS);
                if (!exp) {
                   fErrors.push_back(std::string("Unknown flag: ") + argOrig);
                   break;
                }
 
+               // In Prefix mode, check if the returned expected flag is shorter than `argS`. This can mean two things:
+               // - if `nxtArgIsTentative == false` then this flag was followed by an equal sign, and in that case
+               //   the intention is interpreted as "I want this flag's argument to be whatever follows the equal sign",
+               //   which means we treat this as an unknown flag;
+               // - otherwise, we use the rest of `argS` as the argument to the flag.
+               // More concretely: if the user added flag "-D" and argS is "-Dfoo=bar", we parse it as
+               // {flag: "-Dfoo", arg: "bar"}, rather than {flag: "-D", arg: "foo=bar"}.
+               if ((exp->fOpts & kFlagPrefixArg) && argS.size() > exp->fName.size()) {
+                  if (nxtArgIsTentative) {
+                     i -= !nxtArgStr.empty(); // if we had already picked a candidate next arg, undo that.
+                     nxtArgStr = argS.substr(exp->fName.size());
+                     nxtArgIsTentative = false;
+                  } else {
+                     fErrors.push_back(std::string("Unknown flag: ") + argOrig);
+                     break;
+                  }
+               } else {
+                  assert(exp->fName.size() == argS.size());
+               }
+
                std::string_view nxtArg = (j == argStr.size() - 1) ? nxtArgStr : "";
 
                RCmdLineOpts::RFlag flag;
                flag.fHelp = exp->fHelp;
                // If the flag is an alias (e.g. long version of a short one), save its name as the aliased one, so we
                // can fetch the value later by using any of the aliases.
                if (exp->fAlias < 0)
-                  flag.fName = argS;
+                  flag.fName = exp->fName;
                else
                   flag.fName = fExpectedFlags[exp->fAlias].fName;