Announcement
Lightspeed has been deprecated in favor of
Leap, a streamlined but in many
respects enhanced version of its ancestor. Compared to Lightspeed, Leap:
- gets rid of some gimmicks with a low benefit/cost ratio (like “shortcut”
labels), but works the same way in the common case; all the really important
features are there
- has a smaller and simpler visual footprint; it feels like using Sneak
- is much more flexible and extensible; it can be used as an engine for
selecting arbitrary targets, and performing arbitrary actions on them
🌌 lightspeed.nvim
Lightspeed is a motion plugin for Neovim, with a
relatively small interface and lots of innovative ideas, that allow for making
on-screen movements with yet unprecedented ease and efficiency. The aim is to
maximize speed while minimizing mental effort and breaks in the flow, providing
a distractionless experience, that should feel as “native” as possible.
The gist in 30 secs
With Lightspeed you can jump to any positions in the visible window area by
entering a 2-character search pattern, and then optionally a “label” character
for choosing among multiple matches. The plugin aims to substitute all native
commands for in-window navigation (/, ?, gg, f, etc.) with a uniform,
minimal set of atomic (repeatable), multi-axis motions.
So far we have more or less described what
vim-sneak does. The game-changing idea
in Lightspeed is its “clairvoyant” ability: it maps possible futures, and shows
you which keys you will need to press before you actually need to do that, so
despite the use of target labels, you can keep typing in a continuous manner.
You can almost always reach the destination by at most - and very often less
than - four keystrokes in total, that can be typed in one go.
Video tutorial
If this sounds cool enough, read on, or watch the 6-minute introductory video
by DevOnDuty - a very good entry point, showing
the basic usage with straightforward, easy to understand explanations.
Sky chart
Quick links (FAQ)
🧬 Evolution and design
Composite motions do not compose
Everyone has been taught that the “Vim way” of reaching distant points in the
window is using combinations of primitive motions: 8jfx;;. The pipelining
instinct is so deeply ingrained in our Vim-infected mindsets, that many of us
tend to forget that this approach has evolved merely as a consequence of the
limitations of the interface, and is not some divinely decreed, superior way of
doing things; while the “controls as
language” paradigm is an
ingenious aspect of Vim in general, “compound sentences” make no sense for doing
arbitrary jumps between A and B, that should ideally be atomic.
Railways versus jetpacks
EasyMotion attempted to improve
the situation by introducing many new “atoms” - direct routes to a lot of
specific targets. That plugin and its derivatives
(Hop, or
Avy for Emacs) are a bit like convoluted
railway networks, with pre-built stations: each time you have to think about
which train to take, which exit point is the closest to your goal, etc. In
short, they buy speed for cognitive load - a questionable bargain.
Sneak’s approach, however, with its sole focus on using 2-character search
patterns for targeting, and later combining that with the labeling method
inspired by EasyMotion, felt close to perfect at its time. A user of Sneak
embraces a philosophy that is just the opposite of above: you barely need to
think about motions anymore - “sneaking” gets you everywhere you need to be,
with maximal precision. It is like having a jetpack on you all the time.
Always a step ahead of you
Lightspeed takes the next logical step, and eliminates yet more cognitive
overhead, unnecessary keystrokes or interruptions, by blurring the boundary
between one- and two-character search. The idea is to process the input
incrementally - analyzing the available information after each keystroke, to
assist the user and offer shortcuts:
- jump based on partial input: if the character is unique in the search
direction, you will automatically jump after the first input (these characters
are highlighted beforehand, so this is never too surprising)
- shortcut-labels: for some matches, it is possible to use the target
label right after the first input, as if doing 1-character search
- ahead-of-time displayed target labels: in any case, you will see the
label right after the first input, so once you need to type it, your brain
will already have processed it
The last one is probably the biggest game-changer, beating the major problem of
all other general-purpose motion plugins - the frustrating momentary pause
between entering your search pattern and selecting the target. Once you try it,
you will never look back.
To see these features in action, check the screen
recordings in the in-depth
introduction below.
Universal motions
To make the suite complete, Lightspeed implements enhanced f/t-like motions
working over multiple lines, with same-key repeat
available, and a so-called x-mode, providing
exclusive/inclusive variations for 2-character search. Together the four
bi-directional motions (s/x/f/t) make it possible to reach and operate
on the whole window area with high efficiency in all situations when there is no
obvious atomic alternative - like w, {, or % - available.
Other improvements and quality-of-life features
- smart shifting between Sneak/EasyMotion mode - the plugin automatically
jumps to the first match if the remaining matches can be covered by a limited
set of “safe” target labels, but stays in place, and switches to an extended,
more comfortable label set otherwise
- linewise operations are possible via the same interface, by targeting
(potentially off-screen) EOL characters
- uniform repeat interface, and flawless dot-repeat support for operators
(with repeat.vim installed)
- bidirectional search (opt-in)
- cross-window motions
High-level guiding principles
“Some people . . . like tons of features, but experienced users really care
about cohesion, conceptual integrity, and reliability. I think of [the latter]
as the @tpope school.”
(justinmk)
-
80/20: focus on features that are
applicable in all contexts - micro-improvements to the most frequent tasks
accumulate more savings than vanity features that turn out to be rarely needed
in practice
-
Design is making
decisions:
mitigate choice paralysis for the user, regarding both usage (the kinds of
targeting methods provided) and configuration options
-
Sharpen the saw:
the plugin should feel a natural extension to the core, with an interplay as
seamless and intuitive as possible
📚 An in-depth introduction of the key features
If you enter a character that is the only match in the search direction,
Lightspeed jumps to it directly, without waiting for a second input. These
unique characters are highlighted beforehand;
quick-scope is based on a similar
idea, but the intent here is not a “choose me!”-kind of preliminary orientation
(the assumption is that you know where you want to go), more like giving
feedback for your brain while you type.
To further mitigate accidents, a short timeout is set by default, until the
second character in the pair (and only that) is “swallowed”. In operator-pending
mode, the operated area gets a temporary highlight until the next character is
entered.
Ahead-of-time labeling
Target labels are shown ahead of time, right after typing the first input
character. This means you can often type without any serious break in the
flow, almost as if using 3-character search. It is a micro-optimisation, but
can mean the world - Lightspeed simply feels different because of this.
Shortcuts
Made possible by the above, Lightspeed has the concept of “shortcutable”
positions, where the assigned label itself is enough to determine the target:
those you can reach via typing the label character right after the first
input, bypassing the second one. This case is surprisingly frequent in
practice, and in case of harder-to-type sequences, when you’re not rushing
with 200+ CPM, can work really well.
You can see that “shortcuts” are highlighted differently (with a background
color):
Note that this is just an alternative: you do not have to watch out for
these, and nothing bad happens if you type the second input as normal, and
then type the label to reach the target. But in my experience, you can often
guess whether the targeted position will be shortcutable, e.g. if there is a
character that seems to be consistently followed by the same other character
in the window (simple examples: a comment leader, e.g. - in Lua, or an <
if there are lots of <Plug> forms in a section of a Vim config file).
Grouping matches by distance
When there is a large number of matches, we cycle through groups instead of
trying to label everything at once (just like Sneak does it). However, the
immediate next group is always shown ahead of time too, with a different color,
so your brain has a bit of time to process the label, even in case of a distant
group. If the target is right in the second group, you don’t even have to think
in terms of “switching groups” - a blue label should rather be thought of as a
<space>-prefixed, 2-character label. That means we have 2 * number-of-labels
targets right away that are in the efficiently-reachable/low-cognitive-load
range.
Note that Lightspeed keeps the invariant that a label consists of exactly one
character, that should always stay in the same position, once appeared. (No
rolling/flashing sequence of labels, like in case of Hop/EasyMotion.)
🚀 Getting started
Requirements
Dependencies
- repeat.vim is required for the dot-repeat
functionality to work as intended.
Installation
use 'ggandor/lightspeed.nvim'
Plug 'ggandor/lightspeed.nvim'
🏹 Usage
“Just relax and let your mind go blank” - Lightspeed thinks for you. It always
presents information before it is actually needed.
2-character search (s/x)
Without further ado, let’s cut to the chase, and learn by doing.
(Permalink
to the file, if you want to follow along.)
The search is invoked with s in the forward direction, and S in the backward
direction. Let’s press s:
You can see that the search area is greyed out, and you can also see some
characters highlighted. Those are characters with only one occurrence, and you
can jump to them by simply typing the given character.
Let’s target some word containing me. After entering the letter m, the
plugin processes all bigrams starting with it, and from here on, you have all
the visual information you need to reach your specific target:
Now type e. If you aimed for the first match (in frame_minheight), you are
good to go, just continue the work! (The labels for the subsequent matches of
me remain visible until the next keypress, but they are carefully chosen
“safe” letters, guaranteed to not interfere with your following editing
command.) If you aimed for some other match, then type the label, for example
u, and move on to that.
An alternative could have been using a shortcut - skipping the
second pattern character (e in our case), and just typing the label, if it has
an inverse highlight. This is only practical if the first pattern character is
hard to type - it is not worth it to deliberately pause and wait for a potential
shortcut, instead of going with the flow. Shortcuts can always be used as
normal labels - skipping is optional.
To show the last important feature, let’s zoom out a bit, and target the struct
member on the line available = oldwin->w_frame->fr_height; near the bottom,
using the pattern fr, by first pressing s, and then f:
The blue labels indicate the “secondary” group of matches, where we start to
reuse the available labels for a given pair (s, f, n… again). You can
reach those by prefixing the label with <space>, that switches to the
subsequent match group. For example, to jump to the “blue” j target, you
should now press r<space>j. In very rare cases, if the large number of matches
cannot be covered even by two label groups, you might need to press <space>
multiple times, until you see the target labeled, first with blue, and then,
after one more <space>, red.
To summarize, here is the general flow again (in Normal and Visual mode, with
the default settings):
s|S char1 (char2|shortcut)? (<space>|<tab>)* label?
That is,
- invoke in the forward (
s) or backward (S) direction
- enter the first character of the search pattern (might short-circuit after
this, if the character is unique in the search
direction)
- the “beacons” are lit at this point; all potential matches are labeled
(char1 + ?)
- finish the motion by selecting a shortcut, or enter the second
character of the search pattern (might short-circuit after this, if there is
only one match)
- certain beacons are extinguished; only char1 + char2 matches remain
- the cursor automatically jumps to the first match if there are enough
“safe” labels; pressing any other key than a group-switch or a target
label exits the plugin now
- optionally cycle through the groups of
matches that can be labeled at once
- choose a labeled target to jump to (in the current group)
When matches are too close to each other
If a match is too close to the next one, the beacon should be “squeezed” into
the original 2-column box of the match; that is, on top of an A B match, a
B label pair will appear, where the first field shows the character masked
by the label (it is shifted left by a column) - those are the brownish
characters you can see on some of the screenshots. In the most extreme case, the
B field can even be overlapped by the label of another match, but only until
the second input has not been entered - after that, all overlapped matches are
guaranteed to become uncovered.
Operator-pending mode
In Operator-pending mode, there are two different (pairs of) motions available,
providing the necessary additional comfort and precision, since in that case we
are targeting exact positions, and can only aim once, without the means of easy
correction.
z/Z are the equivalents of Normal/Visual s/S, and they follow the
semantics of / and ? in terms of cursor placement and inclusive/exclusive
operational behaviour, including forced motion types (:h forced-motion):
ab···| |···ab
█████· ← Zab zab → ████ab
██████ ← vZab vzab → █████b
The mnemonic for X-mode could be extend/exclude (corresponding to
x/X). It provides missing variants for the two directions:
ab···| |···ab
ab███· ← Xab xab → ██████
ab████ ← vXab vxab → █████b
As you can see from the figure, x goes to the end of the match, including it
in the operation, while X stops just before - in an absolute sense, after -
the end of the match (the equivalent of T for two-character search). In
simpler terms: in X-mode, the relevant edge of the operated area gets an
offset of +2.
The assignment of z and x seems a sensible default, considering that those
keys are free in O-P mode, and the handy visual mnemonic that x is physically
to the right of z on a QWERTY keyboard (think about “pulling” the cursor
forward). We are also acknowledging that “surround” plugins in Operator-pending
mode may benefit more from being able to use the s/S keypair than
general-purpose motion plugins like Lightspeed.
Cross-window motions
gs and gS are like s/S, but they search in the successor/predecessor
windows in the window tree of the current tab page. In practical terms: gs
scans downwards/rightwards, while gS upwards/leftwards. In exceptional cases,
the direction can be switched on the fly with tab after invocation.
Bidirectional search
By mapping to the special keys <Plug>Lightspeed_omni_s and
<Plug>Lightspeed_omni_gs, you can search in the whole window or tab page,
instead of just a given direction. In this case, the matches are sorted by their
screen distance from the cursor, advancing in concentric circles. This is a very
different mental model, but has its own merits too.
1-character search (f/t)
Lightspeed also overrides the native f/F/t/T motions with enhanced
versions that work over multiple lines. In all other respects they behave the
same way as the native ones.
Matching line breaks (linewise motions)
The newline character is represented by <enter> in search patterns. For
example, f<enter> is equivalent to $, and will move the cursor to the end of
the line. s<enter> will label all EOL positions, including off-screen ones
(labeled as <{label} or {label}>), providing an easy way to move to blank
lines. Likewise, a character before EOL can be targeted by s{char}<enter>
(\n in the match is highlighted as ¬ by default).
Repeating motions
Repeating in Lightspeed works in a uniform way across all motions - all of the
following methods (and even combinations of them) are valid options.
Note that for s/x motions the labels will remain available during the whole
time, even after entering instant-repeat mode, if the “safe” label set is in
use.
“Instant” repeat (after jumping)
-
In Normal and Visual mode, the motions can be repeated by pressing the
corresponding trigger key - s, f, t - again. (They continue in the
original direction, whether it was forward or backward.) S, F and T, on
the other hand, always revert the previous repeat. Note that in the case of
T (or X, if mapped), this results in a different, and presumably more
useful behaviour than what you are used to in clever-f and Sneak: it does not
repeat the search in the reverse direction, but puts the cursor back to its
previous position - before the previous match -, allowing for an easy
correction when you accidentally overshoot your target.
-
For f/t-search, there is a special, opt-in repeat mode: pressing the target
character again can also repeat the motion
(opts.repeat_ft_with_target_char).
“Cold” repeat
-
Pressing <backspace> after invoking any of Lightspeed’s motions searches
with the previous input (1- and 2-character searches are saved separately).
Subsequent keystrokes of <backspace> move on to the next match (that is, it
invokes “instant-repeat” mode), while <tab> reverts (just like S/F/T).
-
There are also dedicated <Plug> keys available for repeating the two search
modes. ; and , are mapped to f/t repeat by default (following the native
behaviour), but it might be a good idea to remap them to repeat s/x. If you
would like to set them to repeat the last Lightspeed motion (whether it was
s/x or f/t), see :h lightspeed-custom-mappings. Just like above, subsequent
keystrokes move on to the next match, while the opposite key reverts the
previous motion.
Dot-repeat
Dot-repeat aims to behave in the most intuitive way in different situations -
on special cases, see :h lightspeed-dot-repeat.
See also
For more details, see the docs (:h lightspeed-usage, :h lightspeed-default-mappings), and the in-depth
introduction.
🔧 Configuration
Lightspeed exposes a configuration table (opts), that can be set directly, or
via a setup function that updates the current settings with the values given
in its argument table.
-- NOTE: This is just illustration - there is no need to copy/paste the
-- defaults, or call `setup` at all, if you do not want to change anything.
require'lightspeed'.setup {
ignore_case = false,
exit_after_idle_msecs = { unlabeled = nil, labeled = nil },
--- s/x ---
jump_to_unique_chars = { safety_timeout = 400 },
match_only_the_start_of_same_char_seqs = true,
force_beacons_into_match_width = false,
-- Display characters in a custom way in the highlighted matches.
substitute_chars = { ['\r'] = '¬', },
-- Leaving the appropriate list empty effectively disables "smart" mode,
-- and forces auto-jump to be on or off.
safe_labels = { . . . },
labels = { . . . },
-- These keys are captured directly by the plugin at runtime.
special_keys = {
next_match_group = '<space>',
prev_match_group = '<tab>',
},
--- f/t ---
limit_ft_matches = 4,
repeat_ft_with_target_char = false,
}
For a detailed description of the available options, see the docs: :h lightspeed-config.
You can also set options individually from the command line:
lua require'lightspeed'.opts.jump_to_unique_chars = false
EasyMotion/Hop-style config
By default, Lightspeed is tuned for maximum speed, especially for close and
midrange movements, but the cost of this is increased visual noise and a bit
more hectic experience. For a “calmer” style of navigation, similar to using Hop
or EasyMotion, add the following two lines to your config:
jump_to_unique_chars = false,
safe_labels = {}
These disable the two most obtrusive automagic features (jumping to unique
characters, and to the first 2-character match), while you can still enjoy
Lightspeed’s unique advantage of making the labels visible right as you type.
You might also want to use bidirectional search instead of the default s/S -
for that, see :h lightspeed-custom-mappings.
Keymaps
Lightspeed aims to be part of an “extended native” layer, similar to such
canonized Vim plugins like surround.vim
or targets.vim. Therefore it provides
carefully thought-out defaults, mapping to the following keys: s, S (Normal
and Visual mode), gs, gS (Normal mode), z, Z, x, X
(Operator-pending mode), and - obviously, enhancing the built-in motions - f,
F, t, T, ;, , (all modes). See :h lightspeed-default-mappings for
details.
That said, Lightspeed will check for conflicts with any custom mappings created
by you or other plugins, and will not overwrite them, unless explicitly told so.
To set alternative keymaps, you can use the <Plug> keys listed in :h lightspeed-custom-mappings.
Overridden native keymaps (s/S/gs)
Basic motions, like Lightspeed jumps, should have the absolute least friction
among all commands, since they are the most frequent.
s: for replacing one character, r is the adequate choice; for the rare
case when one wants to continue inserting after that, using cl is more than
fineS: cc is comfortable enough, and it is consistent with yy and ddgs: probably no one misses this shortcut for the :sleep command
Setting keys to repeat the last lightspeed motion (s/x/f/t)
That can be achieved easily with autocommands and expression mappings. See :h lightspeed-custom-mappings.
Using the repeat keys for instant repeat only
Likewise, see :h lightspeed-custom-mappings for an example snippet.
Disabling the default keymaps
See :h lightspeed-disable-default-mappings.
User events
Lightspeed triggers User events on entering/exiting, so that you can set
up autocommands, e.g. to change the values of some editor options while the
plugin is active. For details, check :h lightspeed-events.
Highlight groups
For customizing the highlight colors, see :h lightspeed-highlight. If you are
a colorscheme author/maintainer, please also check out the appropriate
guide.
In case you - as a user - are not happy with a certain colorscheme’s
integration, you could force reloading the default settings by calling
lightspeed.init_highlight(true). The call can even be wrapped in an
autocommand to automatically re-init on every colorscheme change:
autocmd ColorScheme * lua require'lightspeed'.init_highlight(true)
This can be tweaked further, you could e.g. check the actual colorscheme, and
only execute for certain ones, etc.
Notes
-
While the plugin is active, the actual cursor is down on the command line, but
its position in the window is kept highlighted, using the attributes of the
built-in Cursor highlight group - should you experience any issues, you
should check the state of that first. Alternatively, you can tweak the
LightspeedCursor group, to highlight the cursor in a custom way.
-
If you are using VSCode with NeoVim extension, you need to set
hi LightspeedCursor gui=reverse
in your nvim config to support the fake cursor and make Lightspeed work.
-
The otherwise useful multiline scoping of f/F/t/T can be undesirable when
recording macros or executing :normal. This is being worked
on, but as an API
change, it should be thought through carefully. In the meantime, here is a
rather elegant workaround for macros by rktjmp
(caveat: this causes a problem for same-key
repeat):
nmap <expr> f reg_recording() . reg_executing() == "" ? "<Plug>Lightspeed_f" : "f"
nmap <expr> F reg_recording() . reg_executing() == "" ? "<Plug>Lightspeed_F" : "F"
nmap <expr> t reg_recording() . reg_executing() == "" ? "<Plug>Lightspeed_t" : "t"
nmap <expr> T reg_recording() . reg_executing() == "" ? "<Plug>Lightspeed_T" : "T"
For :normal, you could use the bang-version :normal!, although that disables
all custom mappings, so that is only a half-measure.
❔ Why is there no feature X or Y?
Smart case-sensitivity?
See #64. It is
unfortunately impossible for this plugin, by design. (Because of ahead-of-time
labeling, it would require showing two different labels - corresponding to two
different futures - at the same time.)
Arbitrary-length search pattern?
That is practically labeling /? matches, right? It is overkill for our
purposes, IMO. Again, we are optimizing for the common case. A 2-character
pattern, with the secondary group of matches displayed ahead of time, should be
enough for making an on-screen jump efficiently 99% of the time; in that
remaining 1%, just live with having to press Space multiple times. (What the
heck are you editing, on what size of display, by the way?)
Labeled matches for 1-character search?
That would be pretty pointless, for two reasons. First, the pause is inevitable
then, since it is physically impossible to show labels ahead of time. And
usually there are too many matches, so we should use multi-character labels.
(The closer ones you could probably reach with sab directly, instead of fa +
l.) Now, ask yourself the question: isn’t it much better to type two on-screen
characters and then a “little bit surprising” label almost in one go (sabl),
than to type one on-screen character, and wait for (most probably) two
surprising characters to appear (fa + lm)?
Second, labeling matches makes it impossible to directly jump to the first
target when doing operations - we’re making our lives harder in the most
frequent case (e.g. couldn’t do a simple dfa).
In general, if you need to start thinking about whether to use f or s,
scanning the context, then the whole thing is screwed already. Minimal mental
effort. That is the mantra of Lightspeed. You should think of f and t as
shortcuts for very specific situations, when you can count the number of
occurrences, and thus reach for them in a totally automatic way, and not as
equals of the s/x motions.
I miss Sneak’s “vertical scope” feature…
That might indeed be useful, but I considered it would needlessly complicate the
plugin. Sometime in the future we might add that though.
If you work with tabular data frequently, you can make a mapping instead that
pre-populates the normal search prompt with horizontal bounds based on the
count, something like the following (:h /\%v):
" note: g? in the example overwrites the superfun native rot13 command
nnoremap <expr> g/ '/<C-u>\%>'.(col(".")-v:count1).'v\%<'.(col(".")+v:count1).'v'
nnoremap <expr> g? '?<C-u>\%>'.(col(".")-v:count1).'v\%<'.(col(".")+v:count1).'v'
🌜 Contributing
Every contribution is very welcome, be it a bug report, fix, or just a
discussion-initiating question - please do not feel intimidated. If you have any
problems with the documentation especially, do not hesitate to reach out.
Tip: besides the issue
tracker, be sure to also
check/use Discussions
for announcements, simple Q&A, and open-ended brainstorming.
Regarding feature requests and enhancements, consider the guiding
principles first. If you have a different
vision, feel free to fork the plugin and improve upon it in ways you think are
best - I am glad to help -, but I’d like to keep this version streamlined, and
save it from feature creep. Of course, that doesn’t mean that I am not open for
discussions.
Lightspeed is written in Fennel, and compiled to Lua
ahead of time. I am aware that using Fennel might limit the number of available
contributors, but compile-time macros, pattern matching, and a bunch of other
features are simply too much of a convenience. (Learning a Lisp can be an
eye-opening experience anyway, even though Fennel is something of a half-blood.)
As for “building”, the plugin is really just one .fnl file at the moment, that
you can compile into the lua folder with the Fennel executable manually, or
using the provided Makefile.
💡 Inspired by
As always, we are standing on the shoulders of giants:
- Sneak: a big fan of this - absolute
respect for justinmk, besides his work on
Neovim, for making a motion plugin that I have considered to be close to
perfect for a long time
- clever-f
- Hop: a promising take on EasyMotion in
the Neovim-era
- EasyMotion: the venerable one,
of course
评论