From d226a2cd7066063195e97da7db21a6d791f0b024 Mon Sep 17 00:00:00 2001
From: Peter Krempa <pkrempa@redhat.com>
Date: Wed, 13 Mar 2024 22:31:20 +0100
Subject: [PATCH] vsh: Introduce annotation for vsh options which are
 unexpectedly parsed positionally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on the rationale in previous commit, all commands which were
parsed as positional but not documented as such will be annotated with
this flag.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
---
 tools/vsh.c | 12 ++++++++++--
 tools/vsh.h |  7 +++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/tools/vsh.c b/tools/vsh.c
index 96d6a5c238..eeee58d39e 100644
--- a/tools/vsh.c
+++ b/tools/vsh.c
@@ -334,7 +334,8 @@ vshCmddefCheckInternals(vshControl *ctl,
             case VSH_OT_ARGV:
                 if (brokenPositionals == 0 ||
                     brokenPositionals == opt->type) {
-                    if (!(opt->flags & VSH_OFLAG_REQ_OPT) && !opt->positional)
+                    if (!(opt->flags & VSH_OFLAG_REQ_OPT) &&
+                        !(opt->positional || opt->unwanted_positional))
                         virBufferStrcat(&posbuf, opt->name, ", ", NULL);
                 }
                 break;
@@ -363,6 +364,12 @@ vshCmddefCheckInternals(vshControl *ctl,
             return -1;
         }
 
+        if (opt->unwanted_positional && opt->positional) {
+            vshError(ctl, "unwanted_positional flag of argument '%s' of command '%s' must not be used together with positional",
+                     opt->name, cmd->name);
+            return -1;
+        }
+
         switch (opt->type) {
         case VSH_OT_NONE:
             vshError(ctl, "invalid type 'NONE' of option '%s' of command '%s'",
@@ -376,7 +383,7 @@ vshCmddefCheckInternals(vshControl *ctl,
                 return -1;
             }
 
-            if (opt->positional) {
+            if (opt->positional || opt->unwanted_positional) {
                 vshError(ctl, "boolean parameter '%s' of command '%s' must not be positional",
                          opt->name, cmd->name);
                 return -1;
@@ -397,6 +404,7 @@ vshCmddefCheckInternals(vshControl *ctl,
 
             if (opt->required ||
                 opt->positional ||
+                opt->unwanted_positional ||
                 opt->completer ||
                 opt->flags ||
                 !opt->help) {
diff --git a/tools/vsh.h b/tools/vsh.h
index cd833a55fa..fdcc89b12a 100644
--- a/tools/vsh.h
+++ b/tools/vsh.h
@@ -133,6 +133,13 @@ struct _vshCmdOptDef {
     vshCmdOptType type;         /* option type */
     bool required;              /* option is required */
     bool positional;            /* option is a positional option (not requiring '--optionname') */
+
+    /* Historically the command parser in virsh allowed many optional arguments
+     * which were documented as non-positional to be filled positionally. To
+     * preserve this functionality those need to be annotated with the
+     * 'unwanted_positional' flag. New options must not use this flag */
+    bool unwanted_positional;
+
     unsigned int flags;         /* flags */
     const char *help;           /* non-NULL help string; or for VSH_OT_ALIAS
                                  * the name of a later public option */