CLOUDP-138375: [cobra2snooty] better arg detection (#21)

Author: gssbzn

cobra2snooty_test.go

@@ -1,3 +1,17 @@
+// Copyright 2022 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package cobra2snooty
 
 import (
@@ -53,14 +67,12 @@ func Echo() *cobra.Command {
 		return echoCmd
 	}
 	echoCmd = &cobra.Command{
-		Use:     "echo <string to echo> [test param]",
+		Use:     "echo <string to print> [test param]",
 		Aliases: []string{"say"},
 		Short:   "Echo anything to the screen",
 		Long:    "an utterly useless command for testing",
 		Example: "Just run root echo",
 		Annotations: map[string]string{
-			"args":                "string to print, test param",
-			"requiredArgs":        "string to print",
 			"string to printDesc": "A string to print",
 			"test paramDesc":      "just for testing",
 		},
@@ -108,7 +120,7 @@ var deprecatedCmd = &cobra.Command{
 }
 
 func TestGenDocs(t *testing.T) {
-	// We generate on a subcommand so we have both subcommands and parents
+	// We generate on a subcommand, so we have both subcommands and parents
 	buf := new(bytes.Buffer)
 	Root() // init root
 	if err := GenDocs(Echo(), buf); err != nil {
@@ -166,7 +178,13 @@ func TestGenDocsNoTag(t *testing.T) {
 }
 
 func TestGenTreeDocs(t *testing.T) {
-	c := &cobra.Command{Use: "do [OPTIONS] arg1 arg2"}
+	c := &cobra.Command{
+		Use: "do <arg1> [arg2]",
+		Annotations: map[string]string{
+			"arg1Desc": "desc",
+			"arg2Desc": "desc",
+		},
+	}
 
 	tmpdir, err := ioutil.TempDir("", "test-gen-rst-tree")
 	if err != nil {
@@ -212,3 +230,48 @@ func checkStringOmits(t *testing.T, got, expected string) {
 		t.Errorf("Expected to not contain: \n %v\nGot: %v", expected, got)
 	}
 }
+
+func TestArgsRegex(t *testing.T) {
+	t.Run("simple", func(t *testing.T) {
+		result := argsRegex.FindAllString("<arg1> [arg2]", -1)
+		expected := []string{"<arg1>", "[arg2]"}
+		for i := range result {
+			if result[i] != expected[i] {
+				t.Fatalf("expected: %s, got: %s\n", expected[i], result[i])
+			}
+		}
+	})
+	t.Run("with spaces", func(t *testing.T) {
+		result := argsRegex.FindAllString("<this arg1> [that arg2]", -1)
+		expected := []string{"<this arg1>", "[that arg2]"}
+		for i := range result {
+			if result[i] != expected[i] {
+				t.Fatalf("expected: %s, got: %s\n", expected[i], result[i])
+			}
+		}
+	})
+	t.Run("repeating", func(t *testing.T) {
+		result := argsRegex.FindAllString("<arg1>... [arg2]...", -1)
+		expected := []string{"<arg1>", "[arg2]"}
+		for i := range result {
+			if result[i] != expected[i] {
+				t.Fatalf("expected: %s, got: %s\n", expected[i], result[i])
+			}
+		}
+	})
+	t.Run("empty", func(t *testing.T) {
+		result := argsRegex.FindAllString("<> []", -1)
+		if len(result) != 0 {
+			t.Fatalf("expected no matches\n")
+		}
+	})
+	t.Run("complex", func(t *testing.T) {
+		result := argsRegex.FindAllString("<this arg1> <that arg2> [optional] [long option]", -1)
+		expected := []string{"<this arg1>", "<that arg2>", "[optional]", "[long option]"}
+		for i := range result {
+			if result[i] != expected[i] {
+				t.Fatalf("expected: %s, got: %s\n", expected[i], result[i])
+			}
+		}
+	})
+}

options.go

@@ -1,9 +1,24 @@
+// Copyright 2022 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package cobra2snooty
 
 import (
 	"bytes"
 	"errors"
 	"fmt"
+	"regexp"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -19,30 +34,31 @@ const optionsHeader = `.. list-table::
      - Description
 `
 
-var ErrMissingDescription = errors.New("missing description")
+var (
+	ErrMissingDescription = errors.New("missing description")
+	argsRegex             = regexp.MustCompile(`<[^>]+>|\[[^]]+]`)
+)
 
 func printArgs(buf *bytes.Buffer, cmd *cobra.Command) error {
-	if args, ok := cmd.Annotations["args"]; ok {
-		buf.WriteString("Arguments\n")
-		buf.WriteString("---------\n\n")
-		buf.WriteString(optionsHeader)
-		var requiredSlice []string
-		if requiredArgs, hasRequired := cmd.Annotations["requiredArgs"]; hasRequired {
-			requiredSlice = strings.Split(requiredArgs, ",")
-		}
-
-		for _, arg := range strings.Split(args, ",") {
-			trimmedArg := strings.TrimSpace(arg)
-			required := stringInSlice(requiredSlice, trimmedArg)
-			if description, hasDescription := cmd.Annotations[trimmedArg+"Desc"]; hasDescription {
-				line := fmt.Sprintf("   * - %s\n     - string\n     - %v\n     - %s\n", trimmedArg, required, description)
-				buf.WriteString(line)
-			} else {
-				return fmt.Errorf("%w: %s - %s", ErrMissingDescription, cmd.Use, trimmedArg)
-			}
+	u := argsRegex.FindAllString(cmd.Use, -1)
+	if len(u) == 0 {
+		return nil
+	}
+	buf.WriteString("Arguments\n")
+	buf.WriteString("---------\n\n")
+	buf.WriteString(optionsHeader)
+	for _, a := range u {
+		value := a[1 : len(a)-1]
+		if description, hasDescription := cmd.Annotations[value+"Desc"]; hasDescription {
+			required := strings.HasPrefix(a, "<")
+			line := fmt.Sprintf("   * - %s\n     - string\n     - %v\n     - %s\n", value, required, description)
+			buf.WriteString(line)
+		} else {
+			return fmt.Errorf("%w: %s - %s", ErrMissingDescription, cmd.CommandPath(), value)
 		}
-		buf.WriteString("\n")
 	}
+	buf.WriteString("\n")
+
 	return nil
 }
 

strings.go

@@ -1,3 +1,17 @@
+// Copyright 2022 MongoDB Inc
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package cobra2snooty
 
 // adapted from: https://github.com/kr/text/blob/main/indent.go
@@ -15,12 +29,3 @@ func indentString(s, p string) string {
 	}
 	return string(res)
 }
-
-func stringInSlice(a []string, x string) bool {
-	for _, b := range a {
-		if b == x {
-			return true
-		}
-	}
-	return false
-}