Adding shebang documentation

pkg/yqlib/doc/usage/formatting-expressions.md

@@ -35,6 +35,40 @@ a:
   c: frog
 ```
 
+## Flags in expression files
+You can specify flags on the shebang line, this only works when executing the file directly.
+
+Given a sample.yaml file of:
+```yaml
+a:
+  b: old
+```
+And an 'update.yq' expression file of:
+```bash
+#! yq -oj
+
+# This is a yq expression that updates the map
+# for several great reasons outlined here.
+
+.a.b = "new" # line comment here
+| .a.c = "frog"
+
+# Now good things will happen.
+```
+then
+```bash
+./update.yq sample.yaml
+```
+will output
+```yaml
+{
+  "a": {
+    "b": "new",
+    "c": "frog"
+  }
+}
+```
+
 ## Commenting out yq expressions
 Note that `c` is no longer set to 'frog'. In this example we're calling yq directly and passing the expression file into `--from-file`, this is no different from executing the expression file directly.
 

pkg/yqlib/formatting_expressions_test.go

@@ -3,6 +3,7 @@ package yqlib
 import (
 	"bufio"
 	"fmt"
+	"strings"
 	"testing"
 
 	"github.com/mikefarah/yq/v4/test"
@@ -24,6 +25,14 @@ var formattingExpressionScenarios = []formatScenario{
 		expected:       "a:\n  b: new\n  c: frog\n",
 		scenarioType:   "shebang",
 	},
+	{
+		description:    "Flags in expression files",
+		subdescription: "You can specify flags on the shebang line, this only works when executing the file directly.",
+		input:          "a:\n  b: old",
+		expression:     "#! yq -oj\n\n# This is a yq expression that updates the map\n# for several great reasons outlined here.\n\n.a.b = \"new\" # line comment here\n| .a.c = \"frog\"\n\n# Now good things will happen.\n",
+		expected:       "a:\n  b: new\n  c: frog\n",
+		scenarioType:   "shebang-json",
+	},
 	{
 		description:    "Commenting out yq expressions",
 		subdescription: "Note that `c` is no longer set to 'frog'. In this example we're calling yq directly and passing the expression file into `--from-file`, this is no different from executing the expression file directly.",
@@ -53,14 +62,19 @@ func documentExpressionScenario(_ *testing.T, w *bufio.Writer, i interface{}) {
 	writeOrPanic(w, fmt.Sprintf("```bash\n%v```\n", s.expression))
 
 	writeOrPanic(w, "then\n")
-	if s.scenarioType == "shebang" {
+	if strings.HasPrefix(s.scenarioType, "shebang") {
 		writeOrPanic(w, "```bash\n./update.yq sample.yaml\n```\n")
 	} else {
 		writeOrPanic(w, "```bash\nyq --from-file update.yq sample.yml\n```\n")
 	}
 	writeOrPanic(w, "will output\n")
+	encoder := NewYamlEncoder(2, false, ConfiguredYamlPreferences)
 
-	writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n", mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewYamlEncoder(2, false, ConfiguredYamlPreferences))))
+	if s.scenarioType == "shebang-json" {
+		encoder = NewJSONEncoder(2, false, false)
+	}
+
+	writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n", mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), encoder)))
 }
 
 func TestExpressionCommentScenarios(t *testing.T) {