From 5edabcf934457cd5206dfd440e7f49e5c8d0ce2b Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Fri, 9 Feb 2024 14:54:36 +1100 Subject: [PATCH] Improve merge docs --- operators/multiply-merge.md | 5 ++- usage/formatting-expressions.md | 61 +++++++++++++++++++++++++++++++++ usage/xml.md | 12 +++---- 3 files changed, 71 insertions(+), 7 deletions(-) create mode 100644 usage/formatting-expressions.md diff --git a/operators/multiply-merge.md b/operators/multiply-merge.md index a7cf3d62..963a1f30 100644 --- a/operators/multiply-merge.md +++ b/operators/multiply-merge.md @@ -3,7 +3,9 @@ Like the multiple operator in jq, depending on the operands, this multiply operator will do different things. Currently numbers, arrays and objects are supported. ## Objects and arrays - merging -Objects are merged deeply matching on matching keys. By default, array values override and are not deeply merged. +Objects are merged _deeply_ matching on matching keys. By default, array values override and are not deeply merged. + +You can use the add operator `+`, to shallow merge objects, see more info [here](https://mikefarah.gitbook.io/yq/operators/add). Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below. @@ -16,6 +18,7 @@ You can control how objects are merged by using one or more of the following fla - `n` only merge _new_ fields - `c` clobber custom tags +To perform a shallow merge only, use the add operator `+`, see more info [here](https://mikefarah.gitbook.io/yq/operators/add). ### Merge two files together This uses the load operator to merge file2 into file1. diff --git a/usage/formatting-expressions.md b/usage/formatting-expressions.md new file mode 100644 index 00000000..51e24117 --- /dev/null +++ b/usage/formatting-expressions.md @@ -0,0 +1,61 @@ +# Formatting Expressions + +`From version v4.41+` + +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 +Given a sample.yaml file of: +```yaml +a: + b: old +``` +And an 'update.yq' expression file of: +```bash +# 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 +yq --from-file update.yq sample.yml +``` +will output +```yaml +a: + b: new + c: frog +``` + +## Commenting out yq expressions +Note that `c` is no longer set to 'frog'. + +Given a sample.yaml file of: +```yaml +a: + b: old +``` +And an 'update.yq' expression file of: +```bash +# 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 +yq --from-file update.yq sample.yml +``` +will output +```yaml +a: + b: new +``` + diff --git a/usage/xml.md b/usage/xml.md index 503f9a74..4238e971 100644 --- a/usage/xml.md +++ b/usage/xml.md @@ -370,7 +370,7 @@ cat: purrs ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml @@ -387,7 +387,7 @@ pets: ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml @@ -409,7 +409,7 @@ cat: ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml @@ -430,7 +430,7 @@ cat: ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml @@ -457,7 +457,7 @@ cat: # inline_cat ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml @@ -487,7 +487,7 @@ apple: ``` then ```bash -yq -o=xml '.' sample.yml +yq -o=xml sample.yml ``` will output ```xml