yq/README.md

252 lines
4.0 KiB
Markdown
Raw Normal View History

# yaml [![Build Status](https://travis-ci.org/mikefarah/yaml.svg?branch=master)](https://travis-ci.org/mikefarah/yaml)
2015-10-13 10:31:02 +00:00
yaml is a lightweight and flexible command-line YAML processor
2015-09-27 03:29:20 +00:00
2015-10-13 10:31:02 +00:00
The aim of the project is to be the [jq](https://github.com/stedolan/jq) or sed of yaml files.
2015-09-27 03:29:20 +00:00
2015-11-20 10:42:45 +00:00
## Install
[Download latest binary](https://github.com/mikefarah/yaml/releases/latest) or alternatively:
```
go get github.com/mikefarah/yaml
```
2015-10-13 10:31:02 +00:00
## Features
- Written in portable go, so you can download a lovely dependency free binary
- Deep read a yaml file with a given path
- Update a yaml file given a path
- Update a yaml file given a script file
2017-04-12 11:17:54 +00:00
- Update creates any missing entries in the path on the fly
- Create a yaml file given a deep path and value
- Create a yaml file given a script file
2015-10-13 10:31:02 +00:00
- Convert from json to yaml
- Convert from yaml to json
2017-04-12 11:30:29 +00:00
- Pipe data in by using '-'
2015-09-29 00:20:31 +00:00
2015-09-28 00:50:32 +00:00
## Read examples
2015-09-27 03:29:20 +00:00
```
2015-10-06 05:07:09 +00:00
yaml r <yaml file> <path>
2015-09-27 03:29:20 +00:00
```
2015-09-28 00:50:32 +00:00
### Basic
Given a sample.yaml file of:
```yaml
b:
c: 2
2015-09-27 03:29:20 +00:00
```
2015-09-28 00:50:32 +00:00
then
```bash
2015-10-06 05:07:09 +00:00
yaml r sample.yaml b.c
2015-09-27 03:29:20 +00:00
```
will output the value of '2'.
2015-09-27 03:40:09 +00:00
2015-10-05 04:48:34 +00:00
### Reading from STDIN
Given a sample.yaml file of:
2015-10-06 00:51:36 +00:00
```bash
2015-10-06 05:07:09 +00:00
cat sample.yaml | yaml r - b.c
2015-10-05 04:48:34 +00:00
```
will output the value of '2'.
2015-10-05 23:01:33 +00:00
### Splat
Given a sample.yaml file of:
```yaml
---
bob:
item1:
cats: bananas
item2:
cats: apples
```
then
```bash
2015-10-06 05:07:09 +00:00
yaml r sample.yaml bob.*.cats
2015-10-05 23:01:33 +00:00
```
will output
```yaml
- bananas
- apples
```
2015-10-03 05:10:29 +00:00
### Handling '.' in the yaml key
Given a sample.yaml file of:
```yaml
b.x:
c: 2
```
then
```bash
2015-10-06 05:07:09 +00:00
yaml r sample.yaml \"b.x\".c
2015-10-03 05:10:29 +00:00
```
will output the value of '2'.
2015-09-28 00:50:32 +00:00
### Arrays
You can give an index to access a specific element:
e.g.: given a sample file of
```yaml
2015-09-27 03:40:09 +00:00
b:
e:
- name: fred
value: 3
- name: sam
value: 4
```
then
```
2015-10-06 05:07:09 +00:00
yaml r sample.yaml b.e[1].name
2015-09-27 03:40:09 +00:00
```
will output 'sam'
2015-09-28 00:50:32 +00:00
2015-10-06 00:58:51 +00:00
### Array Splat
2015-10-05 03:41:01 +00:00
e.g.: given a sample file of
```yaml
b:
e:
- name: fred
value: 3
- name: sam
value: 4
```
then
```
2015-10-06 05:07:09 +00:00
yaml r sample.yaml b.e[*].name
2015-10-05 03:41:01 +00:00
```
will output:
```
- fred
- sam
```
2015-10-06 00:58:51 +00:00
## Update examples
2017-04-12 11:17:54 +00:00
Existing yaml files can be updated via the write command
2015-10-05 23:01:33 +00:00
2015-10-06 00:58:51 +00:00
### Update to stdout
2015-09-29 06:29:32 +00:00
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
2015-10-03 08:19:13 +00:00
yaml w sample.yaml b.c cat
2015-09-29 06:29:32 +00:00
```
will output:
```yaml
b:
c: cat
```
2015-10-06 00:58:51 +00:00
2017-04-12 11:30:29 +00:00
### Update from STDIN
```bash
cat sample.yaml | yaml w - b.c blah
```
2017-04-12 11:17:54 +00:00
### Adding new fields
Any missing fields in the path will be created on the fly.
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yaml w sample.yaml b.d[0] "new thing"
```
will output:
```yaml
b:
c: cat
d:
- new thing
```
2015-10-06 00:58:51 +00:00
### Updating yaml in-place
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
2015-10-06 05:07:09 +00:00
yaml w -i sample.yaml b.c cat
2015-10-06 00:58:51 +00:00
```
will update the sample.yaml file so that the value of 'c' is cat.
### Updating multiple values with a script
Given a sample.yaml file of:
```yaml
b:
c: 2
e:
- name: Billy Bob
```
and a script update_instructions.yaml of:
```yaml
b.c: 3
b.e[0].name: Howdy Partner
```
then
```bash
2015-10-08 09:07:27 +00:00
yaml w -s update_instructions.yaml sample.yaml
```
will output:
```yaml
b:
c: 3
e:
- name: Howdy Partner
```
2017-04-12 11:30:29 +00:00
And, of course, you can pipe the instructions in using '-':
```bash
cat update_instructions.yaml | yaml w -s - sample.yaml
```
2017-04-12 11:17:54 +00:00
## New Examples
Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file.
### Creating a simple yaml file
```bash
yaml n b.c cat
```
will output:
```yaml
b:
c: cat
```
### Creating using a create script
Create scripts follow the same format as the update scripts.
Given a script create_instructions.yaml of:
```yaml
b.c: 3
b.e[0].name: Howdy Partner
```
then
```bash
yaml n -s create_instructions.yaml
```
will output:
```yaml
b:
c: 3
e:
- name: Howdy Partner
```
2017-04-12 11:30:29 +00:00
You can also pipe the instructions in:
```bash
cat create_instructions.yaml | yaml n -s -
```
2015-10-13 10:31:02 +00:00
## Converting to and from json
### Yaml2json
2015-10-10 23:00:22 +00:00
To convert output to json, use the --tojson (or -j) flag. This can be used with any command.
2015-10-13 10:31:02 +00:00
### json2yaml
To read in json, use the --fromjson (or -J) flag. This can be used with any command.