Skip to content

About

Composable editor operations for Emacs, controllable by voice

Topics

Resources

Stars

11 stars

Watchers

2 watching

Forks

Latest commit

 

History

418 Commits

Folders and files

Repository files navigation

cursorfree.el

An extensible spoken language for controlling Emacs.

Description

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.

Contents

Setup

Recommended dependencies

  • 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.

Installation

This package is available on MELPA as 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.

Usage

The objects acted upon by the cursorfree operations are called targets. Targets can be any elisp object, but are most often objects representing a region in some buffer.

Spoken command structure

The typical structure of a command is <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.

Primitives

A primitive is a target that can be referred to directly.
Spoken formDescriptionFunction
[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.
thisPoint, or region if active.cursorfree-this
thatThe target of the last action.cursorfree-that
sourceThe source of the last action.cursorfree-source
clipThe kill ring.cursorfree-kill-ring
primaryThe primary selection.cursorfree-primary-selection
its, itselfThe result of the last evaluation.

Actions

An action consumes targets and performs a side effect. The most important actions are pre, take, change, bring and move.

The following table lists the different actions, both the spoken form and the corresponding library function.

Spoken formDescriptionFunction
takeSelect targetcursorfree-select
copyCopy to kill ringcursorfree-copy
chuckDelete targetcursorfree-delete
cloneInsert a copy after itselfcursorfree-clone
jumpMove point to targetcursorfree-jump
preMove point to beginningcursorfree-jump-beginning
postMove point to endcursorfree-jump-end
commentComment outcursorfree-do-make-comment
uncommentUncommentcursorfree-do-uncomment
indentIndentcursorfree-do-indent
narrowNarrow buffer to targetcursorfree-do-narrow
titleCapitalize each wordcursorfree-do-capitalize
upcaseConvert to upper casecursorfree-do-upcase
downcaseConvert to lower casecursorfree-do-downcase
crownScroll target to top of windowcursorfree-crown
centerScroll target to center of windowcursorfree-center
bottomScroll target to bottom of windowcursorfree-bottom
pickFollow or activate thing at targetcursorfree-pick
fuseRemove all whitespace within targetcursorfree-fuse
tidyTidy up whitespace and formattingcursorfree-tidy
joinJoin into one linecursorfree-join
breakInsert newline before targetcursorfree-break
flashTemporarily highlightcursorfree-pulse
helpShow help at targetcursorfree-help
drinkInsert empty line before, jump therecursorfree-drink
pourInsert empty line after, jump therecursorfree-pour
dropInsert empty line beforecursorfree-drop
floatInsert empty line aftercursorfree-float
puffInsert empty lines aroundcursorfree-puff

Some actions have more complex spoken forms:

Spoken formDescriptionFunction
bring <target> to/after/before <target>Move copy to/after/before targetcursorfree-do-bring
move <target> to/after/before <target>Move target to/after/before targetcursorfree-do-move
change <target> [to <target>]Change target [to target]cursorfree-do-change
swap <target> with <target>Swap target with targetcursorfree-swap
wrap <target> with <character>Wrap target with charactercursorfree-wrap
unwrap <target>Remove enclosing delimitercursorfree-unwrap
rewrap <target> with <character>Replace enclosing delimitercursorfree-rewrap
hunt <target> [in <target>] [context <number>]Occur search [in target] [context N]cursorfree-occur

Modifiers

A modifier transforms a target into a new target.
Spoken formDescriptionFunction
paintExpand to surrounding non-whitespacecursorfree-paint
leftpaintExpand left to non-whitespacecursorfree-paint-left
rightpaintExpand right to non-whitespacecursorfree-paint-right
trimShrink to exclude surrounding whitespacecursorfree-trim
lineExtend to non-whitespace on linecursorfree-line
tailExtend to end of linecursorfree-line-right
headExtend to start of linecursorfree-line-left
blockExtend to surrounding paragraphcursorfree-block
tokenExtend to containing hatty tokencursorfree-token
commentExtend to containing commentcursorfree-comment
stringExtend to containing string literalcursorfree-string-literal
wordExtend to containing wordcursorfree-word
symbolExtend to containing symbolcursorfree-symbol
sentenceExtend to containing sentencecursorfree-sentence
everythingWhole buffer contentscursorfree-everything
visibleVisible portion of buffercursorfree-visible
every instanceAll occurrences of targetcursorfree-every-instance
nextNext occurrencecursorfree-next
prevePrevious occurrencecursorfree-previous
beginningEmpty region at start of targetcursorfree-beginning
endEmpty region at end of targetcursorfree-end
bufferBuffer containing targetcursorfree-buffer-or-current
splitWindow containing targetcursorfree-window-or-selected
inside [<character>]Expand to inside enclosing delimitercursorfree-inside
outside [<character>]Expand to include enclosing delimitercursorfree-outside

Infixes

The region spanning two targets can be referred to with <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.

Extending cursorfree

Custom target types can be defined by overriding the generic functions 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.

Versioning system

This project uses semantic versioning. While still on 0.y.z, an increment of y signals breaking changes.

About

Composable editor operations for Emacs, controllable by voice

Topics

Resources

Stars

11 stars

Watchers

2 watching

Forks

Releases

Contributors

Languages