v4.53.2

usage/hcl.md

@@ -7,7 +7,7 @@ HCL is commonly used in HashiCorp tools like Terraform for configuration files.
 - String interpolation and expressions (preserved without quotes)
 - Comments (leading, head, and line comments)
 - Nested structures (maps and lists)
-- Syntax colorization when enabled
+- Syntax colorisation when enabled
 
 
 ## Parse HCL

usage/kyaml.md

@@ -0,0 +1,253 @@
+# KYaml
+
+Encode and decode to and from KYaml (a restricted subset of YAML that uses flow-style collections).
+
+KYaml is useful when you want YAML data rendered in a compact, JSON-like form while still supporting YAML features like comments.
+
+Notes:
+- Strings are always double-quoted in KYaml output.
+- Anchors and aliases are expanded (KYaml output does not emit them).
+
+## Encode kyaml: plain string scalar
+Strings are always double-quoted in KYaml output.
+
+Given a sample.yml file of:
+```yaml
+cat
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+"cat"
+```
+
+## encode flow mapping and sequence
+Given a sample.yml file of:
+```yaml
+a: b
+c:
+  - d
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  a: "b",
+  c: [
+    "d",
+  ],
+}
+```
+
+## encode non-string scalars
+Given a sample.yml file of:
+```yaml
+a: 12
+b: true
+c: null
+d: "true"
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  a: 12,
+  b: true,
+  c: null,
+  d: "true",
+}
+```
+
+## quote non-identifier keys
+Given a sample.yml file of:
+```yaml
+"1a": b
+"has space": c
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  "1a": "b",
+  "has space": "c",
+}
+```
+
+## escape quoted strings
+Given a sample.yml file of:
+```yaml
+a: "line1\nline2\t\"q\""
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  a: "line1\nline2\t\"q\"",
+}
+```
+
+## preserve comments when encoding
+Given a sample.yml file of:
+```yaml
+# leading
+a: 1 # a line
+# head b
+b: 2
+c:
+  # head d
+  - d # d line
+  - e
+# trailing
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+# leading
+{
+  a: 1, # a line
+  # head b
+  b: 2,
+  c: [
+    # head d
+    "d", # d line
+    "e",
+  ],
+  # trailing
+}
+```
+
+## Encode kyaml: anchors and aliases
+KYaml output does not support anchors/aliases; they are expanded to concrete values.
+
+Given a sample.yml file of:
+```yaml
+base: &base
+  a: b
+copy: *base
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  base: {
+    a: "b",
+  },
+  copy: {
+    a: "b",
+  },
+}
+```
+
+## Encode kyaml: yaml to kyaml shows formatting differences
+KYaml uses flow-style collections (braces/brackets) and explicit commas.
+
+Given a sample.yml file of:
+```yaml
+person:
+  name: John
+  pets:
+    - cat
+    - dog
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+{
+  person: {
+    name: "John",
+    pets: [
+      "cat",
+      "dog",
+    ],
+  },
+}
+```
+
+## Encode kyaml: nested lists of objects
+Lists and objects can be nested arbitrarily; KYaml always uses flow-style collections.
+
+Given a sample.yml file of:
+```yaml
+- name: a
+  items:
+    - id: 1
+      tags:
+        - k: x
+          v: y
+        - k: x2
+          v: y2
+    - id: 2
+      tags:
+        - k: z
+          v: w
+
+```
+then
+```bash
+yq -o=kyaml '.' sample.yml
+```
+will output
+```yaml
+[
+  {
+    name: "a",
+    items: [
+      {
+        id: 1,
+        tags: [
+          {
+            k: "x",
+            v: "y",
+          },
+          {
+            k: "x2",
+            v: "y2",
+          },
+        ],
+      },
+      {
+        id: 2,
+        tags: [
+          {
+            k: "z",
+            v: "w",
+          },
+        ],
+      },
+    ],
+  },
+]
+```
+

usage/toml.md

@@ -141,3 +141,263 @@ will output
 dependencies: {}
 ```
 
+## Roundtrip: inline table attribute
+Given a sample.toml file of:
+```toml
+name = { first = "Tom", last = "Preston-Werner" }
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+name = { first = "Tom", last = "Preston-Werner" }
+```
+
+## Roundtrip: table section
+Given a sample.toml file of:
+```toml
+[owner.contact]
+name = "Tom"
+age = 36
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+[owner.contact]
+name = "Tom"
+age = 36
+```
+
+## Roundtrip: array of tables
+Given a sample.toml file of:
+```toml
+[[fruits]]
+name = "apple"
+[[fruits.varieties]]
+name = "red delicious"
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+[[fruits]]
+name = "apple"
+[[fruits.varieties]]
+name = "red delicious"
+```
+
+## Roundtrip: arrays and scalars
+Given a sample.toml file of:
+```toml
+A = ["hello", ["world", "again"]]
+B = 12
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+A = ["hello", ["world", "again"]]
+B = 12
+```
+
+## Roundtrip: simple
+Given a sample.toml file of:
+```toml
+A = "hello"
+B = 12
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+A = "hello"
+B = 12
+```
+
+## Roundtrip: deep paths
+Given a sample.toml file of:
+```toml
+[person]
+name = "hello"
+address = "12 cat st"
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+[person]
+name = "hello"
+address = "12 cat st"
+```
+
+## Roundtrip: empty array
+Given a sample.toml file of:
+```toml
+A = []
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+A = []
+```
+
+## Roundtrip: sample table
+Given a sample.toml file of:
+```toml
+var = "x"
+
+[owner.contact]
+name = "Tom Preston-Werner"
+age = 36
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+var = "x"
+
+[owner.contact]
+name = "Tom Preston-Werner"
+age = 36
+```
+
+## Roundtrip: empty table
+Given a sample.toml file of:
+```toml
+[dependencies]
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+[dependencies]
+```
+
+## Roundtrip: comments
+Given a sample.toml file of:
+```toml
+# This is a comment
+A = "hello"  # inline comment
+B = 12
+
+# Table comment
+[person]
+name = "Tom"  # name comment
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+# This is a comment
+A = "hello"  # inline comment
+B = 12
+
+# Table comment
+[person]
+name = "Tom"  # name comment
+```
+
+## Roundtrip: sample from web
+Given a sample.toml file of:
+```toml
+# This is a TOML document
+title = "TOML Example"
+
+[owner]
+name = "Tom Preston-Werner"
+dob = 1979-05-27T07:32:00-08:00
+
+[database]
+enabled = true
+ports = [8000, 8001, 8002]
+data = [["delta", "phi"], [3.14]]
+temp_targets = { cpu = 79.5, case = 72.0 }
+
+# [servers] yq can't do this one yet
+[servers.alpha]
+ip = "10.0.0.1"
+role = "frontend"
+
+[servers.beta]
+ip = "10.0.0.2"
+role = "backend"
+
+```
+then
+```bash
+yq '.' sample.toml
+```
+will output
+```yaml
+# This is a TOML document
+title = "TOML Example"
+
+[owner]
+name = "Tom Preston-Werner"
+dob = 1979-05-27T07:32:00-08:00
+
+[database]
+enabled = true
+ports = [8000, 8001, 8002]
+data = [["delta", "phi"], [3.14]]
+temp_targets = { cpu = 79.5, case = 72.0 }
+
+# [servers] yq can't do this one yet
+[servers.alpha]
+ip = "10.0.0.1"
+role = "frontend"
+
+[servers.beta]
+ip = "10.0.0.2"
+role = "backend"
+```
+
+## Encode: Simple mapping produces table section
+Given a sample.yml file of:
+```yaml
+arg:
+  hello: foo
+
+```
+then
+```bash
+yq -o toml '.' sample.yml
+```
+will output
+```toml
+[arg]
+hello = "foo"
+```
+