YamlPath
Sublime Text plugin and Python package to determine the YAML (and JSON) Path of a particular position in a document, compatible with `yq`/`jq`. Shows the path in the ST status bar, like breadcrumb navigation.
Details
Installs
- Total 35
- Win 14
- Mac 11
- Linux 10
Dec 5 | Dec 4 | Dec 3 | Dec 2 | Dec 1 | Nov 30 | Nov 29 | Nov 28 | Nov 27 | Nov 26 | Nov 25 | Nov 24 | Nov 23 | Nov 22 | Nov 21 | Nov 20 | Nov 19 | Nov 18 | Nov 17 | Nov 16 | Nov 15 | Nov 14 | Nov 13 | Nov 12 | Nov 11 | Nov 10 | Nov 9 | Nov 8 | Nov 7 | Nov 6 | Nov 5 | Nov 4 | Nov 3 | Nov 2 | Nov 1 | Oct 31 | Oct 30 | Oct 29 | Oct 28 | Oct 27 | Oct 26 | Oct 25 | Oct 24 | Oct 23 | Oct 22 | Oct 21 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Windows | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 2 | 0 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 | 1 |
Mac | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 1 | 1 | 0 | 0 | 0 | 1 | 0 | 1 |
Linux | 0 | 1 | 0 | 1 | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
Readme
- Source
- raw.githubusercontent.com
YAML Path
A Python package and Sublime Text plugin which uses ruamel.yaml
to parse YAML and JSON documents and lookup the “breadcrumb path” at a given position, which if used as a yq
/jq
query, should return the same item.
The Sublime Text plugin shows the path of the current selection/caret position in the status bar, so you can easily tell which part of the document you are in. There is also a command palette entry to copy the path to the clipboard. And to view the parse error in case the content is not valid.
It even works with multiple selections and inside YAML or JSON codefences embedded in Markdown documents.
Status
Originally written for my own personal use, but happily accepting Pull Requests to fix any bugs or add more features.
Known limitations:
- currently only drills down to line level. This can be improved if it would be useful.
- doesn't handle JSONC very well - because it is using a YAML parser, //
isn't a valid comment in YAML…
- currently no way to enable only for YAML files, and leave JSON to be handled by a separate plugin for example
How it works
When a selection change event is fired by Sublime Text, YAMLPath checks to see if the selection start and end has the same scope. (It will if it is an empty selection of course!) If it is a JSON or YAML scope, it finds the surrounding context - either the whole document or the Markdown code fence for example, and checks the cache to see if it has an already parsed document for that region. If it doesn't, it will use the ruamel.yaml Python package to parse it and get the locations of all the nodes. This is then cached until the “view” is closed or edited etc. Then, it recursively looks through the parse tree for the node which comes immediately before the selection position. It knows not to recurse the 1st child node if the selection is after the 2nd child node position for example. Based on that hierarchy/stack of breadcrumbs, it generates the “YAML path” and shows it in the status bar. When the view is edited, it debounces the events, so that it only reparses the YAML after 200 ms has elapsed since the last edit, to keep the UI smooth.
Testing
To run the unit tests:
python3 -m venv .venv
source .venv/bin/activate
pip3 install poetry
poetry install --no-root
poetry run python3 -m yaml_path.tests.test_yaml_path
Other Features
Not strictly related to paths, there is a command implemented (without bloating the core functionality/performance or anything) for converting JSON into human readable YAML. This was specifically made for converting structured logs with unreadable stack traces, JSON dumped to a string and thus escaped in a JSON string etc. into something easily understandable by a human. Currently it is a one-way conversion, but it would be possible to also implement a YAML -> JSON converter and support “round-tripping” by adding some YAML tags to the output when it is converted from JSON. When this gets implemented, some unit tests covering this will also be added.