Skip to content

Commit b433eab

Browse files
pokeypokey
committed
Add hidden documentation for advanced keyboard interface
Adds hidden documentation for the experimental advanced keyboard interface with appropriate warnings about its stability. Hides the keyboard category from the sidebar navigation. Includes examples from the test suite with concise key sequence explanations.
1 parent dfaff22 commit b433eab

File tree

2 files changed

+245
-0
lines changed

2 files changed

+245
-0
lines changed

‎packages/cursorless-org-docs/src/docs/user/experimental/keyboard/advanced/README.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Advanced Keyboard Interface (Experimental)
2+
3+
**⚠️ WARNING: This is a bleeding-edge experimental feature that is likely to break in future versions. Use at your own risk. ⚠️**
4+
5+
The Cursorless Advanced Keyboard Interface provides a fully customizable keyboard-based command system for controlling Cursorless. This document explains how to set up and use this experimental feature.
6+
7+
## Setup Instructions
8+
9+
To use the Advanced Keyboard Interface, you need to:
10+
11+
1. Copy the configuration into your VSCode settings.json
12+
2. Configure your keybindings to enter and exit the keyboard mode
13+
14+
### Step 1: Copy the Configuration
15+
16+
Copy the configuration from this file into your VSCode settings.json:
17+
18+
```
19+
packages/cursorless-vscode/src/keyboard/keyboard-config.fixture.json
20+
```
21+
22+
The configuration should be merged directly into your settings.json file, not copied as a separate file.
23+
24+
### Step 2: Configure Keybindings
25+
26+
Add the following to your VSCode `keybindings.json`:
27+
28+
```json
29+
{
30+
"key": "ctrl+c",
31+
"command": "cursorless.keyboard.modal.modeOn",
32+
"when": "editorTextFocus"
33+
},
34+
{
35+
"key": "escape",
36+
"command": "cursorless.keyboard.escape",
37+
"when": "cursorless.keyboard.listening && editorTextFocus && !suggestWidgetMultipleSuggestions && !suggestWidgetVisible"
38+
}
39+
```
40+
41+
## Understanding the Interface
42+
43+
The Advanced Keyboard Interface works through a grammar-based command system. Commands are composed of sequences of key presses that correspond to different terminals in the grammar.
44+
45+
### Command Grammar
46+
47+
The interface's grammar is defined in `packages/cursorless-vscode/src/keyboard/grammar/grammar.ne`. A visual representation of this grammar can be viewed at [Cursorless Keyboard Modal Railroad](https://www.cursorless.org/keyboard-modal-railroad).
48+
49+
### Configuration Sections
50+
51+
The configuration file is divided into several sections, each mapping keyboard sequences to different components of the grammar:
52+
53+
#### Scope Types
54+
55+
```json
56+
"cursorless.experimental.keyboard.modal.keybindings.scope": {
57+
"i": "line",
58+
"sb": "paragraph",
59+
";": "statement",
60+
// additional scopes...
61+
}
62+
```
63+
64+
#### Actions
65+
66+
```json
67+
"cursorless.experimental.keyboard.modal.keybindings.action": {
68+
"at": "setSelection",
69+
"ah": "setSelectionBefore",
70+
// additional actions...
71+
}
72+
```
73+
74+
#### Colors
75+
76+
```json
77+
"cursorless.experimental.keyboard.modal.keybindings.color": {
78+
"d": "default",
79+
"b": "blue",
80+
// additional colors...
81+
}
82+
```
83+
84+
#### Shapes
85+
86+
```json
87+
"cursorless.experimental.keyboard.modal.keybindings.shape": {
88+
"hx": "ex",
89+
"hf": "fox",
90+
// additional shapes...
91+
}
92+
```
93+
94+
#### Miscellaneous
95+
96+
```json
97+
"cursorless.experimental.keyboard.modal.keybindings.misc": {
98+
"fx": "combineColorAndShape",
99+
"fk": "makeRange",
100+
// additional misc commands...
101+
}
102+
```
103+
104+
#### Special Marks
105+
106+
```json
107+
"cursorless.experimental.keyboard.modal.keybindings.specialMark": {
108+
"mc": "cursor"
109+
}
110+
```
111+
112+
#### Modifiers
113+
114+
```json
115+
"cursorless.experimental.keyboard.modal.keybindings.modifier": {
116+
"n": "nextPrev",
117+
"*": "every",
118+
// additional modifiers...
119+
}
120+
```
121+
122+
#### VSCode Commands
123+
124+
```json
125+
"cursorless.experimental.keyboard.modal.keybindings.vscodeCommand": {
126+
"va": "editor.action.addCommentLine",
127+
// additional VSCode commands...
128+
}
129+
```
130+
131+
#### Paired Delimiters
132+
133+
```json
134+
"cursorless.experimental.keyboard.modal.keybindings.pairedDelimiter": {
135+
"wl": "angleBrackets",
136+
"wt": "backtickQuotes",
137+
// additional delimiters...
138+
}
139+
```
140+
141+
## Examples
142+
143+
Here are some example command sequences (spaces are added only for readability and should be ignored when typing the commands):
144+
145+
### `dx fa dy c`
146+
- What it does: Delete two tokens marked with default color hats
147+
- Voice command equivalent: "change plex and yank"
148+
- Breakdown:
149+
- `dx`: targets token with default color hat over 'x'
150+
- `fa`: make a list/combine targets ("and")
151+
- `dy`: targets token with default color hat over 'y'
152+
- `c`: clear and set selection (exits Cursorless mode)
153+
154+
### `da *st c`
155+
- What it does: Delete every token
156+
- Voice command equivalent: "change every token air"
157+
- Breakdown:
158+
- `da`: targets token with default color hat over 'a'
159+
- `*`: every (select all instances of the scope)
160+
- `st`: token scope
161+
- `c`: clear and set selection (exits Cursorless mode)
162+
163+
### `db 3st c`
164+
- What it does: Delete three consecutive tokens starting with blue hat
165+
- Voice command equivalent: "change three tokens bat"
166+
- Breakdown:
167+
- `db`: targets token with default color hat over 'b'
168+
- `3`: three (select this number of instances)
169+
- `st`: token scope
170+
- `c`: clear and set selection (exits Cursorless mode)
171+
172+
### `dd -3st c`
173+
- What it does: Delete three consecutive tokens going backwards from default hat
174+
- Voice command equivalent: "change three tokens backwards drum"
175+
- Breakdown:
176+
- `dd`: targets token with default color hat over 'd'
177+
- `-3`: three tokens backward
178+
- `st`: token scope
179+
- `c`: clear and set selection (exits Cursorless mode)
180+
181+
### `db wp c`
182+
- What it does: Delete the parentheses and their contents
183+
- Voice command equivalent: "change parens bat"
184+
- Breakdown:
185+
- `db`: targets token with default color hat over 'b'
186+
- `wp`: parentheses pair
187+
- `c`: clear and set selection (exits Cursorless mode)
188+
189+
### `dw wj c`
190+
- What it does: Delete any pair of matching delimiters and their contents
191+
- Voice command equivalent: "change pair whale"
192+
- Breakdown:
193+
- `dw`: targets token with default color hat over 'w'
194+
- `wj`: any pair (matches any surrounding pairs)
195+
- `c`: clear and set selection (exits Cursorless mode)
196+
197+
### `da mi c`
198+
- What it does: Delete the content inside delimiters while preserving the delimiters
199+
- Voice command equivalent: "change inside air"
200+
- Breakdown:
201+
- `da`: targets token with default color hat over 'a'
202+
- `mi`: modifier to select inside the target
203+
- `c`: clear and set selection (exits Cursorless mode)
204+
205+
### `db mt wb mi c`
206+
- What it does: Delete from the token to the end of the containing curly bracket block
207+
- Voice command equivalent: "change inside tail curly bat"
208+
- Breakdown:
209+
- `db`: targets token with default color hat over 'b'
210+
- `mt`: extend through end of (tail modifier)
211+
- `wb`: curly brackets
212+
- `mi`: modifier to select inside
213+
- `c`: clear and set selection (exits Cursorless mode)
214+
215+
### `da aw wp`
216+
- What it does: Wrap the token in parentheses
217+
- Voice command equivalent: "round wrap air"
218+
- Breakdown:
219+
- `da`: targets token with default color hat over 'a'
220+
- `aw`: wrap action
221+
- `wp`: parentheses (round)
222+
223+
### `da fs dc st c`
224+
- What it does: Delete tokens in a vertical slice from one token to another
225+
- Voice command equivalent: "keyboard air; keyboard slice past cap; change token"
226+
- Breakdown:
227+
- `da`: targets token with default color hat over 'a'
228+
- `fs`: make vertical range (slice)
229+
- `dc`: targets token with default color hat over 'c'
230+
- `st`: token scope
231+
- `c`: clear and set selection (exits Cursorless mode)
232+
233+
## Known Limitations
234+
235+
- The keyboard interface grammar and configuration may change significantly in future versions
236+
- Not all Cursorless capabilities are accessible through the keyboard interface
237+
- Error handling is minimal
238+
- Documentation may not match implementation as this is rapidly evolving
239+
240+
## Customization
241+
242+
You can customize any of the keyboard mappings by modifying the configuration in your settings.json. The key sequences can be adjusted to match your preferences, but the command structure must follow the grammar defined in the railroad diagrams.

‎packages/cursorless-org-docs/src/docs/user/experimental/keyboard/advanced/_category_.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"className": "hidden"
3+
}

0 commit comments

Comments
 (0)