Home

YAML Path and Command-Line Tools

The README file touches on all of the major aspects of this YAML Path project. This Wiki provides a deeper dive into some of them.

The YAML Path project provides three things:

1. A standard which defines intuitive, command-line friendly syntax for interacting with complex YAML and compatible (JSON, EYAML, etc.) data.
2. A rich set of trivial (light-weight and cross-platform) command-line tools (CLI) for reading and editing YAML and compatible (JSON, EYAML, etc.) data via YAML Paths.
3. A reusable Python library designed with a simple API which enables other projects to employ YAML Paths.

This project strives to allow users and other developers to parse and edit YAML, EYAML, JSON, and compatible data streams and files with as little effort and maximum compatibility as possible. It also provides for advanced query capabilities not otherwise available from most other data parsers.

What is a YAML Path?

A YAML Path is a human-friendly means of identifying or searching for one or more nodes within YAML, EYAML, or compatible data structures like JSON using intuitive path segment notation. The core idea here is to make it easy to find or change the data users need from the command-line, other text input, or Python API. In fact, multiple representations of YAML Paths are supported, enabling users to express paths in whatever way is most intuitive to them.

Wait... did you say JSON? Yes; any valid JSON is also valid YAML, so YAML Paths also work perfectly well against JSON data.

Why Adopt the YAML Path Standard?

When everyone follows the same standard, everything "just works" and users can context-switch from one tool to another without encountering syntax differences for the same conceptual needs. The YAML Path standard was developed based on a study of other popular technologies which employ complex data navigation capabilities. Two were selected:

• Puppet's Hiera: dotted notation for accessing "key.subkey" nodes, string demarcation for embedded path delimiters, and path delimiter escaping
• W3C's XPath: forward-slash notation for accessing nodes and square-bracket notation for search expressions

Not every YAML/Compatible parsing or editing tool can do everything. Users will eventually need to employ more than one such tool. Some tools will even die off, forcing users to transition to its replacement. Adopting the YAML Path standard specifically helps users enjoy predictable outcomes when transitioning from one YAML/Compatible tool to another.

Why Use YAML Path's Command-Line Tools?

It is worth noting that YAML Path was created before any effort was spent searching for pre-existing command-line YAML parsing and editing tools. In fact, there are many such tools written in myriad languages. Each tool has its own strength, weaknesses, and novel capabilities. However, the Command-Line Tools provided with this YAML Paths project are reference implementations of the YAML Path standard.

Sure, many people can write their own program to read their own site- and domain-specific YAML/Compatible data. But it takes a lot of code and intimate knowledge of the data to reliably zero-in on any particular piece of data; more so to affect changes to the data without corrupting it or crashing in the process. The YAML Path project abstracts away all of the boilerplate, the error-handling, the R&D time, and the guesswork of writing your own code to perform the same tasks.

Rather than write your own code ("reinventing the wheel"), just use the YAML Path tools while enjoying its intuitive means of addressing the desired data.