yq/pkg/yqlib/doc/operators/add.md

326 lines
4.4 KiB
Markdown
Raw Normal View History

2021-11-03 02:54:09 +00:00
# Add
2020-11-24 02:07:19 +00:00
Add behaves differently according to the type of the LHS:
2021-11-03 02:54:09 +00:00
* arrays: concatenate
* number scalars: arithmetic addition
* string scalars: concatenate
2022-01-23 00:35:44 +00:00
* maps: shallow merge (use the multiply operator (`*`) to deeply merge)
2022-01-23 00:35:44 +00:00
Use `+=` as a relative append assign for things like increment. Note that `.a += .x` is equivalent to running `.a = .a + .x`.
2022-01-22 02:47:22 +00:00
2022-02-06 03:39:46 +00:00
{% hint style="warning" %}
Note that versions prior to 4.18 require the 'eval/e' command to be specified. 
`yq e <exp> <file>`
{% endhint %}
2020-11-24 02:07:19 +00:00
## Concatenate arrays
Given a sample.yml file of:
```yaml
a:
- 1
- 2
b:
- 3
- 4
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a + .b' sample.yml
2020-11-24 02:07:19 +00:00
```
will output
```yaml
- 1
- 2
- 3
- 4
```
## Concatenate to existing array
Note that the styling of `a` is kept.
2020-11-24 02:07:19 +00:00
Given a sample.yml file of:
```yaml
a: [1,2]
b:
- 3
- 4
2020-11-24 02:07:19 +00:00
```
then
```bash
yq '.a += .b' sample.yml
2020-11-24 02:07:19 +00:00
```
will output
```yaml
a: [1, 2, 3, 4]
b:
- 3
- 4
2020-11-24 02:07:19 +00:00
```
## Concatenate null to array
2020-11-24 02:07:19 +00:00
Given a sample.yml file of:
```yaml
a:
- 1
- 2
```
then
```bash
yq '.a + null' sample.yml
2020-11-24 02:07:19 +00:00
```
will output
```yaml
- 1
- 2
```
## Append to existing array
Note that the styling is copied from existing array elements
2020-11-24 02:07:19 +00:00
Given a sample.yml file of:
```yaml
a: ['dog']
2020-11-24 02:07:19 +00:00
```
then
```bash
yq '.a += "cat"' sample.yml
2020-11-24 02:07:19 +00:00
```
will output
```yaml
a: ['dog', 'cat']
2020-11-24 02:07:19 +00:00
```
## Add new object to array
2021-07-07 05:36:43 +00:00
Given a sample.yml file of:
```yaml
a:
- dog: woof
2021-07-07 05:36:43 +00:00
```
then
```bash
yq '.a + {"cat": "meow"}' sample.yml
2021-07-07 05:36:43 +00:00
```
will output
```yaml
- dog: woof
- cat: meow
2021-07-07 05:36:43 +00:00
```
## Relative append
2021-01-11 04:43:50 +00:00
Given a sample.yml file of:
```yaml
a:
a1:
b:
- cat
a2:
b:
- dog
a3: {}
2021-01-11 04:43:50 +00:00
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a[].b += ["mouse"]' sample.yml
2021-01-11 04:43:50 +00:00
```
will output
```yaml
a:
a1:
b:
- cat
- mouse
a2:
b:
- dog
- mouse
a3:
b:
- mouse
2021-01-11 04:43:50 +00:00
```
## String concatenation
2021-01-11 04:43:50 +00:00
Given a sample.yml file of:
```yaml
a: cat
b: meow
```
then
```bash
yq '.a += .b' sample.yml
2021-01-11 04:43:50 +00:00
```
will output
```yaml
a: catmeow
b: meow
```
## Number addition - float
If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of:
```yaml
a: 3
b: 4.9
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a = .a + .b' sample.yml
2021-01-11 04:43:50 +00:00
```
will output
```yaml
a: 7.9
b: 4.9
```
## Number addition - int
If both the lhs and rhs are ints then the expression will be calculated with ints.
Given a sample.yml file of:
```yaml
a: 3
b: 4
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a = .a + .b' sample.yml
2021-01-11 04:43:50 +00:00
```
will output
```yaml
a: 7
b: 4
```
## Increment numbers
2021-01-11 04:43:50 +00:00
Given a sample.yml file of:
```yaml
a: 3
b: 5
2021-01-11 04:43:50 +00:00
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.[] += 1' sample.yml
2021-01-11 04:43:50 +00:00
```
will output
```yaml
a: 4
b: 6
2021-01-11 04:43:50 +00:00
```
## Date addition
You can add durations to dates. Assumes RFC3339 date time format, see [date-time operators](https://mikefarah.gitbook.io/yq/operators/date-time-operators) for more information.
Given a sample.yml file of:
```yaml
a: 2021-01-01T00:00:00Z
```
then
```bash
yq '.a += "3h10m"' sample.yml
```
will output
```yaml
a: 2021-01-01T03:10:00Z
```
## Date addition - custom format
You can add durations to dates. See [date-time operators](https://mikefarah.gitbook.io/yq/operators/date-time-operators) for more information.
Given a sample.yml file of:
```yaml
a: Saturday, 15-Dec-01 at 2:59AM GMT
```
then
```bash
yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST", .a += "3h1m")' sample.yml
```
will output
```yaml
a: Saturday, 15-Dec-01 at 6:00AM GMT
```
2021-01-18 02:58:46 +00:00
## Add to null
Adding to null simply returns the rhs
Running
```bash
2022-01-27 06:21:10 +00:00
yq --null-input 'null + "cat"'
2021-01-18 02:58:46 +00:00
```
will output
```yaml
cat
```
2022-01-23 00:35:44 +00:00
## Add maps to shallow merge
Adding objects together shallow merges them. Use `*` to deeply merge.
Given a sample.yml file of:
```yaml
a:
thing:
name: Astuff
value: x
a1: cool
b:
thing:
name: Bstuff
legs: 3
b1: neat
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a += .b' sample.yml
2022-01-23 00:35:44 +00:00
```
will output
```yaml
a:
thing:
name: Bstuff
legs: 3
a1: cool
b1: neat
b:
thing:
name: Bstuff
legs: 3
b1: neat
```
2022-01-22 02:17:16 +00:00
## Custom types: that are really strings
2022-01-22 02:47:22 +00:00
When custom tags are encountered, yq will try to decode the underlying type.
2022-01-22 02:17:16 +00:00
Given a sample.yml file of:
```yaml
a: !horse cat
b: !goat _meow
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a += .b' sample.yml
2022-01-22 02:17:16 +00:00
```
will output
```yaml
a: !horse cat_meow
b: !goat _meow
```
## Custom types: that are really numbers
2022-01-22 02:47:22 +00:00
When custom tags are encountered, yq will try to decode the underlying type.
2022-01-22 02:17:16 +00:00
Given a sample.yml file of:
```yaml
a: !horse 1.2
b: !goat 2.3
```
then
```bash
2022-01-27 06:21:10 +00:00
yq '.a += .b' sample.yml
2022-01-22 02:17:16 +00:00
```
will output
```yaml
a: !horse 3.5
b: !goat 2.3
```