From 2db47ec2f228cff0eca9f9e4f03688f1ae6cffbe Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Wed, 5 Oct 2022 20:23:03 +1100 Subject: [PATCH] v4.28.1 --- operators/comment-operators.md | 136 ++++++++++++++++++++++++++++++++- operators/keys.md | 40 ++++++++++ operators/path.md | 116 +++++++++++++++++++++++++++- 3 files changed, 290 insertions(+), 2 deletions(-) diff --git a/operators/comment-operators.md b/operators/comment-operators.md index d29a9b19..5560b1e9 100644 --- a/operators/comment-operators.md +++ b/operators/comment-operators.md @@ -1,6 +1,6 @@ # Comment Operators -Use these comment operators to set or retrieve comments. +Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the _key_ node as opposed to the _value_ (map/array). See below for examples. Like the `=` and `|=` assign operators, the same syntax applies when updating comments: @@ -66,6 +66,121 @@ a: cat # cat b: dog # dog ``` +## Where is the comment - map key example +The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value). +From this, you can see the 'hello-world-comment' is actually on the 'hello' key + +Given a sample.yml file of: +```yaml +hello: # hello-world-comment + message: world +``` +then +```bash +yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml +``` +will output +```yaml +- p: "" + isKey: false + hc: "" + lc: "" + fc: "" +- p: hello + isKey: true + hc: "" + lc: hello-world-comment + fc: "" +- p: hello + isKey: false + hc: "" + lc: "" + fc: "" +- p: hello.message + isKey: true + hc: "" + lc: "" + fc: "" +- p: hello.message + isKey: false + hc: "" + lc: "" + fc: "" +``` + +## Retrieve comment - map key example +From the previous example, we know that the comment is on the 'hello' _key_ as a lineComment + +Given a sample.yml file of: +```yaml +hello: # hello-world-comment + message: world +``` +then +```bash +yq '.hello | key | line_comment' sample.yml +``` +will output +```yaml +hello-world-comment +``` + +## Where is the comment - array example +The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value). +From this, you can see the 'under-name-comment' is actually on the first child + +Given a sample.yml file of: +```yaml +name: + # under-name-comment + - first-array-child +``` +then +```bash +yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml +``` +will output +```yaml +- p: "" + isKey: false + hc: "" + lc: "" + fc: "" +- p: name + isKey: true + hc: "" + lc: "" + fc: "" +- p: name + isKey: false + hc: "" + lc: "" + fc: "" +- p: name.0 + isKey: false + hc: under-name-comment + lc: "" + fc: "" +``` + +## Retrieve comment - array example +From the previous example, we know that the comment is on the first child as a headComment + +Given a sample.yml file of: +```yaml +name: + # under-name-comment + - first-array-child +``` +then +```bash +yq '.name[0] | headComment' sample.yml +``` +will output +```yaml +under-name-comment +``` + ## Set head comment Given a sample.yml file of: ```yaml @@ -82,6 +197,25 @@ will output a: cat ``` +## Set head comment of a map entry +Given a sample.yml file of: +```yaml +f: foo +a: + b: cat +``` +then +```bash +yq '(.a | key) head_comment="single"' sample.yml +``` +will output +```yaml +f: foo +# single +a: + b: cat +``` + ## Set foot comment, using an expression Given a sample.yml file of: ```yaml diff --git a/operators/keys.md b/operators/keys.md index 9be768e5..f4ef293a 100644 --- a/operators/keys.md +++ b/operators/keys.md @@ -118,3 +118,43 @@ will output comment on key ``` +## Check node is a key +Given a sample.yml file of: +```yaml +a: + b: + - cat + c: frog +``` +then +```bash +yq '[... | { "p": path | join("."), "isKey": is_key, "tag": tag }]' sample.yml +``` +will output +```yaml +- p: "" + isKey: false + tag: '!!map' +- p: a + isKey: true + tag: '!!str' +- p: a + isKey: false + tag: '!!map' +- p: a.b + isKey: true + tag: '!!str' +- p: a.b + isKey: false + tag: '!!seq' +- p: a.b.0 + isKey: false + tag: '!!str' +- p: a.c + isKey: true + tag: '!!str' +- p: a.c + isKey: false + tag: '!!str' +``` + diff --git a/operators/path.md b/operators/path.md index 27ccf016..51ac3d4f 100644 --- a/operators/path.md +++ b/operators/path.md @@ -1,9 +1,12 @@ # Path -The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node. +The `path` operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node. You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key. +Use `setpath` to set a value to the path array returned by `path`, and similarly `delpaths` for an array of path arrays. + + {% hint style="warning" %} Note that versions prior to 4.18 require the 'eval/e' command to be specified. @@ -98,3 +101,114 @@ will output value: frog ``` +## Set path +Given a sample.yml file of: +```yaml +a: + b: cat +``` +then +```bash +yq 'setpath(["a", "b"]; "things")' sample.yml +``` +will output +```yaml +a: + b: things +``` + +## Set on empty document +Running +```bash +yq --null-input 'setpath(["a", "b"]; "things")' +``` +will output +```yaml +a: + b: things +``` + +## Set array path +Given a sample.yml file of: +```yaml +a: + - cat + - frog +``` +then +```bash +yq 'setpath(["a", 0]; "things")' sample.yml +``` +will output +```yaml +a: + - things + - frog +``` + +## Set array path empty +Running +```bash +yq --null-input 'setpath(["a", 0]; "things")' +``` +will output +```yaml +a: + - things +``` + +## Delete path +Notice delpaths takes an _array_ of paths. + +Given a sample.yml file of: +```yaml +a: + b: cat + c: dog + d: frog +``` +then +```bash +yq 'delpaths([["a", "c"], ["a", "d"]])' sample.yml +``` +will output +```yaml +a: + b: cat +``` + +## Delete array path +Given a sample.yml file of: +```yaml +a: + - cat + - frog +``` +then +```bash +yq 'delpaths([["a", 0]])' sample.yml +``` +will output +```yaml +a: + - frog +``` + +## Delete - wrong parameter +delpaths does not work with a single path array + +Given a sample.yml file of: +```yaml +a: + - cat + - frog +``` +then +```bash +yq 'delpaths(["a", 0])' sample.yml +``` +will output +```bash +Error: DELPATHS: expected entry [0] to be a sequence, but its a !!str. Note that delpaths takes an array of path arrays, e.g. [["a", "b"]] +``` +