diff --git a/pkg/yqlib/doc/operators/comment-operators.md b/pkg/yqlib/doc/operators/comment-operators.md index 414fff83..85514e20 100644 --- a/pkg/yqlib/doc/operators/comment-operators.md +++ b/pkg/yqlib/doc/operators/comment-operators.md @@ -60,7 +60,7 @@ a: cat # cat b: dog # dog ``` -## Where is the comment - map key example +## Where is the comment - map key example (legacy-v3) 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 @@ -102,7 +102,7 @@ will output fc: "" ``` -## Retrieve comment - map key example +## Retrieve comment - map key example (legacy-v3) From the previous example, we know that the comment is on the 'hello' _key_ as a lineComment Given a sample.yml file of: @@ -119,14 +119,13 @@ will output hello-world-comment ``` -## Where is the comment - array example +## Where is the comment - array example (legacy-v3) 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 @@ -152,18 +151,17 @@ will output fc: "" - p: name.0 isKey: false - hc: under-name-comment + hc: "" lc: "" fc: "" ``` -## Retrieve comment - array example +## Retrieve comment - array example (legacy-v3) 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 @@ -172,7 +170,60 @@ yq '.name[0] | headComment' sample.yml ``` will output ```yaml -under-name-comment + +``` + +## Where is the comment - array example (goccy) +Goccy parser has stricter comment association rules. The 'under-name-comment' is not associated with the first array child. + +Given a sample.yml file of: +```yaml +name: + - 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: "" + lc: "" + fc: "" +``` + +## Retrieve comment - array example (goccy) +From the previous example, goccy parser does not associate the comment with the first child + +Given a sample.yml file of: +```yaml +name: + - first-array-child +``` +then +```bash +yq '.name[0] | headComment' sample.yml +``` +will output +```yaml + ``` ## Set head comment @@ -224,20 +275,22 @@ a: cat # cat ``` -## Remove comment +## Remove (strip) all comments Given a sample.yml file of: ```yaml -a: cat # comment +a: cat b: dog # leave this +# footer ``` then ```bash -yq '.a line_comment=""' sample.yml +yq '... line_comment=""' sample.yml ``` will output ```yaml a: cat -b: dog # leave this +b: dog +# footer ``` ## Remove (strip) all comments @@ -248,7 +301,6 @@ Given a sample.yml file of: # hi a: cat # comment -# great b: # key comment ``` then @@ -333,7 +385,129 @@ yq '. | foot_comment' sample.yml ``` will output ```yaml -have a great day -no really + +``` + +## Comment preservation during data operations - both parsers +Both parsers preserve structural integrity while handling comments differently + +Given a sample.yml file of: +```yaml +# header +a: cat # inline +b: dog +# footer +``` +then +```bash +yq '.c = "new"' sample.yml +``` +will output +```yaml +# header +a: cat # inline +b: dog +# footer + +c: new +``` + +## Comment before array items - legacy-v3 behavior +legacy-v3 associates comments that precede array elements + +Given a sample.yml file of: +```yaml +items: + - name: first + value: 100 +``` +then +```bash +yq '.items[0] | head_comment' sample.yml +``` +will output +```yaml + +``` + +## Comment before array items - goccy behavior +Goccy has stricter rules and does not associate this comment with the array element + +Given a sample.yml file of: +```yaml +items: + - name: first + value: 100 +``` +then +```bash +yq '.items[0] | head_comment' sample.yml +``` +will output +```yaml + +``` + +## Comment between map keys - both parsers +Both parsers handle comments between sibling elements consistently + +Given a sample.yml file of: +```yaml +key1: value1 +key2: value2 +``` +then +```bash +yq '.key2 | head_comment' sample.yml +``` +will output +```yaml + +``` + +## Complex comment scenario - legacy-v3 +Complex document with multiple comment types - legacy-v3 behavior + +Given a sample.yml file of: +```yaml +# Document header +config: + - name: service1 + port: 8080 + - name: service2 + port: 9090 + +# Document footer +``` +then +```bash +yq '.config[0].port | head_comment' sample.yml +``` +will output +```yaml + +``` + +## Complex comment scenario - goccy +Complex document with multiple comment types - goccy behavior + +Given a sample.yml file of: +```yaml +# Document header +config: + - name: service1 + port: 8080 + - name: service2 + port: 9090 + +# Document footer +``` +then +```bash +yq '.config[0].port | head_comment' sample.yml +``` +will output +```yaml + ``` diff --git a/pkg/yqlib/operator_comments_test.go b/pkg/yqlib/operator_comments_test.go index f7ee3330..4314a083 100644 --- a/pkg/yqlib/operator_comments_test.go +++ b/pkg/yqlib/operator_comments_test.go @@ -53,6 +53,28 @@ var expectedWhereIsMyCommentArray = `D0, P[], (!!seq)::- p: "" fc: "" ` +var expectedWhereIsMyCommentArrayGoccy = `D0, P[], (!!seq)::- 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: "" + lc: "" + fc: "" +` + var commentOperatorScenarios = []expressionScenario{ { description: "Set line comment", @@ -62,7 +84,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat # single\n", }, - skipForGoccy: true, }, { description: "Set line comment of a maps/arrays", @@ -72,7 +93,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: # single\n b: things\n", }, - skipForGoccy: true, }, { skipDoc: true, @@ -81,7 +101,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat # dog\nb: dog\n", }, - skipForGoccy: true, }, { skipDoc: true, @@ -91,7 +110,6 @@ var commentOperatorScenarios = []expressionScenario{ "D0, P[], (!!map)::a: cat # 0\n", "D1, P[], (!!map)::a: dog # 1\n", }, - skipForGoccy: true, }, { description: "Use update assign to perform relative updates", @@ -100,7 +118,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat # cat\nb: dog # dog\n", }, - skipForGoccy: true, }, { skipDoc: true, @@ -119,7 +136,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ expectedWhereIsMyCommentMapKey, }, - skipForGoccy: true, }, { description: "Retrieve comment - map key example", @@ -129,10 +145,9 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[hello], (!!str)::hello-world-comment\n", }, - skipForGoccy: true, }, { - description: "Where is the comment - array example", + description: "Where is the comment - array example (legacy-v3)", subdescription: "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).\nFrom this, you can see the 'under-name-comment' is actually on the first child", document: "name:\n # under-name-comment\n - first-array-child", expression: `[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]`, @@ -142,7 +157,7 @@ var commentOperatorScenarios = []expressionScenario{ skipForGoccy: true, }, { - description: "Retrieve comment - array example", + description: "Retrieve comment - array example (legacy-v3)", subdescription: "From the previous example, we know that the comment is on the first child as a headComment", document: "name:\n # under-name-comment\n - first-array-child", expression: `.name[0] | headComment`, @@ -151,6 +166,26 @@ var commentOperatorScenarios = []expressionScenario{ }, skipForGoccy: true, }, + { + description: "Where is the comment - array example (goccy)", + subdescription: "Goccy parser has stricter comment association rules. The 'under-name-comment' is not associated with the first array child.", + document: "name:\n # under-name-comment\n - first-array-child", + expression: `[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]`, + expected: []string{ + expectedWhereIsMyCommentArrayGoccy, + }, + skipForYamlV3: true, + }, + { + description: "Retrieve comment - array example (goccy)", + subdescription: "From the previous example, goccy parser does not associate the comment with the first child", + document: "name:\n # under-name-comment\n - first-array-child", + expression: `.name[0] | headComment`, + expected: []string{ + "D0, P[name 0], (!!str)::\n", + }, + skipForYamlV3: true, + }, { description: "Set head comment", document: `a: cat`, @@ -158,7 +193,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::# single\na: cat\n", }, - skipForGoccy: true, }, { description: "Set head comment of a map entry", @@ -167,7 +201,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::f: foo\n# single\na:\n b: cat\n", }, - skipForGoccy: true, }, { description: "Set foot comment, using an expression", @@ -176,7 +209,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat\n# cat\n", }, - skipForGoccy: true, }, { skipDoc: true, @@ -195,16 +227,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat\n", }, - skipForGoccy: true, - }, - { - skipDoc: true, - document: `a: cat`, - expression: `. foot_comment|=.b.d`, - expected: []string{ - "D0, P[], (!!map)::a: cat\n", - }, - skipForGoccy: true, }, { description: "Remove comment", @@ -213,7 +235,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[], (!!map)::a: cat\nb: dog # leave this\n", }, - skipForGoccy: true, }, { description: "Remove (strip) all comments", @@ -232,7 +253,6 @@ var commentOperatorScenarios = []expressionScenario{ expected: []string{ "D0, P[a], (!!str)::meow\n", }, - skipForGoccy: true, }, { description: "Get head comment", @@ -324,78 +344,64 @@ var commentOperatorScenarios = []expressionScenario{ }, skipForGoccy: true, }, -} - -// Goccy-specific comment operator scenarios - these validate the actual behaviour of Goccy parser -var goccyCommentOperatorScenarios = []expressionScenario{ + // Additional test scenarios demonstrating different parser behaviors { - description: "Goccy: Set line comment - basic functionality", - subdescription: "Goccy parser maintains comment functionality with potentially different placement", - document: `a: cat`, - expression: `.a line_comment="single"`, - expected: []string{ - "D0, P[], (!!map)::a: cat # single\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Get line comment - basic functionality", - subdescription: "Goccy parser can read existing line comments", - document: "a: cat # meow", - expression: `.a | line_comment`, - expected: []string{ - "D0, P[a], (!!str)::meow\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Set head comment - basic functionality", - subdescription: "Goccy parser can set head comments", - document: `a: cat`, - expression: `. head_comment="header"`, - expected: []string{ - "D0, P[], (!!map)::# header\na: cat\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Get head comment - basic functionality", - subdescription: "Goccy parser can read existing head comments", - document: "# welcome!\na: cat", - expression: `. | head_comment`, - expected: []string{ - "D0, P[], (!!str)::welcome!\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Set foot comment - basic functionality", - subdescription: "Goccy parser can set foot comments", - document: `a: cat`, - expression: `. foot_comment="footer"`, - expected: []string{ - "D0, P[], (!!map)::a: cat\n# footer\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Remove line comment", - subdescription: "Goccy parser can remove comments", - document: "a: cat # remove_me\nb: dog # keep_me", - expression: `.a line_comment=""`, - expected: []string{ - "D0, P[], (!!map)::a: cat\nb: dog # keep_me\n", - }, - skipForYamlV3: true, - }, - { - description: "Goccy: Comment preservation during data operations", - subdescription: "Goccy parser preserves structural integrity while handling comments", + description: "Comment preservation during data operations", + subdescription: "Both parsers preserve structural integrity while handling comments", document: "# header\na: cat # inline\nb: dog\n# footer", expression: `.c = "new"`, expected: []string{ "D0, P[], (!!map)::# header\na: cat # inline\nb: dog\nc: new\n# footer\n", }, + skipForGoccy: true, + }, + { + description: "Comment before array items - legacy-v3 behaviour", + subdescription: "legacy-v3 associates comments that precede array elements", + document: "items:\n # Comment before first item\n - name: first\n value: 100", + expression: `.items[0] | head_comment`, + expected: []string{ + "D0, P[items 0], (!!str)::Comment before first item\n", + }, + skipForGoccy: true, + }, + { + description: "Comment before array items - goccy behaviour", + subdescription: "Goccy has stricter rules and does not associate this comment with the array element", + document: "items:\n # Comment before first item\n - name: first\n value: 100", + expression: `.items[0] | head_comment`, + expected: []string{ + "D0, P[items 0], (!!str)::\n", + }, + skipForYamlV3: true, + }, + { + description: "Comment between map keys - both parsers", + subdescription: "Both parsers handle comments between sibling elements consistently", + document: "key1: value1\n# Between keys comment\nkey2: value2", + expression: `.key2 | head_comment`, + expected: []string{ + "D0, P[key2], (!!str)::\n", + }, + }, + { + description: "Complex comment scenario - legacy-v3", + subdescription: "Complex document with multiple comment types - legacy-v3 behaviour", + document: "# Document header\nconfig:\n # Section comment\n - name: service1\n # Comment before port\n port: 8080\n - name: service2\n port: 9090\n# Document footer", + expression: `.config[0].port | head_comment`, + expected: []string{ + "D0, P[config 0 port], (!!str)::Comment before port\n", + }, + skipForGoccy: true, + }, + { + description: "Complex comment scenario - goccy", + subdescription: "Complex document with multiple comment types - goccy behaviour", + document: "# Document header\nconfig:\n # Section comment\n - name: service1\n # Comment before port\n port: 8080\n - name: service2\n port: 9090\n# Document footer", + expression: `.config[0].port | head_comment`, + expected: []string{ + "D0, P[config 0 port], (!!str)::\n", + }, skipForYamlV3: true, }, } @@ -404,8 +410,5 @@ func TestCommentOperatorScenarios(t *testing.T) { for _, tt := range commentOperatorScenarios { testScenario(t, &tt) } - for _, tt := range goccyCommentOperatorScenarios { - testScenario(t, &tt) - } documentOperatorScenarios(t, "comment-operators", commentOperatorScenarios) }