An extensible spoken language for controlling Emacs.
cursorfree.el provides an extensible spoken language for controlling Emacs by voice, leveraging the richness of spoken language to provide commands more complex than would be normally comfortable with a keyboard.The underlying model for controlling Emacs is also exposed as an Elisp library, and can be used outside the area of voice control.
This package was inspired by cursorless, a package providing similar faculties for VSCode.
- hatty.el for a way to query arbitrary positions in the visible buffer text.
- multiple-cursors.el for integration with multiple-cursors. Useful when operating on multiple targets at once.
cursorfree.
To use the spoken command language, first set up phony.el. You can
then enable the spoken command language of cursorfree through
cursorfree-phony-mode.
<action> <target>, with
<target> a sequence of primitives, modifiers, and infixes.
A primitive is something that immediately evaluates to a target. For
example, row 42 evaluates to a target for line 42.
Modifiers form a pipeline for targets. block is a modifier
selecting the paragraph of a target. Using the aforementioned
primitive, row 42 block would evaluate to a target for the paragraph
at line 42.
Infixes are like modifiers, but combine two targets. past is an
infix selecting a range between two other targets. row 42 past row
67 would evaluate to a target ranging from lines 42 to 67.
Actions take a target and perform some operation. For example, chuck
row 42 past row 67 removes lines 42 to 67.
Some actions have a more complex structure. One commonly used action
with more complex structure is bring <target> to <target>. It
overwrites the second target with the contents of the first one. So,
bring row 13 past row 15 to row 42 block would overwrite the
paragraph at line 42 with the text spanning line 13 to 15.
There are a heap of different actions, primitives, modifiers and infixes, not all of them related to the regions of the buffer. Following is a list of all available elements for forming a command, along with the underlying function whenever it is available.
A primitive is a target that can be referred to directly.| Spoken form | Description | Function |
|---|---|---|
| [color] [shape] <character> | Token under a hatty hat (see hatty package). | |
| car <character> | The character itself as a string. | |
| word <word> | The word itself as a string. | |
| numb <number> | The number itself. | |
| row <number> | Line with the given number (modulo 100). | cursorfree-row-modulo-100 |
| long row <number> | Line with the given number (exact). | cursorfree-row |
| split <number> | Window with the given winum.el index. | |
| this | Point, or region if active. | cursorfree-this |
| that | The target of the last action. | cursorfree-that |
| source | The source of the last action. | cursorfree-source |
| clip | The kill ring. | cursorfree-kill-ring |
| primary | The primary selection. | cursorfree-primary-selection |
| its, itself | The result of the last evaluation. |
pre, take, change, bring and move.
The following table lists the different actions, both the spoken form and the corresponding library function.
| Spoken form | Description | Function |
|---|---|---|
| take | Select target | cursorfree-select |
| copy | Copy to kill ring | cursorfree-copy |
| chuck | Delete target | cursorfree-delete |
| clone | Insert a copy after itself | cursorfree-clone |
| jump | Move point to target | cursorfree-jump |
| pre | Move point to beginning | cursorfree-jump-beginning |
| post | Move point to end | cursorfree-jump-end |
| comment | Comment out | cursorfree-do-make-comment |
| uncomment | Uncomment | cursorfree-do-uncomment |
| indent | Indent | cursorfree-do-indent |
| narrow | Narrow buffer to target | cursorfree-do-narrow |
| title | Capitalize each word | cursorfree-do-capitalize |
| upcase | Convert to upper case | cursorfree-do-upcase |
| downcase | Convert to lower case | cursorfree-do-downcase |
| crown | Scroll target to top of window | cursorfree-crown |
| center | Scroll target to center of window | cursorfree-center |
| bottom | Scroll target to bottom of window | cursorfree-bottom |
| pick | Follow or activate thing at target | cursorfree-pick |
| fuse | Remove all whitespace within target | cursorfree-fuse |
| tidy | Tidy up whitespace and formatting | cursorfree-tidy |
| join | Join into one line | cursorfree-join |
| break | Insert newline before target | cursorfree-break |
| flash | Temporarily highlight | cursorfree-pulse |
| help | Show help at target | cursorfree-help |
| drink | Insert empty line before, jump there | cursorfree-drink |
| pour | Insert empty line after, jump there | cursorfree-pour |
| drop | Insert empty line before | cursorfree-drop |
| float | Insert empty line after | cursorfree-float |
| puff | Insert empty lines around | cursorfree-puff |
Some actions have more complex spoken forms:
| Spoken form | Description | Function |
|---|---|---|
| bring <target> to/after/before <target> | Move copy to/after/before target | cursorfree-do-bring |
| move <target> to/after/before <target> | Move target to/after/before target | cursorfree-do-move |
| change <target> [to <target>] | Change target [to target] | cursorfree-do-change |
| swap <target> with <target> | Swap target with target | cursorfree-swap |
| wrap <target> with <character> | Wrap target with character | cursorfree-wrap |
| unwrap <target> | Remove enclosing delimiter | cursorfree-unwrap |
| rewrap <target> with <character> | Replace enclosing delimiter | cursorfree-rewrap |
| hunt <target> [in <target>] [context <number>] | Occur search [in target] [context N] | cursorfree-occur |
| Spoken form | Description | Function |
|---|---|---|
| paint | Expand to surrounding non-whitespace | cursorfree-paint |
| leftpaint | Expand left to non-whitespace | cursorfree-paint-left |
| rightpaint | Expand right to non-whitespace | cursorfree-paint-right |
| trim | Shrink to exclude surrounding whitespace | cursorfree-trim |
| line | Extend to non-whitespace on line | cursorfree-line |
| tail | Extend to end of line | cursorfree-line-right |
| head | Extend to start of line | cursorfree-line-left |
| block | Extend to surrounding paragraph | cursorfree-block |
| token | Extend to containing hatty token | cursorfree-token |
| comment | Extend to containing comment | cursorfree-comment |
| string | Extend to containing string literal | cursorfree-string-literal |
| word | Extend to containing word | cursorfree-word |
| symbol | Extend to containing symbol | cursorfree-symbol |
| sentence | Extend to containing sentence | cursorfree-sentence |
| everything | Whole buffer contents | cursorfree-everything |
| visible | Visible portion of buffer | cursorfree-visible |
| every instance | All occurrences of target | cursorfree-every-instance |
| next | Next occurrence | cursorfree-next |
| preve | Previous occurrence | cursorfree-previous |
| beginning | Empty region at start of target | cursorfree-beginning |
| end | Empty region at end of target | cursorfree-end |
| buffer | Buffer containing target | cursorfree-buffer-or-current |
| split | Window containing target | cursorfree-window-or-selected |
| inside [<character>] | Expand to inside enclosing delimiter | cursorfree-inside |
| outside [<character>] | Expand to include enclosing delimiter | cursorfree-outside |
<target> past
<target>.
Sometimes, one wants to act on multiple targets. This can be achieved
with the infix and, which collects targets into a sequence.
Modifiers and actions act on all the targets of the sequence. For
example, chuck row 23 and row 42 block creates a sequence with the
targets row 23 and row 42, applies block to them to get the
paragraph at those lines, and finally deletes those two paragraphs
with chuck.
cursorfree-get and/or cursorfree-put. This allows many built-in
actions to work on them, particularly “bring”.
Custom modifiers and primitives can be added by defining phony rules
that contribute to cursorfree-modifier and cursorfree-primitive.
Custom actions are added by using phony-defun and capturing on
cursorfree-target.