Title here
Summary here
TOML
| source | condition | target |
|---|---|---|
✔ | ✔ | ✔ |
Description
The toml resource reads and writes a single value in a TOML document, addressed by a 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 whenvalueis unset.- target
Writes the value at the given key. Files already holding it are reported as up to date and left untouched.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| createmissingkey | boolean | [t] CreateMissingKey allows non-existing keys. If the key does not exist, the key is created if AllowsMissingKey is true, otherwise an error is raised (the default). Only supported if Key is used. Not supported by the “dasel/v3” engine, which cannot create missing keys. | |
| file | string | [s][c][t] File specifies the toml file to manipulate | |
| files | array | [c][t] Files specifies a list of Json file to manipulate | |
| key | string | [s][c][t] Key specifies the query to retrieve an information from a toml file | |
| query | string | [s][c][t] Query allows to used advanced query. Override the parameter key | |
| value | string | [s][c][t] Value specifies the value for a specific key. Default to source output | |
| versionfilter | object | [s] VersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest. | |
| kind | string | specifies the version kind such as semver, regex, or latest | |
| pattern | string | specifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format | |
| regex | string | specifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used. | |
| replaceall | object | replaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction. | |
| strict | boolean | strict enforce strict versioning rule. Only used for semantic versioning at this time |
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.
createmissingkeyTarget only. Creates the key when it does not exist instead of failing. Only works together with
key, and not with thedasel/v3engine (that combination is rejected at validation time withengine "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.
| Value | Behaviour |
|---|---|
| Default when |
| Deprecated - every run logs a warning. |
| Current engine. Rejects the leading dot: use |
| Alias resolving to the latest engine, currently |
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 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 "File" resource, matching the line with a regular expression so only those bytes are rewritten:
# updatecli.yaml
name: Fallback example with TOML
sources:
hugo:
name: Get latest HUGO version
kind: githubrelease
transformers:
- trimprefix: v
spec:
owner: gohugoio
repository: hugo
token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'
username: '{{ requiredEnv "UPDATECLI_GITHUB_ACTOR" }}'
targets:
netlify:
name: Update Hugo version used on Netlify
kind: file
spec:
file: netlify.toml
matchpattern: HUGO_VERSION = "(.*)"
replacepattern: HUGO_VERSION = "{{ source "hugo" }}"
scmid: default
sourceid: hugo
Example
# updatecli.yaml
name: Basic TOML Example
sources:
local:
name: Get value from toml
kind: toml
spec:
file: pkg/plugins/resources/toml/testdata/data.toml
key: .owner.firstName
conditions:
local:
name: Test value from toml
kind: toml
spec:
file: pkg/plugins/resources/toml/testdata/data.toml
key: .owner.firstName
targets:
local:
name: Ensure owner.firstName is set to John
kind: toml
spec:
file: pkg/plugins/resources/toml/testdata/data.toml
key: .owner.firstName
value: John
Next
Tool Versions