petkaantonov / jump-and-select

A vscode extension to move the cursor to next or previous chosen character with optional selections. Works with multiple selections.

Jump and Select

Jump/move the cursor to the next or previous occurrence of some character.
You can also optionally select the text from the current cursor position to that next/previous character.
Works with keybindings and macros. You can use multiple characters in a keybinding or macro.
Works with multiple cursors.

---

How It Works

• Choose one of your keybindings, say Alt+f to jump forward.

1. Trigger that command: Alt+f,
2. Type a character (it will not be shown), and
3. Cursor moves to that next character.

• Using jump-and-select.jumpBackwardMultiMode and jump-and-select.jumpForwardMultiMode commands:

---

Extension Settings

        Cursor movement or selections will not "wrap" beyond the start or end of the file.

        Searches are case-sensitive.

• jump-and-select.restrictSearch   :   { boolean }   default = "document"

     "line"     :   Move the cursor or select within the current line only
     "document   :   Move the cursor or select within the entire document

• jump-and-select.putCursorForward   :   { string }   default = "beforeCharacter"

     "beforeCharacter"  :   Move the cursor or select to before the next chosen character
     "afterCharacter"    :   Move the cursor or select to after the next chosen character

• jump-and-select.putCursorBackward   :   { string }   default = "beforeCharacter"

     "beforeCharacter"  :   Move the cursor or select to before the previous chosen character
     "afterCharacter"    :   Move the cursor or select to after the previous chosen character

Examples:

"jump-and-select.putCursorForward": "beforeCharacter" if text is  |abcde|f  jumping forward from a to f would put the cursor before f.

"jump-and-select.putCursorForward": "afterCharacter"   if text is  |abcdef|  jumping forward from a to f would put the cursor after f.

Selections will act the same way: either the selection will not include the chosen character (the one you type) or the selection will include that character.

Example of the three settings (in settings.json):

	"jump-and-select.restrictSearch"        :      "line",
	"jump-and-select.putCursorForward"      :      "beforeCharacter",
	"jump-and-select.putCursorBackward"     :      "afterCharacter",

---

Extension Commands

• jump-and-select.jumpForward            :   Move to the next occurrence of the character.   Alt+f

• jump-and-select.jumpForwardSelect      :   Select from the cursor to the next occurrence of the character.   Shift+Alt+f

• jump-and-select.jumpBackward         :   Move to the previous occurrence of the character.   Alt+b

• jump-and-select.jumpBackwardSelect   :   Select from the cursor to the previous occurrence of the character.   Shift+b

   Multimode Commands

What is MultiMode? It means you can trigger the command ONCE and then move/select as many times as you want. Demo:

A reminder in the Status Bar appears that the only way to exit/stop the command and get back to normal text insertion/deletion is to exit the command by hitting the Return (unfortunately Escape will not work). That Status Bar reminder will hide when you do exit the command successfully and reappear the next time you invoke a MultiMode command.

• jump-and-select.jumpForwardMultiMode            :   Move to the next occurrence of the character.   Alt+m   Alt+f

• jump-and-select.jumpForwardSelectMultiMode      :   Select from the cursor to the next occurrence of the character.   Shift+Alt+m   Shift+Alt+f

• jump-and-select.jumpBackwardMultiMode         :   Move to the previous occurrence of the character.   Alt+m   Alt+b

• jump-and-select.jumpBackwardSelectMultiMode   :   Select from the cursor to the previous occurrence of the character.   Shift+Alt+m   Shift+b

To trigger Alt+m   Alt+f you can hold down the Alt key and then hit m and then f and release and MultiMode is running. These are just suggested keybindings, use whatever you want. Think of Alt+m as standing for MultiMode.

Color options for the StatusBarItem are pretty limited. Right now you can use these three settings:

"workbench.colorCustomizations": {

	"statusBarItem.errorBackground": "#fff",   // yes, errorBackground is the only background color supported
	"statusBarItem.errorForeground": "#000"
	"statusBarItem.hoverBackground": "#ff0000",
}

The errorBackground default is #f00 or red. Changing it will change the errorBackground color for all extensions or vscode itself that provide a StatusBarItem that needs an errorBackground. In this demo I left the settings at their default values.

If you see this error message you may have forgotten to exit (via the Enter) the MultiMode and tried to initiate some other jump-and-select command:

---

When you trigger one of these commands, you will not see the next character you type - instead that character will trigger a search for that character.

The bindings listed above are default keybindings, you can change them like this in your keybindings.json:

{
  "key": "alt+f",                  // <== change this to whatever you want
  "command": "jump-and-select.jumpForward"
  // "when": "editorTextFocus && editorLangId == javascript"  // for example
}

{
  "key": "alt+r",
  "command": "jump-and-select.jumpBackwardSelect",
  "args": {

    // the four args that can be used in a keybinding

    "text": "hello",                          // <== can use strings or regexp's here
    // "text": "#\\d+\n"                      //  double-escaped where necessary		                                      

    // "putCursorForward": "afterCharacter"   // or "beforeCharacter"
    "putCursorBackward": "beforeCharacter",   // or "afterCharacter"

    "restrictSearch": "document"              // or "line" to search in the current line only
  }
}

In this last example, you would use putCursorBackward and not putCursorForward because the command jumpBackwardSelect is searching backward and thus putCursorForward is ignored. For commands that are looking forward use putCursorForward.

The available args have the same names as the settings, like "jump-and-select.putCursorForward" minus the extension name prefix.

For more on using keybindings and macros.

---

A note on the precedence of the options.

We have seen that there are three possibilities for the options (like "restrictSearch" for example):

1. options in a keybinding or macro;
2. options in settings; and
3. no options in either (1) or (2).

The options take precedence in that order: 1 > 2 > 3. All the options have defaults, so even in case (3) the default values will be applied.

---

1.   If after triggering one of the commands you decide you don't want to move the cursor after all, Enter will exit the command and you can resume typing.

2.   If after triggering one of the commands you decide you want to move the cursor first, left/rightArrow keys or clicking in the file elsewhere will move the cursor without exiting the command. You can then type a chosen character to move/select from the new cursor position.

---

Known Issues

This extension may not play well with vim or neovim or similar due to registering the same 'type' command as those extensions do. However, this extension disposes of that binding immediately after typing one character so it may not be an issue...

Small intellisense issue in keybindings. If you highlight an existing option and then Ctrl+Space it does not give you the option of the existing highlighted option (seeing it as already used).

TODO

[ X ] - Explore a setting for moving cursor before or after typed character.
[ X ] - Explore use of text arg in keybindings (including macros).
[ X ] - Explore use of beforeCharacter and afterCharacter arg in keybindings (including macros).
[ X ] - Explore use of multi-character queries in macros or keybindings.
[ X ] - Explore use of regexp queries in macros or keybindings.
[ X ] - Add a StatusBarItem reminder for multiMmode.
[ X ] - Add intellisense for keybindings.
[  ] - Explore allowing input via 'paste' as well.
[  ] - Add a setting to make searches case-insensitive, if requested.

Release Notes

• 0.0.1   Initial release of jump-and-select extension.

• 0.0.2   Change behavior of go to previous character, put cursor before the character.

• 0.0.41   Added setting to restrict movement/selection to current line or full document.
       Added setting to move/select before or after the chosen character.
       Separated settings to put cursor before/after the chosen character for both forward/backward.
       Added support for keybindings and all args therein.
       Added support for regular expressions in keybindings and macros.
       Renamed to restrictSearch setting and args option.
       Added intellisense/completions for keybindings, including args options.

---