Segment: Anchors

1. Introduction
   1. Sample Data
2. More About YAML Merge Keys
3. Especially Useful for Anchor Lists

Introduction

When your YAML data contains Anchors and Aliases -- including YAML Merge Keys -- you can select them by their unique name. Note that an & prefix must be used whether accessing the defining Anchor or any of its Aliases. Despite a YAML Alias normally being prefixed with a * rather than an & in the YAML data, you must still access them with an & prefix in this YAML Path segment type.

Demarcating the Anchor segment with a [] pair is optional; &alias and [&alias] are identical. Using one form or another is a stylistic choice. For example, users tend to prefer the square-bracketed form when accessing an Alias from an Array (sequence/list).

For a deep exploration of YAML Anchors, Aliases, and Merge Keys, visit yaml-merge Anchor Options. While it is written in the context of document merging, the document provides very detailed explanations of these powerful, native YAML features with abundant examples.

Sample Data

Unless otherwise stated, the following examples will be based on this sample data:

---
aliases:
  - &reusable_value This value can be used multiple times

anchored_hash: &anchor1
  with: child
  nodes: and values
  including: *reusable_value

non_anchored_hash:
  <<: *anchor1
  with: its
  own: children

All of the Anchors and their Aliases in the sample data can be directly accessed as:

1. aliases[&reusable_value] or /aliases[&reusable_value]
2. &anchor1 or /&anchor1
3. &anchor1.&reusable_value or /&anchor1/&reusable_value
4. non_anchored_hash.&reusable_value or /non_anchored_hash/&reusable_value
5. non_anchored_hash.&anchor1 or /non_anchored_hash/&anchor1
6. non_anchored_hash.&anchor1.&reusable_value or /non_anchored_hash/&anchor1/&reusable_value

More About YAML Merge Keys

Aliases in YAML Merge Keys can be directly addressed using this segment type. In the sample YAML data above, &anchor1 is used as an Alias (*anchor1) in non_anchored_hash via the <<: YAML Merge Key. It can be directly accessed via a YAML Path like non_anchored_hash[&anchor1] or /non_anchored_hash/&anchor1.

Unless using a YAML Path to create or destroy a YAML Merge Key entry, there isn't much value in reading from them, though it is possible. The query would return the original data from the source Anchored Hash. Be aware that doing so ignores any overrides of those key-value pairs in the immediate Hash! From the sample data above, these two queries demonstrate this important distinction:

$ yaml-get --query='/non_anchored_hash/with' sample.yaml
its

$ yaml-get --query='/non_anchored_hash/&anchor1/with' sample.yaml
child

Especially Useful for Anchor Lists

This segment type is especially useful for selecting named anchor values from the typical aliases: list, commonly used in YAML files to define a unified location for any scalar values that are used more than once elsewhere within the same YAML file. For example:

aliases:
  - &anchorA Some value
  - &anchorB Another value
  - &anchorC True
  - &anchorD 5280

You could select the value, Another value, by using its array element index -- if you knew it -- or more simply by its known anchor name, like so: aliases[&anchorB] or /aliases[&anchorB]. Please note that the & symbol is always required to indicate an Anchor name. Further, the [] pair is optional, even when selecting from an Array (AKA: sequence, list); you can use a proper YAML Path separator, instead.