tree-edit

tree-edit copied to clipboard

#+HTML:

⚠ Tree-edit is very much a work-in-progress. Expect to run into bugs and breaking changes!

Every programming language has a formally defined structure, but most text editors are completely ignorant to it. As a result, editing can oftentimes devolve into a tedious exercise in character manipulation.

Tree-edit provides [[#supported-languages][language-agnostic]] editing operations that map directly to the structure of the language, abstracting away the process of manually entering syntax. Leveraging the [[https://github.com/tree-sitter/tree-sitter][tree-sitter]] parser, tree-edit always has access to the precise state of the syntax tree -- and directly wields the grammars of the languages under edit to power it's editing capabilities.

• Overview The repository contains two co-existing packages (that will eventually be split).

• [[file:doc/using-tree-edit.org][tree-edit]] :: The core library for structural editing. This library is intended to be used by other elispers who would like to implement their own structural editing or refactoring commands.
• [[file:doc/evil-tree-edit.org][evil-tree-edit]] :: An evil state for structural editing with preconfigured bindings and visualization, as seen in the GIF.

To get an overview of tree-edit's capabilities, check out the [[https://emacsconf.org/2021/talks/structural/][EmacsConf talk]]!

• How does it work?

#+HTML:

Tree-edit relies heavily on the tree-sitter parser, leveraging the JSON intermediate representation that tree-sitter outputs to have a full understanding of what is valid for a given language with no language specific efforts on tree-edit's part.

To learn more about how tree-edit works under the hood, see [[file:doc/implementation.org][this high-level overview]] or check out this [[file:doc/parser-examples.org][org doc with executable code examples]] demonstrating how the syntax generation works.

• Supported languages

| Status | Language | |--------+----------| | ✅ | [[https://github.com/ethan-leba/tree-edit/issues/33][Python]] | | 🔨 | [[https://github.com/ethan-leba/tree-edit/issues/54][C]] | | 🔨 | [[https://github.com/ethan-leba/tree-edit/issues/34][Java]] |

| ✅ | Supported | | 🔶 | Requires custom grammar | | 🔨 | Under development |

Tree-edit is designed to be as language-agnostic as possible. Currently the list of supported languages is not very impressive, but /in theory/ it should be as simple as running a script to preprocess a grammar and adding a configuration file for the language.

See [[https://github.com/ethan-leba/tree-edit/blob/main/doc/using-tree-edit.org#adding-new-languages-to-tree-edit][here]] to learn the process for adding a new language.

• Limitations

A non-comprehensive list of some of the larger limitations that tree-edit currently has:

• Impedance mismatch :: Most tree-sitter grammars were not designed with tree-edit's usecase in mind, so some grammars may be structured inconveniently for tree-edit's purposes.

• Tree-sitter-langs :: Tree-edit currently depends on [[https://github.com/emacs-tree-sitter/tree-sitter-langs][tree-sitter-langs]] to power the tree-sitter parsers, however tree-sitter-langs does not always have the most up-to-date grammars and is missing some languages. If this continues to be an issue a fork may be needed.

• Contributing

Contributions are very much welcome! In particular, adding language files would be a great place to help. Otherwise, the issues are a good place to propose features or find ones to implement.

The project is fairly complex and the documentation is still in progress, so feel free to open a discussion if you're interested in helping out but you're not sure where to start!

• Related projects

• [[https://github.com/mickeynp/combobulate][combobulate]] :: Structural navigation and limited structural editing
• [[https://github.com/manateelazycat/grammatical-edit][grammatical-edit]] :: Smartparens-like using tree-sitter (?)
• [[https://github.com/meain/evil-textobj-tree-sitter][evil-textobj-tree-sitter]] :: Evil mode text objects using tree-sitter queries.
• [[https://github.com/abo-abo/lispy][lispy]] :: Lisp structural editing package -- big inspiration for tree-edit!
• [[https://github.com/Fuco1/smartparens][smartparens]] :: Multilingual package with structural editing limited to matching delimiters.