-
-
Notifications
You must be signed in to change notification settings - Fork 21
Segments of a YAML Path
A YAML Path is comprised of segments. Each segment indicates part of the navigation instructions through the source data. Some segment types select a single precise node while others are capable of selecting zero, one, or more than one. Most segment types move the internal pointer through the source data, adjusting the basis for the next segment. Not all do. YAML Path defines these segment types:
- Anchors
- Array Elements
- Array Element Searches
- Array Slices
- Collectors
- Hash Attribute Searches
- Hash Keys
- Hash Slices
- Pass-Through Selections for Arrays of Hashes
- Search Keywords
- Set Values
- Wildcard Segments
YAML Paths support one of two segment separators per path:
- Dot (
.
); as in:segment1.segment2.segment3
- Forward-Slash (
/
); as in:/segment1/segment2/segment3
For any YAML Path, these two types of segment separators cannot be mixed. When using the forward-slash separator, the first character of the YAML Path MUST be a forward-slash. When using the dot separator, this is optional; the first character does not need to be a dot.
Whether using dot- or forward-slash notation, every YAML Path is comprised of at least one navigation segment. Whether fetching, changing, or creating new data, all YAML Paths serve the same purpose: to indicate where within the data the requested operation is to be performed. Take the following data for example:
hash:
scalar_value: data
array_values:
- element0
- element1
- element2
array_of_hashes:
- id: 0
name: something
- id: 1
name: something else
To navigate to element1
of the array_values
key within the complex hash
data structure, you'd use the following YAML Path: hash.array_values[1]
(dot-notation) or /hash/array_values[1]
(forward-slash notation). Both of these forms of the YAML Path are comprised of 3 segments:
-
hash
: A Hash Key; in this case the data root is itself a Hash data structure withhash
being one of its top-most keys. -
array_values
: Another Hash Key; in this case it is a child key of the parenthash
. -
[1]
: An Array Element Index; in this case selecting the second element of the array, because Arrays use 0-based indexing (the first element of every array is always at index 0).
How would you select an array_of_hashes
entity with the phrase else
in its name
? Along with deterministic selection, YAML Path also provides for searching capabilities, which can return 0 or more results. Using a Hash Attribute Search segment, you could write: hash.array_of_hashes[name % else]
and get back the entire matching child Hash, {"id": 1, "name": "something else"}
.
Say you needed only the id
of the matching record. In this case, you could add another segment to the YAML Path, selecting just the id
node: hash.array_of_hashes[name % else].id
would yield 1
.
Visit each page of the available YAML Path Segment Types for more detail about how each segment works with examples.