File: README — Documentation by YARD 0.9.38

Yerba

YAML Editing and Refactoring with Better Accuracy

A Rust CLI tool and Ruby library for editing YAML while preserving structure, comments, and format.

What is Yerba?

Yerba is a lossless YAML editing tool. It lets you programmatically read, modify, and enforce formatting in YAML files while preserving their original structure, including comments, blank lines, quote styles, and key ordering.

Most YAML libraries parse a file into a data structure and serialize it back, discarding all formatting in the process. Yerba operates on the concrete syntax tree (CST), so your edits are surgical: only the targeted values change, and everything else stays exactly as it was.

Yerba is available as:

A standalone CLI binary with zero runtime dependencies
A Rust crate for embedding in Rust applications
A Ruby gem for programmatic YAML editing from Ruby

Yerba was born out of the need to manage, validate, and enforce consistent formatting for hundreds of YAML data files in the RubyEvents.org project.

Installation

CLI (standalone)

The yerba CLI is a standalone Rust binary with no Ruby dependency. Install it via Cargo:

cargo install yerba

Rust Crate

Use yerba as a library in your Rust project:

[dependencies]
yerba = "0.2"

let mut document = yerba::parse_file("config.yml")?;
document.set("database.host", "0.0.0.0")?;
document.save()?;

Ruby Gem

The Ruby gem bundles both the CLI binary and a native extension for programmatic access from Ruby:

gem install yerba

Or add it to your Gemfile:

gem "yerba"

The gem ships with precompiled binaries for macOS and Linux.

If no precompiled binary is available for your platform, it will compile from source automatically, which requires a Rust toolchain.

CLI Usage

The yerba CLI follows a consistent pattern:

yerba <command> <file> <selector> [value] [options]

Selectors use dot-notation for nested keys, brackets for array access, and support glob patterns for operating on multiple files at once.

Selectors

Selectors let you address any node in a YAML document:

Pattern	Meaning	Example
`key`	A single key	`"database.host"`
`key.nested`	Nested key path	`"database.settings.pool"`
`[]`	All items in array	`"[].title"`
`[N]`	Item at index	`"[0].title"`
`[].key[].nested`	Nested array access	`"[].speakers[].name"`

Conditions

Conditions filter which items a command operates on:

Syntax	Meaning	Example
`.key == value`	Equality	`".kind == keynote"`
`.key != value`	Inequality	`".status != draft"`
`.key contains val`	Substring or member	`".title contains Ruby"`
`.key not_contains val`	Negated contains	`".title not_contains test"`

`get`

Retrieve values from YAML files. Supports single values, array traversal, glob patterns across multiple files, conditions for filtering, and field selection.

yerba get config.yml "database.host"
yerba get videos.yml "[].title"
yerba get videos.yml "[0].title"

Use --select to pick specific fields from each item, and --condition to filter which items are returned:

yerba get videos.yml "[]" --select ".title,.speakers"
yerba get videos.yml "[]" --condition ".kind == keynote"
yerba get videos.yml "[]" --select ".title" --condition ".kind == keynote"

Glob patterns let you query across many files at once:

yerba get "data/**/videos.yml" "[].speakers[].name"
yerba get "data/**/videos.yml" "[]" --condition ".kind == keynote" --select ".id,.title"

Use --raw to output plain values (one per line) instead of JSON:

yerba get videos.yml "[]" --condition ".speakers contains Matz" --raw

`set`

Update an existing value at a path. The original quote style is preserved automatically, if a value was double-quoted before, it stays double-quoted after the edit.

yerba set config.yml "database.host" "0.0.0.0"
yerba set videos.yml "[0].title" "New Title"

Use --if-exists to only set the value when the path already exists, or --if-missing to only set it when the path does not exist:

yerba set config.yml "database.host" "0.0.0.0" --if-exists
yerba set "data/**/event.yml" "website" "" --if-exists

Use --condition to only apply the change when a sibling field matches:

yerba set config.yml "database.host" "0.0.0.0" --condition ".port == 5432"

`insert`

Insert a new key into a map or a new item into a sequence. By default, new items are appended at the end.

yerba insert config.yml "database.ssl" true
yerba insert config.yml "tags" "yaml"

Control placement with --before, --after, or --at:

yerba insert config.yml "database.ssl" true --after "host"
yerba insert config.yml "database.ssl" true --before "port"
yerba insert config.yml "tags" "yaml" --at 0
yerba insert config.yml "tags" "yaml" --after "ruby"

For sequences of maps, use conditions to position relative to other items:

yerba insert speakers.yml "" "name: Bob" --after ".name == Alice"
yerba insert videos.yml "[0].speakers" "Diana" --before ".name == Charlie"

Use --from to read the value from another file (or stdin with -):

yerba insert videos.yml "" --from "new_talk.yml" --after ".id == first-talk"

`delete`

Remove a key and its value from a map:

yerba delete config.yml "database.pool"
yerba delete videos.yml "[0].description"

Use --dry-run to preview the result without writing to the file:

yerba delete config.yml "database.pool" --dry-run

`remove`

Remove a specific item from a sequence by its value:

yerba remove config.yml "tags" "rust"
yerba remove videos.yml "[0].speakers" "Alice"

`rename`

Rename a key in a map while preserving its value and position:

yerba rename config.yml "database.host" "database.hostname"
yerba rename config.yml "database.host" "hostname"

`move`

Move a sequence item to a new position. You can reference items by value, index, or condition:

yerba move config.yml "tags" "rust" --before "ruby"
yerba move config.yml "tags" "rust" --after "yaml"
yerba move config.yml "tags" 2 --to 0
yerba move videos.yml "" ".id == talk-2" --after ".id == talk-1"

`move-key`

Move a key to a new position within a map:

yerba move-key config.yml "database.name" --to 0
yerba move-key config.yml "database.pool" --before "database.host"
yerba move-key config.yml "database.pool" --after "database.name"

`sort`

Sort items in a sequence. For simple scalar sequences, no options are needed. For sequences of maps, use --by to specify sort fields. Append :desc for descending order:

yerba sort config.yml "tags"
yerba sort videos.yml --by "title"
yerba sort videos.yml --by "date:desc,title"
yerba sort videos.yml "[].speakers" --by "name"

`sort-keys`

Reorder the keys in a map to match a predefined order. If any key in the document is not present in the order list, the command aborts with an error, this ensures you account for every field:

yerba sort-keys config.yml "database" "host,port,name,pool"
yerba sort-keys "data/**/event.yml" "" "id,title,kind,location"
yerba sort-keys "data/**/videos.yml" "[]" "id,title,speakers"

`quote-style`

Enforce a consistent quote style across keys and/or values. Available styles are plain, single, and double:

yerba quote-style config.yml --values double
yerba quote-style config.yml --keys plain
yerba quote-style config.yml --keys plain --values double

Scope the operation to a specific selector:

yerba quote-style config.yml "[].speakers" --values plain
yerba quote-style "data/**/*.yml" --keys plain --values double

`blank-lines`

Enforce a consistent number of blank lines between sequence entries:

yerba blank-lines videos.yml 1
yerba blank-lines videos.yml "[]" 1
yerba blank-lines config.yml "tags" 0

`Yerbafile`

A Yerbafile is a YAML configuration file that defines formatting and editing rules as pipelines of operations that are applied to your files across your project.

Use yerba init to create one, then yerba apply to apply all rules, or yerba check to verify compliance (exits with code 1 if files would change):

yerba init
yerba apply
yerba check

Each rule specifies a file glob and a list of steps to run in order:

rules:
  - files: "config/**/*.yml"
    pipeline:
      - quote_style:
          key_style: plain
          value_style: double

      - sort_keys:
          path: ""
          order:
            - id
            - title
            - description

      - blank_lines:
          count: 1

  - files: "data/speakers.yml"
    pipeline:
      - quote_style:
          key_style: plain
          value_style: double

      - sort_keys:
          path: ""
          order:
            - name
            - slug
            - github
            - twitter
            - website

      - sort:
          path: ""
          by: name

Available pipeline steps:

quote_style Enforce quote style on keys and/or values, optionally scoped by path
sort_keys Reorder keys to match a predefined list
sort Sort sequence items by field(s)
blank_lines Enforce blank lines between sequence entries
set Set a value (supports conditions)
insert Insert a new key or sequence item
delete Remove a key (supports conditions)
rename Rename a key
remove Remove an item from a sequence
get Read a value and store it as a variable for subsequent steps

This makes it easy to enforce project-wide YAML conventions in CI:

yerba check

Ruby API

Yerba includes a native C extension (backed by the same Rust core) that provides a full Ruby API for YAML editing.

Parsing

Create a document from a file path or from a string:

require "yerba"

document = Yerba.parse_file("config.yml")
document = Yerba.parse("database:\n  host: localhost\n  port: 5432\n")

Reading Values

Use get to retrieve the raw value at a path. Values are returned with their YAML types, strings, integers, booleans, and nil are all mapped to their Ruby equivalents:

document.get("database.host")   # => "localhost"
document.get("database.port")   # => 5432
document.get("database.ssl")    # => false

Use bracket notation to get typed wrapper objects (Scalar, Map, or Sequence) representing nodes in the document. These are live references, mutations flow back to the document.

You can use a full dot-path in a single bracket call, or chain brackets to navigate one level at a time:

document["database.host"].value          # => "localhost"
document["database"]["host"].value       # => "localhost"
document["database"]["port"].value       # => 5432

The returned object type depends on what's at the path:

document["database"]       # => Yerba::Map
document["database.host"]  # => Yerba::Scalar
document["tags"]           # => Yerba::Sequence

Scalars expose their value and quote style:

scalar = document["database.host"]
scalar.value         # => "localhost"
scalar.quote_style   # => :double

Mutations

Modify values in place. The original formatting is preserved:

document["database"]["host"].value = "0.0.0.0"
document.set("database.port", 3306)

Insert new keys with positional control:

document["database"].insert("ssl", true, after: "host")

Work with sequences using familiar Ruby patterns:

tags = document["tags"]
tags << "yaml"
tags << { name: "Rust", version: "1.80" }
tags.remove("obsolete")
tags.sort(by: "name")

Quote Style Control

Read and set the quote style on individual scalars:

scalar = document["database.host"]
scalar.quote_style          # => :double
scalar.quote_style = :single

Wildcard Access

Use at_path to access all items matching a wildcard selector:

titles = document.at_path("[].title")
titles.each { |scalar| puts scalar.value }

Collections

Operate on multiple files matching a glob pattern:

collection = Yerba.files("data/**/videos.yml")

collection.each do |document|
  puts document.get("[0].title")
end

collection.apply! do |document|
  document.set("status", "published")
end

Saving

Write changes back to the original file:

document.save!

Or render the document as a string without writing to disk:

document.to_s

Development

After checking out the repo, run bundle install to install Ruby dependencies, then bundle exec rake test to run the test suite.

Building from source

The Rust core is in the rust/ directory:

cd rust
cargo build
cargo test

The C extension (for the Ruby API) is compiled via ext/yerba/extconf.rb which invokes cargo build and links against the resulting static library. Running bundle exec rake compile will build both the Rust library and the C extension.

Running the CLI locally

cargo run -- get config.yml "database.host"

Or build a release binary:

cd rust
cargo build --release
./target/release/yerba --help

License

The gem is available as open source under the terms of the MIT License.