From 796b4a0955a80e040edb9e0fab862543ca3f700e Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Fri, 16 Feb 2024 10:56:18 +1100 Subject: [PATCH] Adding shebang documentation --- examples/environment.yq | 2 +- pkg/yqlib/doc/usage/formatting-expressions.md | 9 +++++-- pkg/yqlib/formatting_expressions_test.go | 25 ++++++++++++++----- release_notes.txt | 3 +++ 4 files changed, 30 insertions(+), 9 deletions(-) diff --git a/examples/environment.yq b/examples/environment.yq index 81325364..aa15e91c 100755 --- a/examples/environment.yq +++ b/examples/environment.yq @@ -1,4 +1,4 @@ -#!yq +#! yq .[] |( ( select(kind == "scalar") | key + "='" + . + "'"), ( select(kind == "seq") | key + "=(" + (map("'" + . + "'") | join(",")) + ")") diff --git a/pkg/yqlib/doc/usage/formatting-expressions.md b/pkg/yqlib/doc/usage/formatting-expressions.md index 51e24117..5846318e 100644 --- a/pkg/yqlib/doc/usage/formatting-expressions.md +++ b/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. diff --git a/pkg/yqlib/formatting_expressions_test.go b/pkg/yqlib/formatting_expressions_test.go index 17f8fbdc..f2233d1b 100644 --- a/pkg/yqlib/formatting_expressions_test.go +++ b/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", - subdescription: "Note that `c` is no longer set to 'frog'.", + description: "Using expression files and comments", + 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)))) diff --git a/release_notes.txt b/release_notes.txt index b5fb9b61..0982e35a 100644 --- a/release_notes.txt +++ b/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