examples.md

Examples

This page shows common disassembly layouts using small file-tree diagrams. The examples focus on how files are split on disk and how to reassemble them.

Try it now

Copy this file as config.json and use it to follow any example on this page:

{
  "name": "demo",
  "enabled": true,
  "settings": {
    "retry": 3,
    "timeout_ms": 5000
  },
  "tags": ["alpha", "beta"]
}

Run the complete round-trip:

config-disassembler json disassemble config.json
config-disassembler json reassemble config

The reassembled file matches the original structure. That's it.

---

JSON Object

Input config.json:

{
  "name": "demo",
  "enabled": true,
  "settings": {
    "retry": 3,
    "timeout_ms": 5000
  },
  "tags": ["alpha", "beta"]
}

Disassemble:

config-disassembler json disassemble config.json

Output:

config/
├── .config-disassembler.json
├── _main.json
├── settings.json
└── tags.json

_main.json contains scalar top-level keys:

{
  "name": "demo",
  "enabled": true
}

settings.json contains the nested object:

{
  "retry": 3,
  "timeout_ms": 5000
}

Reassemble:

config-disassembler json reassemble config

Array Root With Unique IDs

Input items.yaml:

- name: alpha
  weight: 1
- name: beta
  weight: 2
- name: gamma
  weight: 3

Disassemble and name each file from the name field:

config-disassembler yaml disassemble items.yaml --unique-id name

Output:

items/
├── .config-disassembler.json
├── alpha.yaml
├── beta.yaml
└── gamma.yaml

alpha.yaml:

name: alpha
weight: 1

Reassemble:

config-disassembler yaml reassemble items

Cross-Format Split Files

JSON, JSON5, JSONC, YAML, and TOON can be split into any format in that family and reassembled back into any other format in that family.

Disassemble JSON into YAML split files:

config-disassembler json disassemble config.json --output-format yaml

Output:

config/
├── .config-disassembler.json
├── _main.yaml
├── settings.yaml
└── tags.yaml

Reassemble the YAML split files back to JSON:

config-disassembler json reassemble config --output-format json

JSONC Preserving Comments

When JSONC is disassembled to JSONC and reassembled as JSONC, comments and trailing commas are preserved.

Input config.jsonc:

{
  // Scalars stay in _main.jsonc.
  "name": "demo",
  "settings": {
    "retry": 3,
    "features": [
      "comments",
      "trailing-commas",
    ],
  },
}

Disassemble:

config-disassembler jsonc disassemble config.jsonc

Output:

config/
├── .config-disassembler.json
├── _main.jsonc
└── settings.jsonc

_main.jsonc:

{
  // Scalars stay in _main.jsonc.
  "name": "demo",
}

settings.jsonc:

{
    "retry": 3,
    "features": [
      "comments",
      "trailing-commas",
    ],
  }

Reassemble:

config-disassembler jsonc reassemble config

Cross-format JSONC conversions preserve parsed values, but JSONC-specific syntax such as comments and trailing commas cannot be carried through formats like YAML or JSON.

TOML And INI Are Same-Format Only

TOML can only be disassembled to TOML and reassembled to TOML.

Input config.toml:

title = "Demo"
enabled = true

[database]
server = "localhost"
ports = [8001, 8002]

Disassemble:

config-disassembler toml disassemble config.toml

Output:

config/
├── .config-disassembler.json
├── _main.toml
└── database.toml

Reassemble:

config-disassembler toml reassemble config

Cross-format TOML conversion is rejected because TOML cannot represent all values from the JSON-style family, such as null values or array document roots.

INI is grouped with the same table-document behavior, but remains INI-only because section values are strings or valueless keys and INI cannot represent arrays or deeper nesting.

Input config.ini:

name = demo
enabled

[database]
server = localhost
port = 5432

Disassemble:

config-disassembler ini disassemble config.ini

Output:

config/
├── .config-disassembler.json
├── _main.ini
└── database.ini

database.ini keeps the section wrapper so the split file is a valid INI document:

[database]
server=localhost
port=5432

Reassemble:

config-disassembler ini reassemble config

Directory Input With .cdignore

Every disassemble action can process a directory. Matching config files are disassembled in place, and each file gets a sibling directory named after its stem.

Input tree:

configs/
├── .cdignore
├── app.json
├── generated/
│   └── ignored.json
└── service.json

.cdignore:

generated/

Disassemble all JSON files not ignored by .cdignore:

config-disassembler json disassemble configs

Output:

configs/
├── .cdignore
├── app.json
├── app/
│   ├── .config-disassembler.json
│   └── ...
├── generated/
│   └── ignored.json
├── service.json
└── service/
    ├── .config-disassembler.json
    └── ...

XML Unique-ID Strategy

XML uses the xml subcommand and can split nested elements into XML, JSON, JSON5, or YAML files. The default strategy writes one file per nested element using a unique identifier when possible.

config-disassembler xml disassemble metadata.xml --unique-id-elements name,id

Example output:

metadata/
├── Account.objectPermissions-meta.xml
├── Contact.objectPermissions-meta.xml
└── metadata-meta.xml

Reassemble:

config-disassembler xml reassemble metadata

XML Grouped-By-Tag Strategy

Use grouped-by-tag when you want fewer files and one file per repeated tag.

config-disassembler xml disassemble metadata.xml --strategy grouped-by-tag --format yaml

Example output:

metadata/
├── fieldPermissions.yaml
├── objectPermissions.yaml
└── metadata.yaml

Reassemble:

config-disassembler xml reassemble metadata