NAME
    yq - Filter YAML through a command-line program

VERSION
    version 0.010

SYNOPSIS
        yq <script> [<file>...]

        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
  script
    The script to run. For the script syntax, see SYNTAX.

  <file>
    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
  EXPRESSIONS
    An "EXPRESSION" is allowed to be either a FILTER, VALUE, or a
    COMPARISON.

  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

  VALUES
    'STRING' "STRING"
        Both single- and double-quoted strings are allowed. Using \ will
        escape the string delimiter.

    { KEY: EXPRESSION, ... }
        The hash constructor. "KEY" may be any "FILTER" or a bare value.

            # INPUT
            foo: bar
            baz: fuzz
            ---
            foo: 1
            baz: 2

            $ yq '{ bar: .foo, .baz: foo }'
            bar: bar
            fuzz: foo
            ---
            2: foo
            bar: 1

    [ EXPRESSION, ... ]
        The array constructor.

            # INPUT
            foo: bar
            baz: fuzz
            ---
            foo: 1
            baz: 2

            $ yq '[ .foo, .baz ]'
            - bar
            - fuzz
            ---
            - 1
            - 2

    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'
            $

        ... though see the "grep()" function for a shorter way of writing
        this.

    Values
        Any bareword that is not recognized as a syntax element is treated
        as a value. These barewords may only contain letters, numbers, and
        underscore.

        NOTE: This may be subject to change to only allow quoted strings and
        bare numbers in a future version.

  COMPARISONS
    eq  String equals comparison. Returns true if both sides are equal to
        each other when treated as a string.

        The two sides may be FILTERS or VALUES.

            # INPUT
            foo: bar
            baz: fuzz
            buzz: fuzz

            $ yq '.foo eq bar'
            true

            $ yq '.baz eq .buzz'
            true

            $ yq '.baz eq bar'
            false

        YAML treats the string "true" as a true value, and the string
        "false" as a false value.

    ne  String not equals comparison. Returns true if one side is not equal
        to the other side when compared as a string.

        The two sides may be FILTERS or VALUES.

            # INPUT
            foo: bar
            baz: fuzz
            buzz: fuzz

            $ yq '.foo eq bar'
            true

            $ yq '.baz eq .buzz'
            true

            $ yq '.baz eq bar'
            false

        YAML treats the string "true" as a true value, and the string
        "false" as a false value.

  FUNCTIONS
    grep( EXPRESSION )
        If "EXPRESSION" is true, return the current document. Otherwise,
        return "empty".

        This is exactly the same as:

            if EXPRESSION then . else empty

    select( EXPRESSION )
        Another name for "grep()" to match "jq"'s syntax.

    group_by( EXPRESSION )
        Group incoming documents based on the result of "EXPRESSION",
        yielding a single document containing a hash of arrays.

            # INPUT
            ---
            foo: 'bar'
            baz: 1
            ---
            foo: 'bar'
            baz: 2
            ---
            foo: 'baz'
            baz: 3

            $ yq 'group_by( .foo )'
            bar:
                - foo: bar
                  baz: 1
                - foo: bar
                  baz: 2
            baz:
                - foo: baz
                  baz: 3

        NOTE: If you are filtering a lot of documents, this will consume a
        lot of memory.

  CONDITIONALS
    if EXPRESSION then TRUE_FILTER else FALSE_FILTER
        If the "EXPRESSION" is true, return the result of "TRUE_FILTER",
        otherwise return the result of "FALSE_FILTER".

            # 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

            $ yq 'if .foo then .baz'
            fuzz

            $ yq 'if .herp then .derp else .'
            foo: bar
            baz: fuzz

        The "else FALSE_FILTER" is optional and defaults to returning
        undefined.

  COMBINATORS
    Combinators combine multiple expressions to yield one or more documents
    in the output stream.

    ,   Multiple EXPRESSIONS may be separated by commas to yield multiple
        documents in the output.

            # INPUT
            foo: bar
            baz: fuzz

            $ yq '.foo, .baz'
            bar
            ---
            fuzz

SEE ALSO
    jq  <http://stedolan.github.io/jq/> A filter for JSON documents. The
        inspiration for this project.

AUTHOR
    Doug Bell <preaction@cpan.org>

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.