zkry / yaml-pro

Edit YAML in Emacs like a pro
GNU General Public License v3.0
137 stars 9 forks source link

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

MELPA

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/tree-sitter-grammars/tree-sitter-yaml . The tree-sitter re-implementation supports everything below, as well as the following:

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

Formatter

formatter

New in yaml-pro, a pretty formatter in Emacs Lisp powered by treesitter.

Eldoc (tree-sitter)

eldoc

Imenu

imenu

Subtree pasting (tree-sitter)

screenshot

Editing text in detached buffer

screenshot

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)

jumping feature

You can use imenu as well.

Moving subtrees up and down

moving subtrees feature

Folding subtrees (legacy parser)

folding feature

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

Killing subtrees

killing feature

Indenting subtrees

indenting feature

Tree-sitter version

To activate the mode, run M-x yaml-pro-ts-mode. You can have this activated automatically by adding this to your configuration: (add-hook 'yaml-mode-hook 'yaml-pro-ts-mode 100) (or 'yaml-ts-mode-hook).

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/tree-sitter-grammars/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

Pretty formatter

yaml-pro now comes with the addition of a new formatting command yaml-pro-format. This requires tree-sitter to work. There are different settings you can toggle on the formatter. For ease of customization I recommend usind M-x customize-variable. The following is the customization options.

Easy movement with repeat map

With the following configuration and repeat-mode enabled, you can easily move around the YAML tree after executing one of the movement commands.

;; the original bindings will work as well, these are shorter if you prefer them.
(keymap-set yaml-pro-ts-mode-map "C-M-n" #'yaml-pro-ts-next-subtree)
(keymap-set yaml-pro-ts-mode-map "C-M-p" #'yaml-pro-ts-prev-subtree)
(keymap-set yaml-pro-ts-mode-map "C-M-u" #'yaml-pro-ts-up-level)
(keymap-set yaml-pro-ts-mode-map "C-M-d" #'yaml-pro-ts-down-level)
(keymap-set yaml-pro-ts-mode-map "C-M-k" #'yaml-pro-ts-kill-subtree)
(keymap-set yaml-pro-ts-mode-map "C-M-<backspace>" #'yaml-pro-ts-kill-subtree)
(keymap-set yaml-pro-ts-mode-map "C-M-a" #'yaml-pro-ts-first-sibling)
(keymap-set yaml-pro-ts-mode-map "C-M-e" #'yaml-pro-ts-last-sibling)

(defvar-keymap my/yaml-pro/tree-repeat-map
  :repeat t
  "n" #'yaml-pro-ts-next-subtree
  "p" #'yaml-pro-ts-prev-subtree
  "u" #'yaml-pro-ts-up-level
  "d" #'yaml-pro-ts-down-level
  "m" #'yaml-pro-ts-mark-subtree
  "k" #'yaml-pro-ts-kill-subtree
  "a" #'yaml-pro-ts-first-sibling
  "e" #'yaml-pro-ts-last-sibling
  "SPC" #'my/yaml-pro/set-mark)

(defun my/yaml-pro/set-mark ()
  (interactive)
  (my/region/set-mark 'my/yaml-pro/set-mark))

(defun my/region/set-mark (command-name)
  (if (eq last-command command-name)
      (if (region-active-p)
          (progn
            (deactivate-mark)
            (message "Mark deactivated"))
        (activate-mark)
        (message "Mark activated"))
    (set-mark-command nil)))

Special thanks to @uqix for sharing this configuration.

Legacy Parser Version

The following documentation is not applicable if you are using yaml-pro-ts-mode as your entry point. It's not recommented however due to its slow parsing speed.

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 100)

Usage

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

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

Roadmap

Contributing

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