suyiiyii/yq
1
0
Fork 0
mirror of https://github.com/mikefarah/yq.git synced 2026-06-28 07:57:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
dc4b4ea1df
yq/pkg/yqlib/doc/usage/toml.md
Copilot 2927a28283
TOML encoder: prefer readable table sections over inline tables (#2649) 
* Initial plan

* Fix TOML encoder to prefer readable table sections over inline tables

When converting from YAML/JSON to TOML, the encoder now always uses
readable TOML table section syntax ([section]) instead of compact inline
hash table syntax (key = { ... }), which better matches TOML's goal as
a human-focused configuration format.

Changes:
- decoder_toml.go: Mark inline TOML tables with FlowStyle so round-trips
  can be distinguished from YAML flow mappings
- encoder_toml.go:
  - encodeTopLevelEntry: use FlowStyle check instead of EncodeSeparate to
    decide inline vs table section (all block mappings now become tables)
  - encodeSeparateMapping: count FlowStyle children as attributes; use
    recursive encodeSeparateMapping for nested non-flow mappings
  - encodeMappingBodyWithPath: emit non-flow child mappings as sub-table
    sections instead of inline tables
- toml_test.go: add encode (YAML→TOML) test scenarios, update roundtrip
  expectations for inline tables (now expanded to table sections)

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/4824a219-6d5e-42e7-bca1-a8a277bf8c6a

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>

* Fix TOML roundtrip: use TomlInline flag instead of FlowStyle to preserve inline tables

FlowStyle affected YAML decode output (causing inline tables to appear as
YAML flow mappings). Replace it with a new TOML-specific TomlInline bool
on CandidateNode that:
- Is set by the TOML decoder for inline tables (not FlowStyle)
- Is copied by UpdateAttributesFrom so it survives DeeplyAssign merges
- Is checked by the TOML encoder alongside FlowStyle (for YAML flow maps)
- Has no effect on the YAML encoder, preserving existing TOML→YAML output

TOML roundtrip tests are restored to their original expected values (inline
tables stay inline, table sections stay as sections).

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/f59bdf62-6d16-4664-991b-38eb87c9d81c

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>

* Refactor EncodeSeparate+TomlInline into a single EncodeHint enum

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/24db9a8f-601d-4ccf-ada7-129ed3226bb6

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>

* Fix stale comment in hasStructuralChildren

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/24db9a8f-601d-4ccf-ada7-129ed3226bb6

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>

* Remove unused hasStructuralChildren method from tomlEncoder

Agent-Logs-Url: https://github.com/mikefarah/yq/sessions/2c234b77-28e9-4995-ba6f-9d213ec551a0

Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mikefarah <1151925+mikefarah@users.noreply.github.com>
2026-04-12 18:36:43 +10:00

5.1 KiB
Raw Blame History

TOML

Decode from TOML. Note that yq does not yet support outputting in TOML format (and therefore it cannot roundtrip)

Parse: Simple

Given a sample.toml file of:

A = "hello"
B = 12

then

yq -oy '.' sample.toml

will output

A: hello
B: 12

Parse: Deep paths

Given a sample.toml file of:

person.name = "hello"
person.address = "12 cat st"

then

yq -oy '.' sample.toml

will output

person:
  name: hello
  address: 12 cat st

Encode: Scalar

Given a sample.toml file of:

person.name = "hello"
person.address = "12 cat st"

then

yq '.person.name' sample.toml

will output

hello

Parse: inline table

Given a sample.toml file of:

name = { first = "Tom", last = "Preston-Werner" }

then

yq -oy '.' sample.toml

will output

name:
  first: Tom
  last: Preston-Werner

Parse: Array Table

Given a sample.toml file of:


[owner.contact]
name = "Tom Preston-Werner"
age = 36

[[owner.addresses]]
street = "first street"
suburb = "ok"

[[owner.addresses]]
street = "second street"
suburb = "nice"

then

yq -oy '.' sample.toml

will output

owner:
  contact:
    name: Tom Preston-Werner
    age: 36
  addresses:
    - street: first street
      suburb: ok
    - street: second street
      suburb: nice

Parse: Array of Array Table

Given a sample.toml file of:


[[fruits]]
name = "apple"
[[fruits.varieties]]  # nested array of tables
name = "red delicious"

then

yq -oy '.' sample.toml

will output

fruits:
  - name: apple
    varieties:
      - name: red delicious

Parse: Empty Table

Given a sample.toml file of:


[dependencies]

then

yq -oy '.' sample.toml

will output

dependencies: {}

Roundtrip: inline table attribute

Given a sample.toml file of:

name = { first = "Tom", last = "Preston-Werner" }

then

yq '.' sample.toml

will output

name = { first = "Tom", last = "Preston-Werner" }

Roundtrip: table section

Given a sample.toml file of:

[owner.contact]
name = "Tom"
age = 36

then

yq '.' sample.toml

will output

[owner.contact]
name = "Tom"
age = 36

Roundtrip: array of tables

Given a sample.toml file of:

[[fruits]]
name = "apple"
[[fruits.varieties]]
name = "red delicious"

then

yq '.' sample.toml

will output

[[fruits]]
name = "apple"
[[fruits.varieties]]
name = "red delicious"

Roundtrip: arrays and scalars

Given a sample.toml file of:

A = ["hello", ["world", "again"]]
B = 12

then

yq '.' sample.toml

will output

A = ["hello", ["world", "again"]]
B = 12

Roundtrip: simple

Given a sample.toml file of:

A = "hello"
B = 12

then

yq '.' sample.toml

will output

A = "hello"
B = 12

Roundtrip: deep paths

Given a sample.toml file of:

[person]
name = "hello"
address = "12 cat st"

then

yq '.' sample.toml

will output

[person]
name = "hello"
address = "12 cat st"

Roundtrip: empty array

Given a sample.toml file of:

A = []

then

yq '.' sample.toml

will output

A = []

Roundtrip: sample table

Given a sample.toml file of:

var = "x"

[owner.contact]
name = "Tom Preston-Werner"
age = 36

then

yq '.' sample.toml

will output

var = "x"

[owner.contact]
name = "Tom Preston-Werner"
age = 36

Roundtrip: empty table

Given a sample.toml file of:

[dependencies]

then

yq '.' sample.toml

will output

[dependencies]

Roundtrip: comments

Given a sample.toml file of:

# This is a comment
A = "hello"  # inline comment
B = 12

# Table comment
[person]
name = "Tom"  # name comment

then

yq '.' sample.toml

will output

# 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:

# 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

yq '.' sample.toml

will output

# 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:

arg:
  hello: foo

then

yq -o toml '.' sample.yml

will output

[arg]
hello = "foo"