dance/README.md

Dance

Kakoune-inspired key bindings for Visual Studio Code.

Huh?

Dance provides Kakoune-inspired commands and key bindings for Visual Studio Code.

These key bindings are (mostly) compatible with Kakoune's, but are meant to be an addition to Visual Studio Code, rather than an emulation layer on top of it.

Why VS Code, and not Kakoune directly?

• Kakoune is an efficient and lightweight editor with a very small ecosystem. VS Code is an entire IDE with a huge ecosystem and many existing extensions.
• Kakoune is Unix only.

Why Kakoune's key bindings, and not Vim's?

• Whether you prefer Vim, Emacs or Kakoune key bindings is a matter of preference. I, for one, prefer Kakoune's.
• Vim's key bindings are already available to VS Code users.

Why is it merely 'inspired' by Kakoune?

• Unlike VSCodeVim which attempts to emulate Vim, Dance's only goal is to provide VS Code-native commands and key bindings that are inspired by Kakoune.
• Kakoune, Vim and VS Code are all fully-fledged text editors; therefore, they have overlapping features. For instance, where VSCodeVim provides its own multi-cursor and command engines to feel more familiar to existing Vim users, Dance leaves multi-cursor mode and editor commands to VS Code entirely.

User Guide

For most commands, the usage is the same as in Kakoune. However, the following changes have been made:

Pipes

• Pipes no longer accept shell commands, but instead accept 'expressions', those being:

  • #<shell command>: Pipes each selection into a shell command (the shell is taken from the terminal.external.exec value).

  • /<pattern>[/<replacement>[/<flags>]: A RegExp literal, as defined in JavaScript. Do note the addition of a replacement, for commands that add or replace text.

  • <JS expression>: A JavaScript expression in which the following variables are available:

    • $: Text of the current selection.
    • $$: Array of the text of all the selections.
    • i: Index of the current selection.

    Depending on the result of the expression, it will be inserted differently:

    • string: Inserted directly.
    • number: Inserted in its string representation.
    • boolean: Inserted as true or false.
    • null: Inserted as null.
    • undefined: Inserted as an empty string.
    • object: Inserted as JSON.
    • Any other type: Leads to an error.

Examples

• /(\d+),(\d+)/$1.$2/g replaces 12,34 into 12.34.
• i + 1 replaces 1,1,1,1,1 into 1,2,3,4,5, assuming that each selection is on a different digit.

Miscellaneous changes

• Changing the mode will also change the editor.lineNumbers configuration value to on in insert mode, and relative in normal mode. This behavior cannot be disabled, but if you'd like to submit a PR to make this optional, please do!^(This feature is implemented in src/extension.ts, in function onActiveModeChanged).

Troubleshooting

Dance uses the built-in VS Code key bindings, and therefore does not override the type command. However, it sometimes needs access to the type command, in dialogs and register selection, for instance. Consequently, it is not compatible with extensions that always override the type command, such as VSCodeVim; these extensions must therefore be disabled.

Progress

This project is a WIP. It's brand new, and far from complete.

In the following list, if a command is implemented, then its extending equivalent (activated while pressing Shift) then likely is implemented as well.

Most (but not all) commands defined in commands are implemented.

• Basic movements:
  • Arrows, hjkl.
  • Move to character, move until character.
  • Move to next word, move to previous word.
• Insert mode:
  • Enter insert mode with a, i, o, and their Alt / Shift equivalents.
  • Exit insert mode with Escape.
• Basic selections:
  • Search in selections.
  • Split in selections.
  • Split selections by lines.
  • Extend selections by taking lines.
  • Trim selections.
• Pipes.
• Object selection.
• Yanking:
  • Yank.
  • Paste.
• Changes:
  • Join.
  • Replace.
  • Delete.
  • Indent.
  • Dedent.
  • Swap case.
• Macros.
• Registers.

State

I'm working on this project as much as I can. However, since this is mostly something I'm making for myself, I'm focusing on getting this working fast. Therefore, I'm not focusing much on unit tests for now.

Contributions are welcome.