Keyboard version

[pokey]

Discussing keyboard version of cursorless

[anthonyjclark]

Hello, I watched your Strange Loop talk and I really like what I saw. This project is very inspiring. Thank you!

After reading the modal keyboard interface documentation, I am interested in transitioning some of my current modal keyboard workflow to cursorless. I am wondering if you could provide some advise.

I currently use a custom modal keyboard configuration based on the vscode-modal-editor extension. I'd love to start gradually replace some of my custom functionality with cursorless.

For example, here is a snippet from my configuration that I use to select an argument/parameter:

		// ...
		"E": {
			// ...
			"a": [
				findText(false, false, true, true, "[\(,]"),
				{ command: "cursorRight", when: "_ctx.lineAt(_ctx.pos).text[_ctx.pos.character] == '('" },
				findText(true, true, false, true, "[\),]"),
				{ command: "cursorLeftSelect", when: "_ctx.lineAt(_ctx.pos).text[_ctx.pos.character] == ')'" },
			],
		// ...

I'd like to replace this with the tree-sitter commands in cursorless---with the idea to eventually replace most (if not all) of my current setup with cursorless (including jumping).

Here are two questions:

1. How do I encode "select argument" as a vscode command using cursorless commands. (I was digging through the extension but I thought I might be better suited by asking you first. It looks like I would want to first execute a target command, and then an action.)
2. How do I disable some functionality (e.g., hats) while I decide what I'd like to use from cursorless? (I understand that this one might not be reasonable given the project's goals.)

[anthonyjclark]

Thanks again! I was creating a bit of a grammar in my head as I read through the docs and thought that an actual grammar might help me understand the model a bit better.

[pokey]

I'm planning to do a big push on keyboard stuff in the next week or so; getting lots of interest, so it's time. I like your idea of staying away from voice to keep a fresh eye. Stay tuned

[anthonyjclark]

After reading the documentation (and a few issues) and playing around with it a bit. Here are some early thoughts:

Spoken Model

command   : action target
target    : primitive | compound
primitive : mark | modifier+ mark?
compound  : range | list

Keyboard Model

Enter listening mode with ctrl-c.

command   : target action
target    : primitive | compound
primitive : mark | modifier+ mark?
compound  : range | list

Thoughts

• I like the select-first model for keyboards
• The modal keyboard interface videos are not overly useful standalone. I would guess you all are aware of this and that they are mostly placeholders.
• (Opinion incoming) I would introduce the concepts in a tutorial style prior to more thorough documentation. Something like this:

Tutorial Example

Let's say that you want to delete the testing() function below.

function whatever() {|
    const hello = "world";
}

function testing() {
    const bar = "baz";
}

In Cursorless you will execute a command of this form: command : target action.

For our first example, the target is the entire testing() function (along with handling its white-space appropriately), and the action is deletion.

To initiate the command, you need to put your editor into a mode in which Cursorless can listen for input. In VSCode you can add the following to your keybindings.json file:

    {
        "key": "ctrl+c",
        "command": "cursorless.keyboard.modal.modeOn",
        "when": "editorTextFocus"
    },
    {
        "key": "escape",
        "command": "cursorless.keyboard.escape",
        "when": "cursorless.keyboard.listening && editorTextFocus && !suggestWidgetMultipleSuggestions && !suggestWidgetVisible"
    },

Now you can type ctrl-c to type Cursorless commands, and esc to go back to typical VSCode behavior.

At this point, Cursorless does not know what keys it should associate with its various targets and actions. Let's add a few bindings.

  "cursorless.experimental.keyboard.modal.keybindings.scopes": {
    "f": "namedFunction",
  },
  "cursorless.experimental.keyboard.modal.keybindings.actions": {
  },
  "cursorless.experimental.keyboard.modal.keybindings.colors": {
    "d": "default",
  },

You might have noticed that we've left the set of actions empty. That is because we need to handle some keys differently. backspace is one such key. It is natural to delete something with backspace, so let's add that to keybindings.json:

    // ...
    {
        "key": "backspace",
        "command": "cursorless.keyboard.targeted.runActionOnTarget",
        "args": "remove",
        "when": "cursorless.keyboard.modal.mode && editorTextFocus"
    }
    // ...

Now you can target any "default" mark (we'll explain marks soon) in testing(). (Assume we have a gray dot above the letter z in the token baz). To delete testing() we can now type: ctrl-c dzf backspace.

Some thoughts on my tutorial

• It would be nice to use selectable text, but I don't know if that is possible with the hats.
• I imagine Cursorless will come with default bindings? If so, the language will need to change.
• I would continue the tutorial to build up a few scopes, a few actions, and a few colors.

[pokey]

Yeah I think tutorial is a great way to introduce information. We've been big on diataxis philosophy lately. Re adding customizations, I do wonder if we really want to force users to build up their config from scratch, so I'm not sure that's where we'd want tutorial to start. Prob better to start with a full config and tutorial teaches them how to use it and maybe make small tweaks

[pokey]

Fwiw Cursorless keyboard is now expressed using a formal grammar. It's still highly experimental, but is a nice compact way to express key sequences, and allows us to generate nice railroads 😊

[pokey]

I wonder if we want to introduce some redundancy in the keyboard encoding. Cost of a typo seems higher than normal typing, and even there there is arguably the redundancy built into language. Cc/ @josharian

[josharian]

Maybe? I guess I'd be interested in the following redundant-ish additions:

• Press key to "submit" an action, rather than having it happen automatically. Provides an opportunity to fix typos and/or bail.
• Explicit keystroke to re-assign hats (raw notes from learning to use cursorless keyboard #2111 (comment))
• Added structure, e.g. all actions require "a" prefix.

(Should I file issues for these? Discussion items on #2111? Not sure how we want to keep this laundry list organized.)

[pokey]

I think pressing key to submit could make sense, tho I'm imagining getting a head of steam and moving fast enough that you wouldn't want to pause and check before you press that key. I guess the visual feedback from flashes as things get deleted / added helps, and then you can undo if something doesn't happen as you expect

I think we can just discuss these things in this thread, as they're all related to error tolerance

[Kn0rk]

I think i would also favor the undo action over an submit to excecute mode.