NAME yq - Filter YAML through a command-line program VERSION version 0.006 SYNOPSIS yq [...] yq -h|--help DESCRIPTION This program takes a stream of YAML documents (on STDIN or file arguments), applies a filter, then writes the results to STDOUT. ARGUMENTS filter The filter to run. For the filter syntax, see SYNTAX. A YAML file to filter. The special file "-" refers to STDIN. If no files are specified, filter STDIN. OPTIONS -h | --help Show this help document. SYNTAX FILTERS Filters select a portion of the incoming documents. Filters can be combined to reach deep inside the documents you're working with. . Returns the entire document, unfiltered. Useful in if/then statements. # INPUT foo: bar baz: fuzz $ yq . foo: bar baz: fuzz .key Extract a single item out of a hash. # INPUT foo: bar: baz fizz: fuzz $ yq .foo bar: baz fizz: fuzz $ yq .foo.fizz fuzz .[#] Extract a single item out of an array. # INPUT - foo: fuzz - bar: buzz - baz: good: bad new: old $ yq .[1] bar: buzz $ yq .[2] baz: good: bad new: old $ yq .[2].baz good: bad new: old $ yq .[2].baz.new old [] Use [] with no index to flatten an array. # INPUT - foo: fuzz - bar: buzz $ yq '.[]' foo: fuzz --- bar: buzz , Multiple filters may be separated by commas to yield multiple documents in the output. # INPUT foo: bar baz: fuzz $ yq '.foo, .baz' bar --- fuzz VALUES empty The special value empty suppresses printing of a document. Normally, an undefined document will show up in the output as "--- ~". If your filter instead yields empty, the document will not be printed at all. This is especially useful in conditionals: # INPUT foo: bar baz: fuzz $ yq 'if .foo eq bar then . else empty' foo: bar baz: fuzz $ yq 'if .foo eq buzz then . else empty' $ Values Any bareword that is not recognized as a syntax element is treated as a value. CONDITIONALS if lhs_filter eq rhs_filter then true_filter else false_filter If the lhs filter and rhs_filter are equal, return the true_filter, otherwise return the false_filter. For example # INPUT foo: bar baz: fuzz $ yq 'if .foo eq bar then .baz else .foo' fuzz $ yq 'if .foo eq buzz then .baz else .foo' bar The else false_filter is optional and defaults to returning undefined. SEE ALSO jq A filter for JSON documents. The inspiration for this project. AUTHOR Doug Bell COPYRIGHT AND LICENSE This software is copyright (c) 2014 by Doug Bell. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.