rodrigomorales1 / yaml-pro

Edit YAML in Emacs like a pro

yaml-pro: tools for editing YAML leveraging tree-sitter/parser

yaml-pro is a package that provides conveniences for editing yaml.

This package has been written to leverage tree-sitter parsing facilities, allowing all of these actions to be performed fast and accurate, even in the absence of parsing errors. The tree-sitter version is orders of magnitudes faster and I highly recommend its usage if your Emacs version permits.

Tree-sitter support

The latest version of yaml-pro contains tree-sitter support (activated via yaml-pro-ts-mode). In order to use this you will need to have a version of Emacs installed that supports tree-sitter, as well as the yaml tree-sitter parser from here: https://github.com/ikatyang/tree-sitter-yaml . The tree-sitter re-implementation supports everything below, as well as the following:

• yaml-pro-ts-meta-return (M-return): Add a new list item after the current item, similar to org-meta-return.
• yaml-pro-ts-convolute-tree (M-?): Swap the key of the current item's parent with that items parent.
• yaml-pro-ts-mark-subtree (C-c @): Mark the current YAML item. If given a prefix N, mark the Nth parent above. If called repeatedly, mark subsequent items.
• yaml-pro-ts-paste-subtree (C-c C-x C-y): Paste a YAML subtree, fixing indentation to be correct for different levels. When yaml-pro-ts-yank-subtrees is non-nil, yank will automatically call yaml-pro-ts-paste-subtree for subtrees.
• imenu: an index of all keys and their path are build for imenu
• eldoc: current path is shown as eldoc documentation. (enable with eldoc-mode)

Note that folding is not implemented. I assume some tree-sitter folding library will come along which will unify this feature.

Note that all the functions are infixed with "-ts-" to distinguish the tree-sitter and non-tree-sitter variants.

Demo

Eldoc (tree-sitter)

Imenu

Subtree pasting (tree-sitter)

Editing text in detached buffer

Never have to consult https://yaml-multiline.info/ again! With yaml-pro-edit-scalar, you can edit a scalar value in a detached buffer and convert between the various styles with ease.

Jump to heading (legacy parser)

You can use imenu as well.

Moving subtrees up and down

Folding subtrees (legacy parser)

This is not available for tree-sitter variant. Presumably some tree-sitter folding package will exist in the future.

Killing subtrees

Indenting subtrees

Tree-sitter version

To activate the mode, run M-x yaml-pro-ts-mode.

In order to run the tree-sitter version of this program, you should have a version of Emacs that supports tree-sitter, as well as the yaml tree-sitter library installed (https://github.com/ikatyang/tree-sitter-yaml). Ex: having the file libyaml.dylib in /usr/local/lib. With these in place, (treesit-ready-p 'yaml) should return t.

Usage

• yaml-pro-ts-kill-subtree (C-c C-x C-w)
• yaml-pro-ts-up-level (C-c C-u)
• yaml-pro-ts-next-subtree (C-c C-n)
• yaml-pro-ts-prev-subtree (C-c C-p)
• yaml-pro-ts-move-subtree-up (s-up)
• yaml-pro-ts-move-subtree-down (s-down)
• yaml-pro-ts-meta-return (M-)
• yaml-pro-ts-convolute-tree (M-?)
• yaml-pro-ts-indent-subtree (C-c >)
• yaml-pro-ts-unindent-subtree (C-c <)
• yaml-pro-ts-mark-subtree (C-c @)
• yaml-pro-ts-paste-subtree (C-c C-x C-y)
• yaml-pro-edit-ts-scalar (C-c ')
  • (use prefix argument C-u to supply an initialization command to set major mode)

Legacy Parser Version

The following documentation is not applicable if you are using yaml-pro-ts-mode as your entry point.

Installation

You can install this package with MELPA under the id yaml-pro. IMPORTANT: You have to have the latest version of yaml.el installed or else this package won't work properly. If your noticing any errors try making sure that you have the correct version of yaml.el installed (https://melpa.org/#/yaml). You can see the parser version with the variable yaml-parser-version and the required version with the variable yaml-pro-required-yaml-parser-version.

You can have yaml-pro-mode setup on yaml-mode loading with the configuration: (add-hook 'yaml-mode-hook #'yaml-pro-mode)

Usage

Run the command yaml-pro-mode to initialize the mode. From there you have the following commands available (with default keybindings).

• yaml-pro-kill-subtree (C-c C-x C-w)
• yaml-pro-up-level (C-c C-u)
• yaml-pro-next-subtree (C-c C-n)
• yaml-pro-prev-subtree (C-c C-p)
• yaml-pro-fold-at-point (C-c C-f)
• yaml-pro-unfold-at-point (C-c C-o)
• yaml-pro-indent-subtree (C-c >)
• yaml-pro-unindent-subtree (C-c <)
• yaml-pro-move-subtree-up (s-up)
• yaml-pro-move-subtree-down (s-down)
• yaml-pro-edit-scalar (C-c ')
  • (use prefix argument C-u to supply an initialization command to set major mode)
• If your buffer is in yaml-pro-mode, imenu should index the entire buffer's paths.

The default bindings are subject to change as this package is in beta

Configuration

Yaml.el, being an Emacs lisp parser, struggles with very large files. You can configure the parser to parse a smaller section of the buffer via a heuristic (probably error prone). Set the custom variable yaml-pro-max-parse-size to be the size of the buffer after which such a heuristic is used.

Recommendations

• Yaml-pro's features compliments LSP and will enhance your YAML editing capabilities even further.

Roadmap

• Edit yaml values in separate buffer (like org-edit-special)
  • block options for how to store the string.
  • save default init command on a path basis
• Easy navigation (yaml-pro-jump)
• Partial tree-parsing for large files
• Implement internally path-at-point.
• Move functionality to tree-sitter (for better error handling), perhaps when tree-sitter in Emacs reaches some critical mass.
• Common YAML mistakes linter
• Tools to work with various template modes. Go-templated YAML is very common but greatly hinders the effectiveness of tools like LSP. Is there something that could be done (even if it's kind of hacky) to alleviate this?

Contributing

Have a suggestion for this package? Feel free to create an issue. I'd love to hear others pain-points when editing YAML.