# TOML // :toc: // Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key :toclevels: 4 [cols="1^,1^,1^",options=header] |=== | source | condition | target | ✔ | ✔ | ✔ |=== == Description The `toml` resource reads and writes a single value in a TOML document, addressed by a link:https://daseldocs.tomwright.me/[Dasel] selector. **source**:: Reads one value out of one file. Only a single file is accepted. **condition**:: Compares the value to `value`, or to the source output when `value` is unset. **target**:: Writes the value at the given key. Files already holding it are reported as up to date and left untouched. == Parameters {{< resourceparameters "sources" "toml" >}} `file` or `files` is mandatory, as is `key` or `query`; missing either aborts the run with `wrong spec content`. `file` and `files` are mutually exclusive. `createmissingkey`:: Target only. Creates the key when it does not exist instead of failing. Only works together with `key`, and **not** with the `dasel/v3` engine (that combination is rejected at validation time with `engine "dasel/v3" does not support the parameter "createmissingkey"`, because the v3 API resolves the key before setting a value). NOTE: `multiple` is deprecated and hidden from the table above. Use a selector returning several values instead. == Engines `engine` selects which version of Dasel parses the file, and the selector syntax is not portable between versions. [cols="1,3",options=header] |=== | Value | Behaviour | `dasel/v1` | Default when `engine` is unset. Deprecated - every run logs a warning. | `dasel/v2` | Deprecated - every run logs a warning. | `dasel/v3` | Current engine. Rejects the leading dot: use `package.version`, not `.package.version`. Incompatible with `createmissingkey`. | `dasel` | Alias resolving to the latest engine, currently `dasel/v3`. |=== WARNING: `query` is a `dasel/v1` parameter. On `dasel/v2` and `dasel/v3`, a `query` without a `key` fails validation with `engine "dasel/v3" requires the parameter "key" over "query"`. On `dasel/v1`, `query` is the multi-value form and must be paired with `versionfilter` in a source. == Remote files `file` accepts `https://`, `http://` and `file://` for a source and a condition. A target refuses a URL outright with `URL scheme is not supported for TOML target`. == Limitations Dasel rewrites the file from its parsed representation, so **comments are dropped** on any target that changes something - see link:https://github.com/TomWright/dasel/issues/178[tomwright/dasel#178]. This bites hardest on hand-maintained files such as `netlify.toml` or `Cargo.toml`. The workaround is to drive the edit with the link:/docs/plugins/resource/file/["File" resource], matching the line with a regular expression so only those bytes are rewritten: [source,yaml] ---- # updatecli.yaml {{}} ---- == Example [source,yaml] ---- # updatecli.yaml {{}} ---- == Links * link:https://daseldocs.tomwright.me/[Dasel documentation] * link:/docs/core/versionfilter/["Version Filtering" page]