==================================================== Structured Navigation and Editing with Combobulate

.. image:: docs/combobulate-header.jpg

What is Combobulate?

Combobulate is under active development. Expect bugs. The development branch is usually ahead of the master branch.

Combobulate is a package that adds structured editing and movement to a wide range of programming languages. Unlike most programming major modes that use error-prone imperative code and regular expressions to determine what's what in your code, Combobulate uses Emacs 29's tree-sitter library. Tree-sitter maintains a concrete syntax tree of your code; it gives Combobulate absolute clarity of all aspects of your code, enabling more correct movement and editing than you would otherwise have.

.. image:: docs/combobulate.png

Combobulate extends the existing editing and navigation capabilities of Emacs in addition to adding a range of new features you can't easily do in Emacs without Combobulate.

Combobulate's design philosophy is this:

1. It must be extensible and relatively easy to add new languages.

   Open combobulate-<lang>.el to see how each mode is defined.

2. Commands should broadly work the same across all languages.

3. A strong emphasis on extending and enriching the existing movement and editing commands where possible.

4. Combobulate must have a shallow learning curve.

If you want a guided tour and a deeper understanding of why Combobulate is built the way it is, then I recommend you read:

• Combobulate: Structured Movement and Editing with Tree-Sitter <https://www.masteringemacs.org/article/combobulate-structured-movement-editing-treesitter>__, for an overview of Combobulate.
• Combobulate: Intuitive, Structured Navigation with Tree-Sitter <https://www.masteringemacs.org/article/combobulate-intuitive-structured-navigation-treesitter>__, which talks about the challenges around building sensible and intuitive navigation.
• Combobulate: Editing and Searching with the new Query Builder <https://www.masteringemacs.org/article/combobulate-editing-searching-new-query-builder>__, demonstrating how Combobulate's query builder and search works.
• Combobulate: Interactive Node Editing with Tree-Sitter <https://www.masteringemacs.org/article/combobulate-interactive-node-editing-treesitter>__, where I talk about the carousel interface and how it makes it possible to preview complex edits to your buffer before accepting them.
• Combobulate: Bulk Editing Tree-Sitter Nodes with Multiple Cursors <https://www.masteringemacs.org/article/combobulate-bulk-editing-treesitter-nodes-multiple-cursors>__, where I explain how bulk editing with tools like Combobulate's field editor and multiple cursors work.

What does Combobulate do exactly?

Combobulate is as a companion to the existing movement and editing facilities in Emacs. It's designed to sympathetically improve or supplant editing and movement in many major modes that are otherwise lacking or incorrect. If you're familiar with Emacs's many movement and editing commands, then Combobulate will feel right at home.

There's a large emphasis on Combobulate being both easy to use, and a natural extension to Emacs's already-powerful editing and movement commands.

.. image:: docs/sibling-nav-jsx.gif

For instance, navigating up or down list structures with C-M-u and C-M-d is much improved. Whether you're navigating in or out of structures in Python or JSX elements in Typescript of Javascript.

Combobulate also improves list-like navigation bound to C-M-n and C-M-p, as shown above also. They now understand hierarchical code much better, and they will navigate between statements in code as well as parameters in functions or key pairs in dictionaries.

.. image:: docs/drag-complex.gif

Combobulate also adds a wide range of code editing commands, such as the ability to drag logical pieces of code up or down regardless of the size or complexity of the code. If you can navigate between elements with C-M-<p/n>, then you can drag them around with M-P and M-N.

.. image:: docs/expand-region.gif

Much like the popular expand regions package, Combobulate can also expand the region one syntactically interesting unit at time: first the string point is in, then the list that is in, and so on.

.. image:: docs/mc-edit-1.gif

Combobulate can also place cursors (using the optional multiple cursors package, or using the builtin field editor) at syntactically important points in your code, like: dictionary elements; function arguments; or attributes in JSX elements.

.. image:: docs/clone-dwim.gif

You can clone code with ease. If Combobulate cannot guess the exact thing you want to clone, you'll be asked to interactively preview and pick the right node to clone.

.. image:: docs/splicing.gif

Combobulate can splice your code. Any code. For instance, you can keep some of your HTML tags and splice them into the parent node, removing it in the process.

and much more!

Getting Started with Combobulate

Combobulate has to support your programming language for it to work properly. More importantly, it should ideally be the right Grammar version as the table below explains. If you use a newer, or older, version you may run into issues --- not just in Combobulate, but Emacs also!

Here is a list of the languages currently supported.

+--------------------+--------------------------------------------------------------+--------------------+ |Language |Major Modes |Grammar Version | +--------------------+--------------------------------------------------------------+--------------------+ |CSS |css-mode, css-ts-mode |v0.20.0 | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |HTML [1] |html-mode, html-ts-mode, mhtml-mode, sgml-mode |v0.20.1 | | | | | | | | | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |JSON |json-mode, json-ts-mode |v0.20.2 | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |Javascript+JSX |js-mode, jsN-mode, js-ts-mode, js-jsx-mode, js2-jsx-mode |v0.20.1 | | | | | | | | | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |Typescript+TSX |typescript-mode, typescript-ts-mode, tsx-ts-mode |v0.20.3 | | | | | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |Python |python-mode, python-ts-mode |v0.20.4 | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |YAML |yaml-mode, yaml-ts-mode |v0.5.0 | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |TOML |toml-ts-mode, conf-toml-mode |v0.5.1 | | | | | +--------------------+--------------------------------------------------------------+--------------------+ |Go |go-mode, go-ts-mode |v0.20.0 | +--------------------+--------------------------------------------------------------+--------------------+

Don't see your language? If you want your favourite language added, then why not try it yourself? Have a look at combobulate-json.el for an example.

When you have installed Combobulate correctly -- see below -- then it'll turn on when you open a file in one of its supported major modes. If it does not do this, try M-x combobulate-mode to activate Combobulate's minor mode.

If it's working, you'll see a © appear in your mode line.

At that point, Combobulate is now working. Combobulate rebinds a wide range of common navigation and editing keys. You can see a complete list by typing M-x describe-keymap RET combobulate-key-map.

Note that Combobulate may enable or disable keys depending on the major mode it is active in.

Furthermore, Combobulate ships with a Magit-like transient UI that you ca