Deprecate '--sort-by-XX' in favor of '--sort-by XX'

khos2ow · khos2ow · commit 557d53dd1e63 · 2021-04-12T18:34:42.000-04:00
This deprecates sort by flags in favor of their corresponding dynamic
valued ones. Affected flags are:

- `--sort-by-required`
- `--sort-by-type`

In return new `--sort-by string` is added with following values:

- `name` (default)
- `required`
- `type`

Note that the behavior of `--sort bool` was not changed and to disable
sorting altogether you can run `--sort false`.

Signed-off-by: Khosrow Moossavi &lt;khos2ow@gmail.com&gt;
diff --git a/cmd/root.go b/cmd/root.go
@@ -68,8 +68,14 @@ func NewCommand() *cobra.Command {
 	cmd.PersistentFlags().StringVar(&config.Output.Template, "output-template", cli.OutputTemplate, "Output template")
 
 	cmd.PersistentFlags().BoolVar(&config.Sort.Enabled, "sort", true, "sort items")
-	cmd.PersistentFlags().BoolVar(&config.Sort.By.Required, "sort-by-required", false, "sort items by name and print required ones first (default false)")
-	cmd.PersistentFlags().BoolVar(&config.Sort.By.Type, "sort-by-type", false, "sort items by type of them (default false)")
+	cmd.PersistentFlags().StringVar(&config.Sort.By, "sort-by", "name", "sort items by criteria ["+cli.SortTypes+"]")
+
+	// deprecated flags ==>
+	cmd.PersistentFlags().BoolVar(&config.Sort.Criteria.Required, "sort-by-required", false, "sort items by name and print required ones first (default false)")
+	cmd.PersistentFlags().BoolVar(&config.Sort.Criteria.Type, "sort-by-type", false, "sort items by type of them (default false)")
+	cmd.PersistentFlags().MarkDeprecated("sort-by-required", "use '--sort-by required' instead") //nolint:errcheck,gosec
+	cmd.PersistentFlags().MarkDeprecated("sort-by-type", "use '--sort-by type' instead")         //nolint:errcheck,gosec
+	// <==
 
 	cmd.PersistentFlags().StringVar(&config.HeaderFrom, "header-from", "main.tf", "relative path of a file to read header from")
 	cmd.PersistentFlags().StringVar(&config.FooterFrom, "footer-from", "", "relative path of a file to read footer from (default \"\")")
diff --git a/docs/reference/asciidoc-document.md b/docs/reference/asciidoc-document.md
@@ -43,8 +43,7 @@ terraform-docs asciidoc document [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/asciidoc-table.md b/docs/reference/asciidoc-table.md
@@ -43,8 +43,7 @@ terraform-docs asciidoc table [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/asciidoc.md b/docs/reference/asciidoc.md
@@ -44,8 +44,7 @@ terraform-docs asciidoc [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Subcommands
diff --git a/docs/reference/json.md b/docs/reference/json.md
@@ -39,8 +39,7 @@ terraform-docs json [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/markdown-document.md b/docs/reference/markdown-document.md
@@ -44,8 +44,7 @@ terraform-docs markdown document [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/markdown-table.md b/docs/reference/markdown-table.md
@@ -44,8 +44,7 @@ terraform-docs markdown table [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/markdown.md b/docs/reference/markdown.md
@@ -45,8 +45,7 @@ terraform-docs markdown [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Subcommands
diff --git a/docs/reference/pretty.md b/docs/reference/pretty.md
@@ -39,8 +39,7 @@ terraform-docs pretty [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/terraform-docs.md b/docs/reference/terraform-docs.md
@@ -33,8 +33,7 @@ terraform-docs [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Subcommands
diff --git a/docs/reference/tfvars-hcl.md b/docs/reference/tfvars-hcl.md
@@ -38,8 +38,7 @@ terraform-docs tfvars hcl [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/tfvars-json.md b/docs/reference/tfvars-json.md
@@ -38,8 +38,7 @@ terraform-docs tfvars json [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/tfvars.md b/docs/reference/tfvars.md
@@ -34,8 +34,7 @@ Generate terraform.tfvars of inputs.
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Subcommands
diff --git a/docs/reference/toml.md b/docs/reference/toml.md
@@ -38,8 +38,7 @@ terraform-docs toml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/xml.md b/docs/reference/xml.md
@@ -38,8 +38,7 @@ terraform-docs xml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/reference/yaml.md b/docs/reference/yaml.md
@@ -38,8 +38,7 @@ terraform-docs yaml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by-required            sort items by name and print required ones first (default false)
-      --sort-by-type                sort items by type of them (default false)
+      --sort-by string              sort items by criteria [name, required, type] (default "name")
 ```
 
 ## Example
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -68,9 +68,7 @@ output-values:
 
 sort:
   enabled: true
-  by:
-    - required
-    - type
+  by: name
 
 settings:
   anchor: true
@@ -89,7 +87,6 @@ settings:
 - `sections.hide-all` and `sections.show-all`
 - `sections.hide-all` and `sections.hide`
 - `sections.show-all` and `sections.show`
-- `sort.by.required` and `sort.by.type`
 
 ## Formatters
 
@@ -199,3 +196,14 @@ output:
     
     {{ .Content }}
 ```
+
+## Sort
+
+To enable sorting of elements `sort.enabled` (or `--sort bool` CLI flag) can be
+used. This will indicate sorting is enabled or not, but consecutively type of
+sorting can also be specified with `sort.by` (or `--sort-by string` CLI flag).
+The following sort types are supported:
+
+- `name` (default): name of items
+- `required`: by name of inputs AND show required ones first
+- `type`: type of inputs
diff --git a/examples/.terraform-docs.yml b/examples/.terraform-docs.yml
@@ -27,8 +27,7 @@ sections:
 
 sort:
   enabled: true
-  by:
-    - required
+  by: required
 
 settings:
   indent: 4
diff --git a/internal/cli/config.go b/internal/cli/config.go
@@ -29,7 +29,16 @@ const (
 	sectionResources    = "resources"
 )
 
-var allSections = []string{sectionFooter, sectionHeader, sectionInputs, sectionModules, sectionOutputs, sectionProviders, sectionRequirements, sectionResources}
+var allSections = []string{
+	sectionFooter,
+	sectionHeader,
+	sectionInputs,
+	sectionModules,
+	sectionOutputs,
+	sectionProviders,
+	sectionRequirements,
+	sectionResources,
+}
 
 // AllSections list.
 var AllSections = strings.Join(allSections, ", ")
@@ -225,37 +234,56 @@ func (o *outputvalues) validate() error {
 	return nil
 }
 
+const (
+	sortName     = "name"
+	sortRequired = "required"
+	sortType     = "type"
+)
+
+var allSorts = []string{
+	sortName,
+	sortRequired,
+	sortType,
+}
+
+// SortTypes list.
+var SortTypes = strings.Join(allSorts, ", ")
+
 type sortby struct {
+	Name     bool `name:"name"`
 	Required bool `name:"required"`
 	Type     bool `name:"type"`
 }
 type sort struct {
-	Enabled bool     `yaml:"enabled"`
-	ByList  []string `yaml:"by"`
-	By      sortby   `yaml:"-"`
+	Enabled  bool   `yaml:"enabled"`
+	By       string `yaml:"by"`
+	Criteria sortby `yaml:"-"`
 }
 
 func defaultSort() sort {
 	return sort{
 		Enabled: true,
-		ByList:  []string{},
-		By: sortby{
+		By:      sortName,
+		Criteria: sortby{
+			Name:     true,
 			Required: false,
 			Type:     false,
 		},
 	}
 }
 
 func (s *sort) validate() error {
-	types := []string{"required", "type"}
-	for _, item := range s.ByList {
-		switch item {
-		case types[0], types[1]:
-		default:
-			return fmt.Errorf("'%s' is not a valid sort type", item)
+	found := false
+	for _, item := range allSorts {
+		if item == s.By {
+			found = true
+			break
 		}
 	}
-	if s.By.Required && s.By.Type {
+	if !found {
+		return fmt.Errorf("'%s' is not a valid sort type", s.By)
+	}
+	if s.Criteria.Required && s.Criteria.Type {
 		return fmt.Errorf("'--sort-by-required' and '--sort-by-type' can't be used together")
 	}
 	return nil
@@ -343,6 +371,11 @@ func (c *Config) process() {
 	if c.FooterFrom == "" && !changedfs["footer-from"] {
 		c.Sections.footer = false
 	}
+
+	// Enable specified sort criteria
+	c.Sort.Criteria.Name = c.Sort.Enabled && c.Sort.By == sortName
+	c.Sort.Criteria.Required = c.Sort.Enabled && c.Sort.By == sortRequired
+	c.Sort.Criteria.Type = c.Sort.Enabled && c.Sort.By == sortType
 }
 
 // validate config and check for any misuse or misconfiguration
@@ -427,9 +460,9 @@ func (c *Config) extract() (*print.Settings, *terraform.Options) {
 	options.OutputValuesPath = c.OutputValues.From
 
 	// sort
-	options.SortBy.Name = c.Sort.Enabled
-	options.SortBy.Required = c.Sort.Enabled && c.Sort.By.Required
-	options.SortBy.Type = c.Sort.Enabled && c.Sort.By.Type
+	options.SortBy.Name = c.Sort.Enabled && c.Sort.Criteria.Name
+	options.SortBy.Required = c.Sort.Enabled && c.Sort.Criteria.Required
+	options.SortBy.Type = c.Sort.Enabled && c.Sort.Criteria.Type
 
 	// settings
 	settings.EscapeCharacters = c.Settings.Escape
diff --git a/internal/cli/reader.go b/internal/cli/reader.go
@@ -75,23 +75,14 @@ func (c *cfgreader) parse() error { //nolint:gocyclo
 			c.overrideShow()
 		case "hide":
 			c.overrideHide()
-		case "sort":
-			if err := c.overrideValue("enabled", &c.config.Sort, &c.overrides.Sort); err != nil {
+		case "sort", "sort-by":
+			mapping := map[string]string{"sort": "enabled", "sort-by": "by"}
+			if err := c.overrideValue(mapping[flag], &c.config.Sort, &c.overrides.Sort); err != nil {
 				return err
 			}
 		case "sort-by-required", "sort-by-type":
 			mapping := map[string]string{"sort-by-required": "required", "sort-by-type": "type"}
-			if !contains(c.config.Sort.ByList, mapping[flag]) {
-				c.config.Sort.ByList = append(c.config.Sort.ByList, mapping[flag])
-			}
-			el := reflect.ValueOf(&c.overrides.Sort.By).Elem()
-			field, err := c.findField(el, "name", mapping[flag])
-			if err != nil {
-				return err
-			}
-			if !el.FieldByName(field).Bool() {
-				c.config.Sort.ByList = remove(c.config.Sort.ByList, mapping[flag])
-			}
+			c.config.Sort.By = mapping[flag]
 		case "output-file", "output-mode", "output-template":
 			mapping := map[string]string{"output-file": "file", "output-mode": "mode", "output-template": "template"}
 			if err := c.overrideValue(mapping[flag], &c.config.Output, &c.overrides.Output); err != nil {
@@ -109,10 +100,6 @@ func (c *cfgreader) parse() error { //nolint:gocyclo
 		}
 	}
 
-	if err := c.updateSortTypes(); err != nil {
-		return err
-	}
-
 	return nil
 }
 
@@ -160,18 +147,6 @@ func (c *cfgreader) overrideHide() {
 	}
 }
 
-func (c *cfgreader) updateSortTypes() error {
-	for _, item := range c.config.Sort.ByList {
-		el := reflect.ValueOf(&c.config.Sort.By).Elem()
-		field, err := c.findField(el, "name", item)
-		if err != nil {
-			return err
-		}
-		el.FieldByName(field).Set(reflect.ValueOf(true))
-	}
-	return nil
-}
-
 func (c *cfgreader) findField(el reflect.Value, tag string, value string) (string, error) {
 	for i := 0; i < el.NumField(); i++ {
 		f := el.Type().Field(i)
diff --git a/internal/cli/reader_test.go b/internal/cli/reader_test.go
