[WIP] native type-ahead navigation mode (navigate-as-you-type)

[M4he]

ISSUE TYPE

• Improvement/feature implementation

RUNTIME ENVIRONMENT

• Operating system and version: Debian 10 x86_64
• Terminal emulator and version: xfce4-terminal 0.8.7.4
• Python version: 3.7.3
• Ranger version/commit: master (081e731)
• Locale: de_DE.UTF-8

CHECKLIST

• [X] The CONTRIBUTING document has been read [REQUIRED]
• [X] All changes follow the code style [REQUIRED]
• [X] All new and existing tests pass [REQUIRED]
• [X] Changes require config files to be updated
  • [X] Config files have been updated
• [X] Changes require documentation to be updated
  • [X] Documentation has been updated
• [ ] Changes require tests to be updated
  • [ ] Tests have been updated

DESCRIPTION

Introduces native type-ahead navigation as an alternative mode for the normal browser view. The feature is completely optional and doesn't change ranger's behavior when left turned off.

MOTIVATION AND CONTEXT

Ranger does not include a native type-ahead mode (also known as "search-as-you-type" or "navigate-as-you-type" among others). When you know your directory structures by heart, nothing is faster than to navigate by typing the first characters of things and hitting enter in a split of a second. Midnight Commander as well as nnn also provide this feature. A lot of GUI file managers have this behavior enabled by default as well.

See also #1429

Example

Imagine the following directory structure:

/home/user/coart/
/home/user/code/shell-extensions
/home/user/code/side-projects/random/
/home/user/code/side-projects/ranger/

The goal is to open up ranger, starting at / and then entering the following key sequence:

<h> <Enter> <u> <Enter> <c><o><d> <Enter> <s><i> <Enter> <r><a><n><g> <Enter>

... to reach the ranger/ directory, visually aided by the steps in-between getting highlighted in ranger and the view traversing accordingly in realtime, much like travel works.

Here is why find, travel and scout don't cut it from my perspective:

• if enabled, type-ahead should be its own mode which is active permanently (even automatically when ranger is started) as the main method of navigation
• it should not end if a directory is entered or the view returns from editing a file
• the mode should not obscure the information in the status bar
• keybindings should be separate from console, e.g. so that arrow keys still work for navigation in the browser

TESTING

So far, only manual "hands-on" testing has been done. Extensive testing is still pending.

Here's a selection of manual tests done:

• navigating using type-ahead (ofc)
• starting ranger with set typeahead_mode true in the config file
• starting ranger with set typeahead_mode false in the config file
• using set typeahead_mode! to toggle the mode during runtime
• using type-ahead in conjunction with tabs
• using type-ahead in both miller and multipane view modes

ARCHITECTURE

Behavior

With this mode activated in ranger:

• if keys are pressed whose character might be part of a filename (alphanumeric plus a few speical chars), they are consumed by the type-ahead search instead of being interpreted as keybinding
• it will use the defined tamap keybindings instead of the map ones in the default browser view
• the keybinding for typeahead_bypass (<C-x> per default) will make the next keybinding be interpreted using the regular map keymap, which makes it possible to still access all usual keybindings
• if a type-ahead filter is active, it will be displayed in the status bar at the end of the left part, prefixed with /

If this mode is not enabled (default), ranger will behave as usual. It can be toggled at runtime using set typeahead_mode!.

Code extensions

• ext/typeahead.py module to implement the core functionality of type-ahead

Commands

• tamap and untamap to define/undefine keybindings for the type-ahead mode

Actions

• typeahead_next: selects the next matching entry in the current directory (if any)
• typeahead_previous: selects the next matching entry (reverse order) in the current directory (if any)
• typeahead_clear: clears/resets the current type-ahead filter string
• typeahead_delete <amount=n>: deletes characters from the filter string (backspace behavior)
• typeahead_bypass: temporarily disables type-ahead mode until the next normal map keybinding has been executed (allowing to reach normal keybinds)

Settings

• typeahead_mode (bool) to enable or disable the mode
• typeahead_case_insensitive (bool) whether the type-ahead search is case-insensitive

[M4he]

Despite from extensive testing still required, here's a list of things that I still need to address:

visual indicator

Does this mode need a visual indicator when activated? In its current state, if a filter string has been typed its visible as /<string> in the status bar which is different from normal mode. However, if the filter is empty (nothing has been typed), you can't tell type-ahead mode from normal mode visually. I'd like to refrain from using a --VISUAL---style marker in the status bar as visual mode does it because it obscures the permission display. On the other hand, I currently have no clue where to put such indicator and in what fashion.

Any ideas?

compatibility with visual mode

So, type-ahead mode and visual mode are not mutually exclusive. The type-ahead functionality also works in visual mode but currently does not seem to integrate with the visual mode's marking behavior well enough as it seems. As I'm fairly new to ranger and the concept of this visual mode I still need to get a better grasp of how a sensible integration might look like.

[asoymos]

If my opinion is of some value, I think this feature is worthwhile. Travel is very flexible but has been a little difficult of understand for me. First when you type :travel most commands need to be entered, this one need a space. Second I agree it would be very uselful to be able to still navigate with arrows, for example in mc with lynx navigation enabled going from / to icons require u→sh→ic→ but in ranger it require :travel u<enter>sh icons and even sometimes applications is selected and I have no way to select icons down.

[toonn]

@asoymos, thank you, your comparison makes it slightly more understandable what the difference is with :travel or :find. Being able to use the arrow keys while traveling could definitely be useful. I do wonder whether more code can be shared between this and travel.

[adamsmd]

For those who come after me, with the default keybindings, Tab and Shift-Tab can be used in place of Down and Up Arrow to navigate the search results. One can also use :cmap to bind <Up> or <C-u> to move up=1 or move left=1. The result is still rough around the edges though (e.g., directory filters sticking around when the directory is exited and reentered, (AFAIK) no keystroke to toggle the regex mode, etc.).

[toonn]

Hmm, maybe we can make it possible for commands like travel to temporarily remap certain keys. History navigation is not super useful when you're traveling so remapping the arrow keys makes sense to me. Though we do have to take into account when the travel command isn't being typed but navigated by with the console history navigation.

Would that cover most of the reason for having this be a separate mode?

[malteprinzler]

any news on this? sounds like a very useful feature!

[M4he]

any news on this? sounds like a very useful feature!

FWIW, this PR is effectively abandoned, sorry - I forgot it was still open. I have not maintained the patchset any further and I haven't been using ranger in a long time. I don't know how much the code has changed by now and how much of this is still compatible at all.

I'll close this PR now. If anyone wants to work on this, feel free to take the changes of this PR as a basis (if they are still of any value at all) and create a new PR.