Adding shebang documentation

examples/environment.yq

@@ -1,4 +1,4 @@
-#!yq
+#! yq
 .[] |(
     ( select(kind == "scalar") | key + "='" + . + "'"),
     ( select(kind == "seq") | key + "=(" + (map("'" + . + "'") | join(",")) + ")")

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

@@ -5,6 +5,8 @@
 You can put expressions into `.yq` files, use whitespace and comments to break up complex expressions and explain what's going on.
 
 ## Using expression files and comments
+Note that you can execute the file directly - but make sure you make the expression file executable.
+
 Given a sample.yaml file of:
 ```yaml
 a:
@@ -12,6 +14,8 @@ a:
 ```
 And an 'update.yq' expression file of:
 ```bash
+#! yq
+
 # This is a yq expression that updates the map
 # for several great reasons outlined here.
 
@@ -22,7 +26,7 @@ And an 'update.yq' expression file of:
 ```
 then
 ```bash
-yq --from-file update.yq sample.yml
+./update.yq sample.yaml
 ```
 will output
 ```yaml
@@ -32,7 +36,7 @@ a:
 ```
 
 ## Commenting out yq expressions
-Note that `c` is no longer set to 'frog'.
+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.
 
 Given a sample.yaml file of:
 ```yaml
@@ -41,6 +45,7 @@ a:
 ```
 And an 'update.yq' expression file of:
 ```bash
+#! yq
 # This is a yq expression that updates the map
 # for several great reasons outlined here.
 

pkg/yqlib/formatting_expressions_test.go

@@ -11,15 +11,24 @@ import (
 var formattingExpressionScenarios = []formatScenario{
 	{
 		description: "Using expression files and comments",
+		skipDoc:     true,
 		input:       "a:\n  b: old",
-		expression:  "\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",
+		expression:  "#! yq\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",
 	},
 	{
-		description:    "Commenting out yq expressions",
+		description:    "Using expression files and comments",
-		subdescription: "Note that `c` is no longer set to 'frog'.",
+		subdescription: "Note that you can execute the file directly - but make sure you make the expression file executable.",
 		input:          "a:\n  b: old",
-		expression:     "\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",
+		expression:     "#! yq\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",
+	},
+	{
+		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.",
+		input:          "a:\n  b: old",
+		expression:     "#! yq\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",
 	},
 }
@@ -41,10 +50,14 @@ func documentExpressionScenario(_ *testing.T, w *bufio.Writer, i interface{}) {
 	writeOrPanic(w, fmt.Sprintf("```yaml\n%v\n```\n", s.input))
 
 	writeOrPanic(w, "And an 'update.yq' expression file of:\n")
-	writeOrPanic(w, fmt.Sprintf("```bash%v```\n", s.expression))
+	writeOrPanic(w, fmt.Sprintf("```bash\n%v```\n", s.expression))
 
 	writeOrPanic(w, "then\n")
-	writeOrPanic(w, "```bash\nyq --from-file update.yq sample.yml\n```\n")
+	if 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")
 
 	writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n", mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewYamlEncoder(2, false, ConfiguredYamlPreferences))))

release_notes.txt

@@ -1,3 +1,6 @@
+4.42.1 (not released):
+  - Can execute yq expression files directly with shebang (#1851)
+
 4.41.1:
   - Can now comment in yq expressions! #1919
   - Fixed Toml decoding when table array defined before parent #1922