Detailed guide on using dasel, a versatile command-line tool for querying and modifying data structures, focusing on its powerful selection syntax and operators. This guide is designed to help you understand and utilize dasel effectively in various scenarios.
#Introduction to Dasel
Dasel (Data-Selector) is a command-line utility that simplifies the process of querying and modifying data in various formats, including JSON, YAML, TOML, and XML. It employs a unified selector syntax, allowing users to seamlessly switch between different data formats without learning new query languages.
#Installation
Before using dasel, ensure it’s installed on your system. You can download the latest binary for your platform from the official GitHub releases page or use package managers like brew for macOS:
brew install dasel
#Basic Usage
The fundamental operation of dasel involves specifying the file (-f flag) and the query. Here’s the general syntax:
dasel -f <file> -r <format> <selector>
-f: Path to the input file.-r: The parser format to use when reading the file. Can bejson,yaml,toml, orxml.<selector>: The query used to select data from the file.
#Selectors and Operators
Dasel selectors are used to navigate through the data structure. Here are some of the key operators and their uses:
-
Property Access: Access properties of an object or fields of a map by name.
.propertyName -
Array Indexing: Access an element of an array using its zero-based index.
.arrayName.[index] -
All Elements: To select all elements of an array, use
.all()..arrayName.all() -
Filtering:
Daselsupports filtering arrays based on conditions..arrayName.all().filter(<condition>)Conditions can include checks for the presence of a field, value comparisons, and more.
#Examples
-
Selecting a Single Property
To select the
nameproperty from a JSON file:dasel -f data.json '.name' -
Accessing Array Elements
To get the third item from an array named
items:dasel -f data.json '.items.[2]' -
Selecting All Elements of an Array
To select all elements within an array
users:dasel -f data.json '.users.all()' -
Filtering Based on Conditions
To find all users with a non-empty
namefield:dasel -f data.json '.users.all().filter(name?.len())' -
Selecting Nested Properties
To select the
nameproperty within thedocumentobject of eachsegmentin all records:dasel -f data.json '.records.all().segment.document.name'
#REFERENCE
Directory structure:
└── tomwright-dasel-docs/
├── README.md
├── installation.md
├── memory-usage.md
├── SUMMARY.md
├── supported-file-formats.md
├── commands/
│ ├── delete.md
│ ├── put.md
│ └── select.md
├── examples/
│ ├── basics.md
│ ├── change-file-format.md
│ ├── filtering-objects-based-on-present-missing-key.md
│ └── using-dasel-as-a-go-package.md
└── functions/
├── all.md
├── and.md
├── append.md
├── count.md
├── equal.md
├── filter.md
├── filteror.md
├── first.md
├── index.md
├── join.md
├── key.md
├── keys.md
├── last.md
├── len.md
├── lessthan.md
├── mapof.md
├── merge.md
├── morethan.md
├── not.md
├── null.md
├── or.md
├── ordefault.md
├── parent.md
├── property.md
├── selector-overview.md
├── string.md
├── this.md
└── type.md
================================================
FILE: README.md
================================================
# Introduction
{% hint style="warning" %}
You are viewing dasel v2 documentation.
{% endhint %}
## Introduction
Dasel (short for data-selector) allows you to query and modify data structures using selector strings.
### One tool to rule them all <a href="#one-tool-to-rule-them-all" id="one-tool-to-rule-them-all"></a>
Say good bye to learning new tools just to work with a different data format.Dasel uses a standard selector syntax no matter the data format. This means that once you learn how to use dasel you immediately have the ability to query/modify any of the supported data types without any additional tools or effort.
## V1 to V2 breaking changes
This release does introduce a major version upgrade, and as such there are breaking changes.
### Select command
The select command remains largely the same, but the selector format has changed a lot. See selector changes below.
* Removal of `-p`,`--parser`. Please use `-r`,`--read` and `-w`,`--write`.
* Note that if no `-w` is given, the value of `-r` is used.
* `dasel -p json ...` becomes `dasel -r json ...`
* Removal of `--format` flag.
* I plan on implementing this as a custom write parser instead.
* Removal of `-m`,`--multi` flag. All selectors now act in this manner.
* Removal of `-c`, `--compact` flag. Use `--pretty=false` instead.
### Put command
* Removal of sub commands (e.g. `dasel put string`).
* Dasel now expects a `dasel put` command to have a `-t`,`--type` flag that specified the type.
* If the given type doesn't match a pre-defined type (`string`, `int`, etc) it is checked against the read parsers (e.g. `json`, `yaml`). This is how you can achieve the previous `put document` functionality.
* Complete removal of `dasel put object`. Please use `dasel put -t json` or similar to achieve the same outcome.
* Removal of `-p`,`--parser`. Please use `-r`,`--read` and `-w`,`--write`.
* Note that if no `-w` is given, the value of `-r` is used.
* `dasel -p json ...` becomes `dasel -r json ...`
* Removal of `-m`,`--multi` flag. All selectors now act in this manner.
* Removal of `-c`, `--compact` flag. Use `--pretty=false` instead.
### Delete command
The delete command remains largely the same, but the selector format has changed a lot. See selector changes below.
* Removal of `-p`,`--parser`. Please use `-r`,`--read` and `-w`,`--write`.
* Note that if no `-w` is given, the value of `-r` is used.
* `dasel -p json ...` becomes `dasel -r json ...`
* Removal of `-m`,`--multi` flag. All selectors now act in this manner.
* Removal of `-c`, `--compact` flag. Use `--pretty=false` instead.
### Update command
The self-update functionality within dasel has been completely removed. Please use package managers to achieve this functionality.
### Selector changes
Dasel selectors have been completely reworked.
The purpose of this is to allow users to build their own complex logic and filtering without needing specific code being written to handle their use-case.
Please see the [function overview](broken-reference) for function documentation and examples.
================================================
FILE: installation.md
================================================
# Installation
## Homebrew
The easiest way to get your hands on the latest version of dasel is to use homebrew:
```shell
brew install dasel
```
## Docker
Run dasel in docker using the image `ghcr.io/tomwright/dasel`.
### Usage
Run the docker image, passing in a dasel command with the executable excluded.
```shell
$ echo '{"name": "Tom"}' | docker run -i --rm ghcr.io/tomwright/dasel:latest -r json '.name'
"Tom"
```
### Versioning
New image versions are built and pushed automatically as part of the CI/CD pipeline in Github actions.
| Tag | Description |
| ------------- | ------------------------------------------- |
| `latest` | The latest release version. |
| `development` | The latest build from `master` branch. |
| `v*.*.*` | The specified dasel release. E.g. `v2.0.0`. |
## ASDF
Using [asdf-vm](https://asdf-vm.com) and the [asdf-dasel plugin](https://github.com/asdf-community/asdf-dasel?ts=4).
```shell
asdf plugin add dasel https://github.com/asdf-community/asdf-dasel.git
asdf list all dasel
asdf install dasel <version>
asdf global dasel <version>
```
## Nix
To install using the [Nix Package Manager](https://nixos.org) (for non-NixOS)
```shell
nix-env -iA nixpkgs.dasel
```
Or NixOS:
```shell
nix-env -iA nixos.dasel
```
## Windows
See [manual install](installation.md#manual).
## Manual
You can download a compiled executable from the [latest release](https://github.com/TomWright/dasel/releases/latest).
{% hint style="info" %}
Don't forget to put the binary somewhere in your `PATH`.
{% endhint %}
{% tabs %}
{% tab title="Linux (64 bit)" %}
```
curl -sSLf "$(curl -sSLf https://api.github.com/repos/tomwright/dasel/releases/latest | grep browser_download_url | grep linux_amd64 | grep -v .gz | cut -d\" -f 4)" -L -o dasel && chmod +x dasel
mv ./dasel /usr/local/bin/dasel
```
{% endtab %}
{% tab title="Mac OS (64 bit)" %}
```
curl -sSLf "$(curl -sSLf https://api.github.com/repos/tomwright/dasel/releases/latest | grep browser_download_url | grep -v .gz | grep darwin_amd64 | cut -d\" -f 4)" -L -o dasel && chmod +x dasel
mv ./dasel /usr/local/bin/dasel
```
{% endtab %}
{% tab title="Windows" %}
```powershell
$releases = curl -sSLf https://api.github.com/repos/tomwright/dasel/releases/latest
Invoke-WebRequest -Uri (($releases | ConvertFrom-Json).assets `
| Where-Object { $_.name -eq "dasel_windows_amd64.exe" } `
| Select-Object -ExpandProperty browser_download_url) `
-OutFile dasel.exe
```
{% endtab %}
{% endtabs %}
## Scoop
Use the scoop command-line installer to install dasel on windows 10.
```shell
scoop bucket add extras
scoop install dasel
```
## Development Version
You can `go install` the `cmd/dasel` package to build and install dasel for you.
{% hint style="info" %}
You may need to prefix the command with `GO111MODULE=on` in order for this to work.
{% endhint %}
```
go install github.com/tomwright/dasel/v2/cmd/dasel@master
```
================================================
FILE: memory-usage.md
================================================
# Memory usage
Dasel does not perform partial reads or streaming. As a result the dasel executable will read the entire given document into memory.
You should be aware that dasel will attempt to allocate a lot of memory if you are processing very large documents.
================================================
FILE: SUMMARY.md
================================================
# Table of contents
* [Introduction](README.md)
* [GitHub](https://github.com/TomWright/dasel)
* [Supported file formats](supported-file-formats.md)
* [Memory usage](memory-usage.md)
* [Installation](installation.md)
## Commands
* [Select](commands/select.md)
* [Put](commands/put.md)
* [Delete](commands/delete.md)
## Functions
* [Selector Overview](functions/selector-overview.md)
* [All](functions/all.md)
* [And](functions/and.md)
* [Append](functions/append.md)
* [Count](functions/count.md)
* [Equal](functions/equal.md)
* [Filter](functions/filter.md)
* [FilterOr](functions/filteror.md)
* [First](functions/first.md)
* [Index](functions/index.md)
* [Join](functions/join.md)
* [Key](functions/key.md)
* [Keys](functions/keys.md)
* [Last](functions/last.md)
* [Len](functions/len.md)
* [LessThan](functions/lessthan.md)
* [MapOf](functions/mapof.md)
* [Merge](functions/merge.md)
* [MoreThan](functions/morethan.md)
* [Not](functions/not.md)
* [Or](functions/or.md)
* [OrDefault](functions/ordefault.md)
* [Parent](functions/parent.md)
* [Property](functions/property.md)
* [String](functions/string.md)
* [Null](functions/null.md)
* [This](functions/this.md)
* [Type](functions/type.md)
## Examples
* [Using dasel as a go package](examples/using-dasel-as-a-go-package.md)
* [Basics](examples/basics.md)
* [Change file format](examples/change-file-format.md)
* [Filtering objects based on present/missing key](examples/filtering-objects-based-on-present-missing-key.md)
================================================
FILE: supported-file-formats.md
================================================
# Supported file formats
Dasel supports the following file formats:
* `json`
* `yaml`
* Merge tags/aliases are supported in reads from `v2.8.0`.
* `csv`
* `toml` [v1.0.0](https://toml.io/en/v1.0.0)
* `xml`
* `-` (plain, write-only)
Note that
* Some format specific features such as comments may not be present in dasel output.
* Array ordering is not guaranteed. The JSON spec for example doesn't guarantee ordering. As a result dasel cannot either.
* The plain (`-`) parser can only be used when writing.
================================================
FILE: commands/delete.md
================================================
# Delete
The delete command allows you to delete data in any supported data structure.
## Usage
```
$ echo '{"name":{"first":"Tom","last":"Wright"}}' |
dasel delete -r json 'name.last'
{
"name": {
"first": "Frank"
}
}
```
See the [function documentation](broken-reference) for information on the available selectors.
## Flags/Args
<table><thead><tr><th width="214">Flag</th><th width="128">Type</th><th width="308.3333333333333">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>--colour</code></td><td><code>bool</code></td><td>Print colourised output.</td><td><code>false</code></td></tr><tr><td><code>--escape-html</code></td><td><code>bool</code></td><td>Escape HTML tags when writing output.</td><td><code>false</code></td></tr><tr><td><code>-f</code>, <code>--file</code></td><td><code>string</code></td><td>The file to query.<br>If no file is given dasel reads from <code>stdin</code>.</td><td></td></tr><tr><td><code>-o</code>, <code>--out</code></td><td><code>string</code></td><td>The file to write results to.<br>If no file is given dasel writes to <code>--file</code>.<br>If <code>--file</code> is <code>stdin</code>, dasel writes to <code>stdout</code>.</td><td></td></tr><tr><td><code>--pretty</code></td><td><code>bool</code></td><td>Pretty print the output.</td><td><code>true</code></td></tr><tr><td><code>-r</code>, <code>--read</code></td><td><code>string</code></td><td>The parser to use when reading.<br>If no parser is given dasel attempts to find a parser from the <code>--file</code> flag.</td><td></td></tr><tr><td><code>-s</code>, <code>--selector</code></td><td><code>string</code></td><td>The selector used to query the input data.<br>If no flag is given dasel attempts to use the first argument as the selector.</td><td></td></tr><tr><td><code>-w</code>, <code>--write</code></td><td><code>string</code></td><td>The parser to use when writing.<br>If no parser is given dasel attempts to find a parser from the <code>--out</code> flag.<br>If no <code>--out</code> flag is given dasel uses the <code>--read</code> flag.</td><td></td></tr><tr><td><code>--csv-comma</code></td><td><code>string</code></td><td>The separator used when working with csv files.</td><td><code>,</code></td></tr><tr><td><code>--csv-write-comma</code></td><td><code>string</code></td><td>The separator used when writing csv files.</td><td>value of <code>--csv-comma</code> </td></tr><tr><td><code>--csv-comment</code></td><td><code>string</code></td><td>The comment character used when working with csv files.</td><td></td></tr><tr><td><code>--csv-crlf</code></td><td><code>bool</code></td><td>True to write csv files with a <code>\r\n</code> instead of <code>\n.</code></td><td><code>false</code></td></tr></tbody></table>
================================================
FILE: commands/put.md
================================================
# Put
The put command allows you to modify data in any supported data structure.
## Usage
```
$ echo '{"name":{"first":"Tom","last":"Wright"}}' |
dasel put -r json -t string -v Frank 'name.first'
{
"name": {
"first": "Frank",
"last": "Wright"
}
}
```
See the [function documentation](broken-reference) for information on the available selectors.
## Flags/Args
<table><thead><tr><th width="214">Flag</th><th width="128">Type</th><th width="308.3333333333333">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>--colour</code></td><td><code>bool</code></td><td>Print colourised output.</td><td><code>false</code></td></tr><tr><td><code>--escape-html</code></td><td><code>bool</code></td><td>Escape HTML tags when writing output.</td><td><code>false</code></td></tr><tr><td><code>-f</code>, <code>--file</code></td><td><code>string</code></td><td>The file to query.<br>If no file is given dasel reads from <code>stdin</code>.</td><td></td></tr><tr><td><code>-o</code>, <code>--out</code></td><td><code>string</code></td><td>The file to write results to.<br>If no file is given dasel writes to <code>--file</code>.<br>If <code>--file</code> is <code>stdin</code>, dasel writes to <code>stdout</code>.</td><td></td></tr><tr><td><code>--pretty</code></td><td><code>bool</code></td><td>Pretty print the output.</td><td><code>true</code></td></tr><tr><td><code>-r</code>, <code>--read</code></td><td><code>string</code></td><td>The parser to use when reading.<br>If no parser is given dasel attempts to find a parser from the <code>--file</code> flag.</td><td></td></tr><tr><td><code>-s</code>, <code>--selector</code></td><td><code>string</code></td><td>The selector used to query the input data.<br>If no flag is given dasel attempts to use the first argument as the selector.</td><td></td></tr><tr><td><code>-t</code>, <code>--type</code></td><td><code>string</code></td><td>The type of value we are writing.<br>Can be <code>string</code>, <code>int</code> or <code>bool</code>. If it is not contained in that list dasel attempts to find a read parser of <code>--type</code> and if found will read the input value as a document.</td><td></td></tr><tr><td><code>-v</code>, <code>--value</code></td><td><code>string</code></td><td>The value to write.<br>This must be a string input but dasel will parse/convert the value to the given <code>--type</code> internally.</td><td></td></tr><tr><td><code>-w</code>, <code>--write</code></td><td><code>string</code></td><td>The parser to use when writing.<br>If no parser is given dasel attempts to find a parser from the <code>--out</code> flag.<br>If no <code>--out</code> flag is given dasel uses the <code>--read</code> flag.</td><td></td></tr><tr><td><code>--csv-comma</code></td><td><code>string</code></td><td>The separator used when working with csv files.</td><td><code>,</code></td></tr><tr><td><code>--csv-write-comma</code></td><td><code>string</code></td><td>The separator used when writing csv files.</td><td>value of <code>--csv-comma</code> </td></tr><tr><td><code>--csv-comment</code></td><td><code>string</code></td><td>The comment character used when working with csv files.</td><td></td></tr><tr><td><code>--csv-crlf</code></td><td><code>bool</code></td><td>True to write csv files with a <code>\r\n</code> instead of <code>\n.</code></td><td><code>false</code></td></tr></tbody></table>
================================================
FILE: commands/select.md
================================================
# Select
Select is the default command for the `dasel` cli.
The select command allows you to select data from any supported data structure.
## Usage
```
$ echo '{"name":{"first":"Tom","last":"Wright"}}' | dasel -r json 'name.first'
"Tom"
```
See the [function documentation](broken-reference) for information on the available selectors.
## Flags/Args
<table><thead><tr><th>Flag</th><th>Type</th><th width="249.33333333333331">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>--colour</code></td><td><code>bool</code></td><td>Print colourised output.</td><td><code>false</code></td></tr><tr><td><code>--escape-html</code></td><td><code>bool</code></td><td>Escape HTML tags when writing output.</td><td><code>false</code></td></tr><tr><td><code>-f</code>, <code>--file</code></td><td><code>string</code></td><td>The file to query.<br>If no file is given dasel reads from <code>stdin</code>.</td><td></td></tr><tr><td><code>--pretty</code></td><td><code>bool</code></td><td>Pretty print the output.</td><td><code>true</code></td></tr><tr><td><code>-r</code>, <code>--read</code></td><td><code>string</code></td><td>The parser to use when reading.<br>If no parser is given dasel attempts to find a parser from the <code>--file</code> flag.</td><td></td></tr><tr><td><code>-s</code>, <code>--selector</code></td><td><code>string</code></td><td>The selector used to query the input data.<br>If no flag is given dasel attempts to use the first argument as the selector.</td><td></td></tr><tr><td><code>-w</code>, <code>--write</code></td><td><code>string</code></td><td>The parser to use when writing.<br>If no parser is given dasel will use the <code>--read</code> flag.</td><td></td></tr><tr><td><code>--csv-comma</code></td><td><code>string</code></td><td>The separator used when working with csv files.</td><td><code>,</code></td></tr><tr><td><code>--csv-write-comma</code></td><td><code>string</code></td><td>The separator used when writing csv files.</td><td>value of <code>--csv-comma</code> </td></tr><tr><td><code>--csv-comment</code></td><td><code>string</code></td><td>The comment character used when working with csv files.</td><td></td></tr><tr><td><code>--csv-crlf</code></td><td><code>bool</code></td><td>True to write csv files with a <code>\r\n</code> instead of <code>\n.</code></td><td><code>false</code></td></tr></tbody></table>
================================================
FILE: examples/basics.md
================================================
# Basics
## Select
```
$ echo '{"name":"Tom"}' | dasel -r json 'name'
"Tom"
```
## Put
```
$ echo '{"name":"Tom"}' |
dasel put -r json -t string -v 'contact@tomwright.me' 'email'
{
"email": "contact@tomwright.me",
"name": "Tom"
}
```
## Delete
```
$ echo '{
"email": "contact@tomwright.me",
"name": "Tom"
}' | dasel delete -r json 'email'
{
"name": "Tom"
}
```
================================================
FILE: examples/change-file-format.md
================================================
# Change file format
Dasel allows you to quickly and easily change the format of a file.
## JSON to YAML
```
$ echo '{
"users": [
{
"name": "Tom"
},
{
"name": "Jim"
}
]
}' | dasel -r json -w yaml
users:
- name: Tom
- name: Jim
```
## YAML to CSV
```
$ echo 'users:
- name: Tom
- name: Jim' | dasel -r yaml -w csv 'users'
name
Tom
Jim
```
## CSV to JSON
```
$ echo 'name
Tom
Jim
' | dasel -r csv -w json
[
{
"name": "Tom"
},
{
"name": "Jim"
}
]
```
================================================
FILE: examples/filtering-objects-based-on-present-missing-key.md
================================================
# Filtering objects based on present/missing key
## Find users that have a non-empty `name` field.
```sh
$ echo '{
"users": [
{
"name": "Tom"
},
{
"name": "false"
},
{
"name": true
},
{
"wrong_name": "Jim"
},
{
"name": ""
}
]
}' | dasel -r json 'users.all().filter(name?.len())'
{
"name": "Tom"
}
{
"name": "false"
}
{
"name": true
}
```
## Find users with an empty or missing `name` field.
```sh
$ echo '{
"users": [
{
"name": "Tom"
},
{
"name": "false"
},
{
"name": true
},
{
"wrong_name": "Jim"
},
{
"name": ""
}
]
}' | dasel -r json 'users.all().filter(not(name?.len()))'
{
"wrong_name": "Jim"
}
{
"name": ""
}
```
## Find users with a `name` field
```sh
$ echo '{
"users": [
{
"name": "Tom"
},
{
"name": "false"
},
{
"name": true
},
{
"wrong_name": "Jim"
},
{
"name": ""
}
]
}' | dasel -r json 'users.all().filter(keys().all().filter(equal(.,name)))'
{
"name": "Tom"
}
{
"name": "false"
}
{
"name": true
}
{
"name": ""
}
```
## Find users without a `name` field
```shell
$ echo '{
"users": [
{
"name": "Tom"
},
{
"name": "false"
},
{
"name": true
},
{
"wrong_name": "Jim"
},
{
"name": ""
}
]
}' | dasel -r json 'users.all().filter(not(keys().all().filter(equal(.,name)).len()))'
{
"wrong_name": "Jim"
}
```
================================================
FILE: examples/using-dasel-as-a-go-package.md
================================================
# Using dasel as a go package
## Getting a root node
You can convert values into something usable by `dasel` with [`dasel.ValueOf`](https://github.com/TomWright/dasel/blob/09ffcb6c1f500c1a9cd231684d7830d4c6a3a2a2/value.go#L18).
```go
myValue := map[string]any{
"name": "Tom"
}
rootNode := dasel.ValueOf(myValue)
```
It's worth mentioning that this step isn't required because the commands listed below will do this conversion internally.
## Running commands
### [Select](https://github.com/TomWright/dasel/blob/09ffcb6c1f500c1a9cd231684d7830d4c6a3a2a2/context.go#L115)
```go
func main() {
myValue := map[string]any{
"firstName": "Tom",
"lastName": "Wright",
}
values, err := dasel.Select(myValue, "firstName")
if err != nil {
log.Fatalf("could not select: %s", err)
}
results := values.Interfaces()
stringResults := make([]string, len(results))
for k, v := range results {
stringResults[k] = fmt.Sprint(v)
}
fmt.Printf("select result: %s", strings.Join(stringResults, ", "))
// select result: Tom
}
```
### [Put](https://github.com/TomWright/dasel/blob/09ffcb6c1f500c1a9cd231684d7830d4c6a3a2a2/context.go#L127C6-L127C9)
```go
func main() {
myValue := map[string]any{
"firstName": "Tom",
"lastName": "Wright",
}
result, err := dasel.Put(myValue, "firstName", "Hello")
if err != nil {
log.Fatalf("could not select: %s", err)
}
fmt.Printf("original value: %v\n", myValue)
fmt.Printf("put result: %v", result.Interface())
// original value: map[firstName:Tom lastName:Wright]
// put result: map[firstName:Hello lastName:Wright]
}
```
Note that if you pass a pointer, the original value also gets updated.
```go
func main() {
myValue := map[string]any{
"firstName": "Tom",
"lastName": "Wright",
}
result, err := dasel.Put(&myValue, "firstName", "Hello")
if err != nil {
log.Fatalf("could not select: %s", err)
}
fmt.Printf("original value: %v\n", myValue)
fmt.Printf("put result: %v", result.Interface())
// original value: map[firstName:Hello lastName:Wright]
// put result: map[firstName:Hello lastName:Wright]
}
```
### [Delete](https://github.com/TomWright/dasel/blob/09ffcb6c1f500c1a9cd231684d7830d4c6a3a2a2/context.go#L143)
```go
func main() {
myValue := map[string]any{
"firstName": "Tom",
"lastName": "Wright",
}
result, err := dasel.Delete(myValue, "firstName")
if err != nil {
log.Fatalf("could not select: %s", err)
}
fmt.Printf("original value: %v\n", myValue)
fmt.Printf("put result: %v", result.Interface())
// original value: map[firstName:Tom lastName:Wright]
// put result: map[lastName:Wright]
}
```
Note that if you pass a pointer, the original value also gets updated.
```go
func main() {
myValue := map[string]any{
"firstName": "Tom",
"lastName": "Wright",
}
result, err := dasel.Delete(&myValue, "firstName")
if err != nil {
log.Fatalf("could not select: %s", err)
}
fmt.Printf("original value: %v\n", myValue)
fmt.Printf("put result: %v", result.Interface())
// original value: map[lastName:Wright]
// put result: map[lastName:Wright]
}
```
================================================
FILE: functions/all.md
================================================
# All
All takes any list or object value and extracts each element within it, allowing you to access each of them individually.
## Examples
### Lists
```
echo '["a", "b", "c"]' | dasel -r json
[
"a",
"b",
"c"
]
echo '["a", "b", "c"]' | dasel -r json 'all()'
"a"
"b"
"c"
```
### Objects
```
echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json
{
"x": 1,
"y": 2,
"z": 3
}
echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json 'all()'
1
2
3
```
### Nested Objects
```
echo '{
"users": [
{
"name": "Tom"
},
{
"name": "Jim"
}
]
}' | dasel -r json 'users.all().name'
"Tom"
"Jim"
```
================================================
FILE: functions/and.md
================================================
# And
And accepts 1 or more arguments.
Dasel treats each argument as a selector and performs a query using the current value as the root.
If all of the resulting values are truthy, and returns true.
================================================
FILE: functions/append.md
================================================
# Append
Append accepts no arguments.
It appends a new index to the input slice/array.
## Usage
Because the append function is commonly used dasel has a recognised alias of `[]` that results in a `append()` call.
## Examples
### Append an int to a list
```
$ echo '[10, 11]' | dasel put -r json -t int -v 12 'append()'
[
10,
11,
12
]
```
### Append an int to a list with alias
```
$ echo '[10, 11]' | dasel put -r json -t int -v 12 '[]'
[
10,
11,
12
]
```
================================================
FILE: functions/count.md
================================================
# Count
Count will count the number of values output from the previous function.
## Examples
```
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'count()'
1
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'numbers.count()'
1
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'numbers.all().count()'
9
```
================================================
FILE: functions/equal.md
================================================
# Equal
Expects 2 arguments.
The first argument is a dasel selector to be executed from the current value.
The second argument is a comparison value.
Returns true if the value found by the selector matches the comparison value.
## Examples
```
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'equal(numbers.[0],1)'
true
```
================================================
FILE: functions/filter.md
================================================
# Filter
Expects 1 or more arguments.
Each argument should be a selector.
Filter runs the given selectors against each value from the previous function, and if all selectors return a truthy value, the element is allowed through.
## Examples
```
$ echo '[
{"label":"x","allow":true},
{"label":"y","allow":false},
{"label":"z","allow":true}
]' | dasel -r json 'all().filter(allow)'
{
"allow": true,
"label": "x"
}
{
"allow": true,
"label": "z"
}
```
================================================
FILE: functions/filteror.md
================================================
# FilterOr
Expects 1 or more arguments.
Each argument should be a selector.
FilterOr runs the given selectors against each value from the previous function, and if any selectors return a truthy value, the element is allowed through.
## Examples
```
$ echo '[
{"label":"x","allow":true},
{"label":"y","allow":false},
{"label":"z","allow":false}
]' | dasel -r json 'all().filterOr(allow,equal(label,y))'
{
"allow": true,
"label": "x"
}
{
"allow": false,
"label": "y"
}
```
================================================
FILE: functions/first.md
================================================
# First
First expect no arguments.
It can be used with a list, and returns the first item in the list.
## Example
```
$ echo '["a","b","c"]' | dasel -r json 'first()'
"a"
```
================================================
FILE: functions/index.md
================================================
# Index
Index expect 1 argument.
It can be used with a list, and returns the value at the given index list.
## Usage
Because the index function is commonly used dasel has a recognised alias of `[x]` that results in a `index(x)` call.
## Example
### Function usage
```
$ echo '["a","b","c"]' | dasel -r json 'index(1)'
"b"
```
### Alias usage
```
$ echo '["a","b","c"]' | dasel -r json '[1]'
"b"
```
================================================
FILE: functions/join.md
================================================
# Join
Join allows you to join multiple values into a single string. This is dasels version of concatenation.
Expects 1 or more arguments.
## Arguments
The first argument is required, and is the separator used when joining the strings.
Any further arguments are optional.
If no additional arguments are given, join uses the output of the previous function as it's input and will join those values.
If additional arguments are given, join uses those values as selectors and joins the result of those selectors.
If you wish to join data with plain strings you may use the [`string`](string.md) function.
{% hint style="info" %}
Be aware that the separator must always be a plain string and cannot contain any selector functions.
{% endhint %}
## Examples
### Join with no additional arguments
```
$ echo '{
"name": {
"first":"Tom",
"last":"Wright"
}
}' | dasel -r json 'name.all().join( )'
"Tom Wright"
```
### Join with arguments
```
$ echo '{
"name": {
"first":"Tom",
"last":"Wright"
}
}' | dasel -r json 'name.join( ,string(Hello\\, my name is ),first,last)'
"Hello, my name is Tom Wright"
```
================================================
FILE: functions/key.md
================================================
# Key
Key expect no arguments.
It returns the key of the current value, where the key is the object property or array index used to access it.
## Example
```
$ echo '{
"list": ["x", "y", "z"],
"object": {
"a": "x",
"b": "y",
"c": "z"
}
}' | dasel -r json 'all().all().key()'
0
1
2
"a"
"b"
"c"
```
================================================
FILE: functions/keys.md
================================================
# Keys
Keys expect no arguments.
Returns an array of keys for the current value, where the keys are either:
* Object field names
* Array indexes
## Example
```
$ echo '[1,2,3,4,5]' | dasel -r json 'keys()'
[
0,
1,
2,
3,
4
]
```
================================================
FILE: functions/last.md
================================================
# Last
Last expect no arguments.
It can be used with a list, and returns the last item in the list.
## Example
```
$ echo '["a","b","c"]' | dasel -r json 'last()'
"c"
```
================================================
FILE: functions/len.md
================================================
# Len
Len expects no arguments and can be used on lists or objects. It returns the number of elements contained within the list/map.
## Examples
```
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'len()'
1
$ echo '{"numbers":[1,2,3,4,5,6,7,8,9]}' | dasel -r json 'numbers.len()'
9
```
================================================
FILE: functions/lessthan.md
================================================
# LessThan
Expects 2 arguments.
The first argument is a dasel selector to be executed from the current value.
The second argument is a comparison value.
Returns true if the value found by the selector is less than the comparison value.
## Examples
### LessThan
```
$ echo '[1,2,3,4,5]' | dasel -r json 'all().lessThan(.,3)'
true
true
false
false
false
```
### LessThanEqual
```
$ echo '[1,2,3,4,5]' | dasel -r json 'all().or(equal(.,3),lessThan(.,3))'
true
true
true
false
false
```
================================================
FILE: functions/mapof.md
================================================
# MapOf
Expects 2 or more arguments.
Expects arguments to be given in pairs, where the first argument is the property name, and the second argument is a selector that will be used to resolve the property value.
## Examples
### Filtering values into lists
```
$ echo '[1,2,3,4,5]' |
dasel -r json 'mapOf(lessThan,all().filter(lessThan(.,3)).merge(),moreThan,all().filter(moreThan(.,3)).merge())'
{
"lessThan": [
1,
2
],
"moreThan": [
4,
5
]
}
```
### Restructuring/picking specific fields
```
$ echo '[
{
"name": {
"first": "Tom",
"last": "Wright"
},
"title": "Mr",
"phone": "07"
},
{
"name": {
"first": "Joe",
"last": "Bloggs"
},
"title": "Mr",
"phone": "07"
}
]' | dasel -r json 'all().mapOf(firstName,name.first,lastName,name.last,title,title,phone,phone).merge()'
[
{
"firstName": "Tom",
"lastName": "Wright",
"phone": "07",
"title": "Mr"
},
{
"firstName": "Joe",
"lastName": "Bloggs",
"phone": "07",
"title": "Mr"
}
]
```
### Exporting specific fields to csv
```
$ echo '[
{
"name": {
"first": "Tom",
"last": "Wright"
},
"title": "Mr",
"phone": "07"
},
{
"name": {
"first": "Joe",
"last": "Bloggs"
},
"title": "Mr",
"phone": "07"
}
]' | dasel -r json -w csv 'all().mapOf(phone,phone,firstName,name.first).merge()'
firstName,phone
Tom,07
Joe,07
```
================================================
FILE: functions/merge.md
================================================
# Merge
Merge expect 0 or more arguments.
## No arguments
When called with no arguments merge takes all of the output values from the previous function and adds them to a single list.
## 1 or more arguments
When called with 1 or more arguments, the arguments are executed as a subquery on each of the output values from the previous function.
All values returned from subqueries across all input values are added to a single list.
## Examples
### Merge arguments
```
$ echo '{
"name": {
"first":"Tom",
"last":"Wright"
},
"firstNames": [
"Jim",
"Bob"
]
}' | dasel -r json 'merge(name.first,firstNames.all()).all()'
[
"Tom",
"Jim",
"Bob"
]
```
### Merge no arguments
```
$ echo '[
{"name": {"first": "Tom"}},
{"name": {"first": "Jim"}},
{"name": {"first": "Frank"}}
]' | dasel -r json 'all().name.first.merge()'
[
"Tom",
"Jim",
"Frank"
]
```
================================================
FILE: functions/morethan.md
================================================
# MoreThan
Expects 2 arguments.
The first argument is a dasel selector to be executed from the current value.
The second argument is a comparison value.
Returns true if the value found by the selector is more than the comparison value.
## Examples
### MoreThan
```
$ echo '[1,2,3,4,5]' | dasel -r json 'all().moreThan(.,3)'
false
false
false
true
true
```
### MoreThanEqual
```
$ echo '[1,2,3,4,5]' | dasel -r json 'all().or(equal(.,3),moreThan(.,3))'
false
false
true
true
true
```
================================================
FILE: functions/not.md
================================================
# Not
Expects 1 argument.
Expects the argument to be a selector that will be performed against the current value.
Returns false if the selector returns a truthy value.
Returns true if the selector returns a falsey value.
## Examples
### NotMoreThan
```
$ echo '[1,2,3,4,5]' | dasel -r json 'all().not(moreThan(.,3))'
true
true
true
false
false
```
================================================
FILE: functions/null.md
================================================
# Null
Null is a basic function that allows you to return a null value.
Expects 0 arguments.
## Examples
### Basic
```
$ echo '{}' | dasel -r json 'null()'
null
```
================================================
FILE: functions/or.md
================================================
# Or
Or accepts 1 or more arguments.
Dasel treats each argument as a selector and performs a query using the current value as the root.
If one of the resulting values are truthy, or returns true.
================================================
FILE: functions/ordefault.md
================================================
# OrDefault
Accepts 2 arguments.
Or default allows you to use another value or selector as a backup when the expected value isn't present.
## Examples
### Simple field selection
```
$ echo '{"name":"Tom","email":"contact@tomwright.me"}' | dasel -r json 'orDefault(phone,string(N/A))'
"N/A"
```
### Creating a new map with defaults
```
$ echo '[
{
"name": "Tom",
"email": "contact@tomwright.me"
},
{
"name": "Jim",
"phone": "+441234567890"
}
]' | go run cmd/dasel/main.go -r json 'all().mapOf(name,name,email,orDefault(email,string(N/A)),phone,orDefault(phone,string(N/A)))'
{
"email": "contact@tomwright.me",
"name": "Tom",
"phone": "N/A"
}
{
"email": "N/A",
"name": "Jim",
"phone": "+441234567890"
}
```
================================================
FILE: functions/parent.md
================================================
# Parent
Accepts no arguments.
Returns the parent of the current value.
## Examples
```
$ echo '[
{
"name": "Tom",
"flags": {
"banned": false
}
},
{
"name": "Jim",
"flags": {
"banned": true
}
},
{
"name": "Jess",
"flags": {
"banned": false
}
}
]' | dasel -r json 'all().flags.filter(equal(banned,true)).parent().parent().all().name'
"Tom"
"Jim"
"Jess"
```
================================================
FILE: functions/property.md
================================================
# Property
Accepts 1 or more arguments.
Returns the values found under the given keys.
If any argument ends with a `?`, that lookup is considered optional and dasel will continue if that property is not found.
## Usage
Because property is a commonly used function, it has an alias.
If no round brackets are detected in a selector part and no other function detects it as an alias, dasel assumes it is a property name.
## Examples
### Property with optional field
```
$ echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json 'property(x,y,bad?)'
1
2
```
### Property using alias
```
$ echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json 'x'
1
```
================================================
FILE: functions/selector-overview.md
================================================
# Selector Overview
Dasel selectors are simply a list of functions to execute.
Each function:
* Is separated by a `.`
* Accepts 0 or more arguments
* Returns 0 or more values
* May have aliases defined to make them easier to use
All functions are documented with examples.
================================================
FILE: functions/string.md
================================================
# String
String is a basic function that allows you to return a plain string value.
Expects 1 argument.
If you wish to use a comma in your string you must escape it with a backslash `\,`.
## Examples
### Basic
```
$ echo '{}' | dasel -r json 'string(my string)'
"my string"
```
### Add fixed values to maps
```
$ echo '{
"name": "Tom Wright"
}' | dasel -r json 'mapOf(name,name,title,string(Mr))'
{
"name": "Tom Wright",
"title": "Mr"
}
```
================================================
FILE: functions/this.md
================================================
# This
Accepts no arguments.
Returns the current value. Is most commonly used in comparison functions when you want to reference the value of the current element.
## Usage
`.` is an alias for `this()`.
## Examples
### This
```
$ echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json 'all().this()'
1
2
3
```
### This using alias
```
$ echo '{"x": 1, "y": 2, "z": 3}' | dasel -r json 'all().'
1
2
3
```
================================================
FILE: functions/type.md
================================================
# Type
Accepts no arguments.
Returns the type of the current value.
Possible return values are:
* `string`
* `number`
* `bool`
* `array`
* `object`
* `null`
* `unknown`
## Examples
### This
```
$ echo '[
"x",
false,
true,
1,
1.1,
{"x":1},
[1]
]' | dasel -r json 'all().type()'
"string"
"bool"
"bool"
"number"
"number"
"object"
"array"
```