Improved error message

pkg/yqlib/candidate_node.go

@@ -3,6 +3,7 @@ package yqlib
 import (
 	"container/list"
 	"fmt"
+	"strings"
 
 	"github.com/jinzhu/copier"
 	yaml "gopkg.in/yaml.v3"
@@ -33,6 +34,21 @@ func (n *CandidateNode) GetKey() string {
 	return fmt.Sprintf("%v%v - %v", keyPrefix, n.Document, n.Path)
 }
 
+func (n *CandidateNode) GetNiceTag() string {
+	return unwrapDoc(n.Node).Tag
+}
+
+func (n *CandidateNode) GetNicePath() string {
+	if n.Path != nil && len(n.Path) >= 0 {
+		pathStr := make([]string, len(n.Path))
+		for i, v := range n.Path {
+			pathStr[i] = fmt.Sprintf("%v", v)
+		}
+		return strings.Join(pathStr, ".")
+	}
+	return ""
+}
+
 func (n *CandidateNode) AsList() *list.List {
 	elMap := list.New()
 	elMap.PushBack(n)

pkg/yqlib/doc/headers/sort.md

@@ -1,5 +1,5 @@
 # Sort
 
-Sorts an array. Use `sort` to sort an array as is, or `sort_by` to sort by a particular subfield.
+Sorts an array. Use `sort` to sort an array as is, or `sort_by(exp)` to sort by a particular expression (e.g. subfield).
 
 Note that at this stage, `yq` only sorts scalar fields.

pkg/yqlib/doc/sort.md

@@ -1,6 +1,6 @@
 # Sort
 
-Sorts an array. Use `sort` to sort an array as is, or `sort_by` to sort by a particular subfield.
+Sorts an array. Use `sort` to sort an array as is, or `sort_by(exp)` to sort by a particular expression (e.g. subfield).
 
 Note that at this stage, `yq` only sorts scalar fields.
 
@@ -22,6 +22,48 @@ will output
 - a: cat
 ```
 
+## Sort array in place
+Given a sample.yml file of:
+```yaml
+cool:
+  - a: banana
+  - a: cat
+  - a: apple
+```
+then
+```bash
+yq eval '.cool |= sort_by(.a)' sample.yml
+```
+will output
+```yaml
+cool:
+  - a: apple
+  - a: banana
+  - a: cat
+```
+
+## Sort array of objects by key
+Note that you can give sort_by complex expressions, not just paths
+
+Given a sample.yml file of:
+```yaml
+cool:
+  - b: banana
+  - a: banana
+  - c: banana
+```
+then
+```bash
+yq eval '.cool |= sort_by(keys | .[0])' sample.yml
+```
+will output
+```yaml
+cool:
+  - a: banana
+  - b: banana
+  - c: banana
+```
+
 ## Sort is stable
 Note the order of the elements in unchanged when equal in sorting.
 

pkg/yqlib/operator_sort.go

@@ -28,7 +28,7 @@ func sortByOperator(d *dataTreeNavigator, context Context, expressionNode *Expre
 		candidateNode := unwrapDoc(candidate.Node)
 
 		if candidateNode.Kind != yaml.SequenceNode {
-			return context, fmt.Errorf("%v is not an array", candidate.GetKey())
+			return context, fmt.Errorf("node at path [%v] is not an array (it's a %v)", candidate.GetNicePath(), candidate.GetNiceTag())
 		}
 
 		sortableArray := make(sortableNodeArray, len(candidateNode.Content))

pkg/yqlib/operator_sort_test.go

@@ -11,6 +11,23 @@ var sortByOperatorScenarios = []expressionScenario{
 			"D0, P[], (!!seq)::[{a: apple}, {a: banana}, {a: cat}]\n",
 		},
 	},
+	{
+		description: "Sort array in place",
+		document:    "cool: [{a: banana},{a: cat},{a: apple}]",
+		expression:  `.cool |= sort_by(.a)`,
+		expected: []string{
+			"D0, P[], (doc)::cool: [{a: apple}, {a: banana}, {a: cat}]\n",
+		},
+	},
+	{
+		description:    "Sort array of objects by key",
+		subdescription: "Note that you can give sort_by complex expressions, not just paths",
+		document:       "cool: [{b: banana},{a: banana},{c: banana}]",
+		expression:     `.cool |= sort_by(keys | .[0])`,
+		expected: []string{
+			"D0, P[], (doc)::cool: [{a: banana}, {b: banana}, {c: banana}]\n",
+		},
+	},
 	{
 		description:    "Sort is stable",
 		subdescription: "Note the order of the elements in unchanged when equal in sorting.",