doomemacs/modules/completion/selectrum/README.org

#+TITLE:   completion/selectrum
#+DATE:    February 16, 2021
#+SINCE:   v3.0.0
#+STARTUP: inlineimages

* Table of Contents :TOC_2:noexport:
- [[#description][Description]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
  - [[#jump-to-navigation][Jump-to navigation]]
  - [[#project-search--replace][Project search & replace]]
  - [[#in-buffer-searching][In-buffer searching]]
  - [[#selectrum-integration-for-various-completing-commands][Selectrum integration for various completing commands]]
  - [[#orderless-filtering][Orderless filtering]]

* Description
This module provides Selectrum integration for a variety of Emacs commands, as
well as a unified interface for project search and replace, powered by ripgrep.

#+begin_quote
TODO
#+end_quote

** Module Flags
+ ~+prescient~ Enables prescient filtering and sorting for Selectrum searches
  instead of orderless.

** Plugins
[[https://github.com/raxod502/selectrum][selectrum]]
[[https://github.com/minad/consult][consult]]
[[https://github.com/oantolin/embark/][embark]]
[[https://github.com/oantolin/embark/][embark-consult]]
[[https://github.com/minad/marginalia][marginalia]]
[[https://github.com/oantolin/orderless][orderless]] (unless ~+prescient~)
[[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]
[[https://github.com/raxod502/prescient.el][prescient]] (~+prescient~)
[[https://github.com/minad/consult/][consult-flycheck]] (~:checkers syntax~)

* Prerequisites
This module has no prerequisites.

* Features

Selectrum and friends modify and use the built-in ~completing-read~ function,
used by any function that requires completion. Due to this the full scope of
these packages is too large to cover here, so we will detail Doom-specific
additions:

** Jump-to navigation
This module provides an interface to navigate within a project using
=projectile=:

https://assets.doomemacs.org/completion/selectrum/projectile.png

| Keybind              | Description                         |
|----------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project             |
| =SPC f f=, =SPC .=   | Jump to file from current directory |
| =SPC s i=            | Jump to symbol in file              |

** Project search & replace
This module provides interactive text search and replace using ripgrep.

| Keybind   | Description              |
|-----------+--------------------------|
| =SPC s p= | Search project           |
| =SPC s P= | Search another project   |
| =SPC s d= | Search this directory    |
| =SPC s D= | Search another directory |

https://assets.doomemacs.org/completion/selectrum/search.png

Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u=
otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files.

This module also provides Ex Commands for evil users:

| Ex command             | Description                                                      |
|------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~  | Search project (if ~!~, include hidden files)                    |
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |

The optional `!` is equivalent to the universal argument for the previous
commands.

-----

These keybindings are available while a search is active:

| Keybind             | Description                                        |
|---------------------+----------------------------------------------------|
| =C-;=, =<leader> a= | Open an ~embark-act~ menu to chose a useful action |
| =C-c C-;=           | Open a buffer with your search results             |
| =C-c C-e=           | Open a writable buffer of your search results      |
| =C-SPC=             | Preview the current candidate                      |
| =C-M-j=             | Scroll down and preview.                           |
| =C-M-k=             | Scroll up and preview.                             |
| =C-RET=             | Open the selected candidate in other-window        |

Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed
with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil
users).

https://assets.doomemacs.org/completion/selectrum/search-replace.png

** TODO In-buffer searching
This module provides some in buffer searching bindings:

+ =SPC s s= (~isearch~)
+ =SPC s S= (~+selectrum/search-symbol-at-point~ via ~consult-line~)
+ =SPC s b= (~consult-line~)

https://assets.doomemacs.org/completion/selectrum/buffer-search.png

An ~occur-edit~ buffer can be opened from ~consult-line~ with =C-c C-e=.

** Selectrum integration for various completing commands
*** General
| Keybind        | Description                   |
|----------------+-------------------------------|
| =M-x=, =SPC := | Enhanced M-x                  |
| =SPC '=        | Resume last Selectrum session |

*** Jump to files, buffers or projects
| Keybind              | Description                           |
|----------------------+---------------------------------------|
| =SPC RET=            | Find bookmark                         |
| =SPC f f=, =SPC .=   | Browse from current directory         |
| =SPC p f=, =SPC SPC= | Find file in project                  |
| =SPC f r=            | Find recently opened file             |
| =SPC p p=            | Open another project                  |
| =SPC b b=, =SPC ,=   | Switch to buffer in current workspace |
| =SPC b B=, =SPC <=   | Switch to buffer                      |

=SPC b b= and =SPC ,= support changing the workspace you're selecting a buffer from
via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to
selecting a buffer from the third workspace by typing =3 SPC= into the prompt,
or the last workspace by typing =0 SPC=.

=SPC f f= and =SPC .= support exporting to a =wdired= buffer using =C-c C-e=.

*** Search
| Keybind   | Description                               |
|-----------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project           |
| =SPC s b= | Search the current buffer                 |
| =SPC s d= | Search this directory                     |
| =SPC s D= | Search another directory                  |
| =SPC s i= | Search for symbol in current buffer       |
| =SPC s p= | Search project                            |
| =SPC s P= | Search another project                    |
| =SPC s s= | Search the current buffer (incrementally) |

** Orderless filtering
When using orderless to filter through candidates, the default behaviour is for
each space separated input to match the candidate as a regular expression or
literally.

Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more finegrained filtering, which
you can use to further specify each space separated input in the following ways:
| Input            | Description                                |
|------------------+--------------------------------------------|
| =!foo=           | match without literal input =foo=          |
| =`bar= or =bar`= | match input =bar= as an initialism         |
| ==baz= or =baz== | match only with literal input =baz=        |
| =~qux= or =qux~= | match input =qux= with fuzzy/flex matching |