release-engineers/y

A tool like yq (and jq) but without their feature of completely cleaning up your YAML documents. yq and jq are great tools especially for making changes to documents that are not intended to be human-readable. However, when you want to make changes programmatically to documents and still be able to read them afterwards, they're probably not the best tools for the job.

y aims to be a tool familiar for users of yq and jq while preserving your YAML's comments, block & flow style, key ordering, blank lines & more.

Install the y CLI utility and Python package with;

pip install re-y

Usage

y comes with an expression language similar to yq which can be used to select and edit parts of a YAML document. Here's examples for a YAML document 'sample.yml';

---
a:
  b:
    # comments and whitespace are preserved
    # unless the object owning them is removed or replaced
    c:
      - d: 1
      # replacing the array element `d: 1` above would remove this comment (and any potential whitespace around it)
      - e: 2
      - f: 3

#!/usr/bin/env bash
# modify a file in-place
y --inplace --file docs/sample.yml -- '.a.b.c[0] = 123'

#!/usr/bin/env bash
# write to stdout
y --file docs/sample.yml -- '.a.b.c[0] = 123'

Expressions

ℹ️ Regarding mathematical operators; ^ is evaluated first, then *, / and % are evaluated left-to-right, and finally + and - are evaluated left-to-right.

⚠️ Assigning precedence to mathematical operators with parentheses is not supported.

ℹ️ The pipe operator | modifies the expression context (.) of the right-hand expression to the output of the left-hand expression, hence the availability of the $ operator to select the root of the program context.

Contributing

This is a Python Poetry project using Fire. See Poetry for more information.

Development requires:

• Bash
• Docker
• Python
• Poetry

Links

This project was created using template-poetry.