Merge pull request juju#18496 from hpidcock/intern-cmd

juju#18496

In an effort to improve commands and their documentation in Juju, interning juju/cmd will allow the project to have critical documentation generation in tree.

## QA steps

Build and test some juju commands.

Author: jujubot

go.mod

@@ -25,8 +25,8 @@ require (
 	github.com/bmizerany/pat v0.0.0-20210406213842-e4b6760bdd6f
 	github.com/canonical/go-dqlite v1.21.0
 	github.com/canonical/lxd v0.0.0-20231214113525-e676fc63c50a
-	github.com/canonical/sqlair v0.0.0-20240417091145-13970327005b
 	github.com/canonical/pebble v1.17.0
+	github.com/canonical/sqlair v0.0.0-20240417091145-13970327005b
 	github.com/chzyer/readline v1.5.1
 	github.com/coreos/go-systemd/v22 v22.5.0
 	github.com/docker/distribution v2.8.3+incompatible

internal/cmd/aliasfile.go

@@ -0,0 +1,53 @@
+// Copyright 2015 Canonical Ltd.
+// Licensed under the LGPLv3, see LICENSE file for details.
+
+package cmd
+
+import (
+	"io/ioutil"
+	"strings"
+)
+
+// ParseAliasFile will read the specified file and convert
+// the content to a map of names to the command line arguments
+// they relate to.  The function will always return a valid map, even
+// if it is empty.
+func ParseAliasFile(aliasFilename string) map[string][]string {
+	result := map[string][]string{}
+	if aliasFilename == "" {
+		return result
+	}
+
+	content, err := ioutil.ReadFile(aliasFilename)
+	if err != nil {
+		logger.Tracef("unable to read alias file %q: %s", aliasFilename, err)
+		return result
+	}
+
+	lines := strings.Split(string(content), "\n")
+	for i, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			// skip blank lines and comments
+			continue
+		}
+		parts := strings.SplitN(line, "=", 2)
+		if len(parts) != 2 {
+			logger.Warningf("line %d bad in alias file: %s", i+1, line)
+			continue
+		}
+		name, value := strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1])
+		if name == "" {
+			logger.Warningf("line %d missing alias name in alias file: %s", i+1, line)
+			continue
+		}
+		if value == "" {
+			logger.Warningf("line %d missing alias value in alias file: %s", i+1, line)
+			continue
+		}
+
+		logger.Tracef("setting alias %q=%q", name, value)
+		result[name] = strings.Fields(value)
+	}
+	return result
+}

internal/cmd/aliasfile_test.go

@@ -0,0 +1,58 @@
+// Copyright 2015 Canonical Ltd.
+// Licensed under the LGPLv3, see LICENSE file for details.
+
+package cmd_test
+
+import (
+	_ "fmt"
+	"io/ioutil"
+	"path/filepath"
+
+	"github.com/juju/testing"
+	gc "gopkg.in/check.v1"
+
+	"github.com/juju/juju/internal/cmd"
+)
+
+type ParseAliasFileSuite struct {
+	testing.LoggingSuite
+}
+
+var _ = gc.Suite(&ParseAliasFileSuite{})
+
+func (*ParseAliasFileSuite) TestMissing(c *gc.C) {
+	dir := c.MkDir()
+	filename := filepath.Join(dir, "missing")
+	aliases := cmd.ParseAliasFile(filename)
+	c.Assert(aliases, gc.NotNil)
+	c.Assert(aliases, gc.HasLen, 0)
+}
+
+func (*ParseAliasFileSuite) TestParse(c *gc.C) {
+	dir := c.MkDir()
+	filename := filepath.Join(dir, "missing")
+	content := `
+# comments skipped, as are the blank lines, such as the line
+# at the start of this file
+   foo =  trailing-space    
+repeat = first
+flags = flags  --with   flag
+
+# if the same alias name is used more than once, last one wins
+repeat = second
+
+# badly formated values are logged, but skipped
+no equals sign
+=
+key = 
+= value
+`
+	err := ioutil.WriteFile(filename, []byte(content), 0644)
+	c.Assert(err, gc.IsNil)
+	aliases := cmd.ParseAliasFile(filename)
+	c.Assert(aliases, gc.DeepEquals, map[string][]string{
+		"foo":    {"trailing-space"},
+		"repeat": {"second"},
+		"flags":  {"flags", "--with", "flag"},
+	})
+}

internal/cmd/args.go

@@ -0,0 +1,59 @@
+// Copyright 2013 Canonical Ltd.
+// Licensed under the LGPLv3, see LICENSE file for details.
+
+package cmd
+
+import (
+	"strings"
+
+	"github.com/juju/gnuflag"
+)
+
+// StringsValue implements gnuflag.Value for a comma separated list of
+// strings.  This allows flags to be created where the target is []string, and
+// the caller is after comma separated values.
+type StringsValue []string
+
+var _ gnuflag.Value = (*StringsValue)(nil)
+
+// NewStringsValue is used to create the type passed into the gnuflag.FlagSet Var function.
+// f.Var(cmd.NewStringsValue(defaultValue, &someMember), "name", "help")
+func NewStringsValue(defaultValue []string, target *[]string) *StringsValue {
+	value := (*StringsValue)(target)
+	*value = defaultValue
+	return value
+}
+
+// Implements gnuflag.Value Set.
+func (v *StringsValue) Set(s string) error {
+	*v = strings.Split(s, ",")
+	return nil
+}
+
+// Implements gnuflag.Value String.
+func (v *StringsValue) String() string {
+	return strings.Join(*v, ",")
+}
+
+// AppendStringsValue implements gnuflag.Value for a value that can be set
+// multiple times, and it appends each value to the slice.
+type AppendStringsValue []string
+
+var _ gnuflag.Value = (*AppendStringsValue)(nil)
+
+// NewAppendStringsValue is used to create the type passed into the gnuflag.FlagSet Var function.
+// f.Var(cmd.NewAppendStringsValue(&someMember), "name", "help")
+func NewAppendStringsValue(target *[]string) *AppendStringsValue {
+	return (*AppendStringsValue)(target)
+}
+
+// Implements gnuflag.Value Set.
+func (v *AppendStringsValue) Set(s string) error {
+	*v = append(*v, s)
+	return nil
+}
+
+// Implements gnuflag.Value String.
+func (v *AppendStringsValue) String() string {
+	return strings.Join(*v, ",")
+}

internal/cmd/args_test.go

@@ -0,0 +1,174 @@
+// Copyright 2013 Canonical Ltd.
+// Licensed under the LGPLv3, see LICENSE file for details.
+
+package cmd_test
+
+import (
+	"fmt"
+	"io/ioutil"
+
+	"github.com/juju/gnuflag"
+	"github.com/juju/testing"
+	gc "gopkg.in/check.v1"
+
+	"github.com/juju/juju/internal/cmd"
+)
+
+type ArgsSuite struct {
+	testing.LoggingSuite
+}
+
+var _ = gc.Suite(&ArgsSuite{})
+
+func (*ArgsSuite) TestFlagsUsage(c *gc.C) {
+	for i, test := range []struct {
+		message       string
+		defaultValue  []string
+		args          []string
+		expectedValue []string
+	}{{
+		message: "nil default and no arg",
+	}, {
+		message:       "default value and not set by args",
+		defaultValue:  []string{"foo", "bar"},
+		expectedValue: []string{"foo", "bar"},
+	}, {
+		message:       "no value set by args",
+		args:          []string{"--value", "foo,bar"},
+		expectedValue: []string{"foo", "bar"},
+	}, {
+		message:       "default value and set by args",
+		defaultValue:  []string{"omg"},
+		args:          []string{"--value", "foo,bar"},
+		expectedValue: []string{"foo", "bar"},
+	}} {
+		c.Log(fmt.Sprintf("%v: %s", i, test.message))
+		f := gnuflag.NewFlagSet("test", gnuflag.ContinueOnError)
+		f.SetOutput(ioutil.Discard)
+		var value []string
+		f.Var(cmd.NewStringsValue(test.defaultValue, &value), "value", "help")
+		err := f.Parse(false, test.args)
+		c.Check(err, gc.IsNil)
+		c.Check(value, gc.DeepEquals, test.expectedValue)
+	}
+}
+
+func (*ArgsSuite) TestNewStringsValue(c *gc.C) {
+	for i, test := range []struct {
+		message      string
+		defaultValue []string
+	}{{
+		message: "null default",
+	}, {
+		message:      "empty default",
+		defaultValue: []string{},
+	}, {
+		message:      "single value",
+		defaultValue: []string{"foo"},
+	}, {
+		message:      "multiple values",
+		defaultValue: []string{"foo", "bar", "baz"},
+	}} {
+		c.Log(fmt.Sprintf("%v: %s", i, test.message))
+		var underlyingValue []string
+		_ = cmd.NewStringsValue(test.defaultValue, &underlyingValue)
+		c.Assert(underlyingValue, gc.DeepEquals, test.defaultValue)
+	}
+}
+
+func (*ArgsSuite) TestSet(c *gc.C) {
+	for i, test := range []struct {
+		message  string
+		arg      string
+		expected []string
+	}{{
+		message:  "empty",
+		expected: []string{""},
+	}, {
+		message:  "just whitespace",
+		arg:      "   ",
+		expected: []string{"   "},
+	}, {
+		message:  "whitespace and comma",
+		arg:      "  ,  ",
+		expected: []string{"  ", "  "},
+	}, {
+		message:  "single value",
+		arg:      "foo",
+		expected: []string{"foo"},
+	}, {
+		message:  "single value with comma",
+		arg:      "foo,",
+		expected: []string{"foo", ""},
+	}, {
+		message:  "single value with whitespace",
+		arg:      " foo ",
+		expected: []string{" foo "},
+	}, {
+		message:  "multiple values",
+		arg:      "foo,bar,baz",
+		expected: []string{"foo", "bar", "baz"},
+	}, {
+		message:  "multiple values with spaces",
+		arg:      "foo, bar, baz",
+		expected: []string{"foo", " bar", " baz"},
+	}} {
+		c.Log(fmt.Sprintf("%v: %s", i, test.message))
+		var result []string
+		value := cmd.NewStringsValue(nil, &result)
+		error := value.Set(test.arg)
+		c.Check(error, gc.IsNil)
+		c.Check(result, gc.DeepEquals, test.expected)
+	}
+}
+
+func (*ArgsSuite) TestString(c *gc.C) {
+	for i, test := range []struct {
+		message  string
+		target   []string
+		expected string
+	}{{
+		message:  "null",
+		expected: "",
+	}, {
+		message:  "empty",
+		target:   []string{},
+		expected: "",
+	}, {
+		message:  "single value",
+		target:   []string{"foo"},
+		expected: "foo",
+	}, {
+		message:  "multiple values",
+		target:   []string{"foo", "bar", "baz"},
+		expected: "foo,bar,baz",
+	}} {
+		c.Log(fmt.Sprintf("%v: %s", i, test.message))
+		var temp []string
+		value := cmd.NewStringsValue(test.target, &temp)
+		c.Assert(value.String(), gc.Equals, test.expected)
+	}
+}
+
+func (*ArgsSuite) TestAppendStringsUsage(c *gc.C) {
+	for i, test := range []struct {
+		message       string
+		args          []string
+		expectedValue []string
+	}{{
+		message: "no args",
+	}, {
+		message:       "value set by args",
+		args:          []string{"--value", "foo", "--value=bar"},
+		expectedValue: []string{"foo", "bar"},
+	}} {
+		c.Log(fmt.Sprintf("%v: %s", i, test.message))
+		f := gnuflag.NewFlagSet("test", gnuflag.ContinueOnError)
+		f.SetOutput(ioutil.Discard)
+		var value []string
+		f.Var(cmd.NewAppendStringsValue(&value), "value", "help")
+		err := f.Parse(false, test.args)
+		c.Check(err, gc.IsNil)
+		c.Check(value, gc.DeepEquals, test.expectedValue)
+	}
+}