<commit_before>#+title:    Consult: Non-Opinionated Completion System
#+author:   <NAME>
#+email:    <EMAIL>
#+date:     2021:07:17
#+property: header-args:emacs-lisp :lexical t
#+tags:
#+STARTUP: fold

Yet another completion framework for Emacs. Jeez, you think there would be
enough of them at this point to satisfy these Emacs sycophants, but no.  Consult
is a bit of a different creature than Helm and Ivy. In fact, Consult is more
closely a relatively of Counsel than of Ivy, but whereas Counsel is a suite of
utility functions implemented on Ivy's completion system, Consult is a suite of
utility functions implemented using only Emacs' built-in =completing-read= API.
Furthermore, whereas Counsel integrates only with Ivy, Consult integrates with
any narrowing completion UI that supports =completing-read=, such as the default
Emacs completion system, =icomplete-vertical=, Selectrum, and Vertico. This
makes Consult far more flexible and widely usable than Counsel or Helm since a
myriad systems benefit from Consult's functions.

* What is Consult really?
  Consult is designed to fulfill the same role for Selectrum and Vertico that
  Counsel fills for Ivy. You can think of Selectrum/Vertico, Consult, and Embark
  as a similar tool suite to Ivy, Counsel, and Swiper, although these triplets
  do not match up one-to-one. The main difference between these two tool suites
  is that Ivy, Counsel, and Swiper are exclusive to one another, and must be
  used as a package deal. Consult is completely agnostic to the narrowing
  completion UI you choose. It could be Selectrum, Vertico, the built-in Emacs
  completion system, or any other compatible framework.

* =use-package= specification
  #+begin_src emacs-lisp
    (use-package consult
      :after projectile
      :demand t
      ;; Replace bindings. Lazily loaded due by `use-package'.
      :general
      (my/user-leader-def
        ;; C-c bindings (mode-specific-map)
        "h" 'consult-history
        "m" 'consult-mode-command
        "B" 'consult-bookmark
        "k" 'consult-kmacro)
      (general-def
        ;; orig. repeat-complex-command
        "C-x M-:" 'consult-complex-command
        ;; A better alternative to `persp-switch-to-buffer'
        "C-x b" 'consult-project-buffer
        ;; orig. switch-to-buffer
        "C-x C-b" 'consult-buffer
        ;; orig. switch-to-buffer-other-window
        "C-x 4 b" 'consult-buffer-other-window
        ;; orig. switch-to-buffer-other-frame
        "C-x 5 b" 'consult-buffer-other-frame
        ;; Custom M-# bindings for fast register access
        "M-#" 'consult-register-load
        ;; orig. abbrev-prefix-mark (unrelated)
        "M-'" 'consult-register-store
        "C-M-#" 'consult-register
        ;; Other custom bindings
        ;; orig. yank-pop
        "M-y" 'consult-yank-pop
        ;; orig. apropos-command
        "<help> a" 'consult-apropos
        ;; M-g bindings (goto-map)
        "M-g e" 'consult-compile-error
        ;; Alternative: consult-flycheck
        "M-g f" 'consult-flymake
        ;; orig. goto-line
        "M-g g" 'consult-goto-line
        ;; orig. goto-line
        "M-g M-g" 'consult-goto-line
        ;; Alternative: consult-org-heading
        "M-g o" 'consult-outline
        "M-g m" 'consult-mark
        "M-g k" 'consult-global-mark
        "M-g i" 'consult-imenu
        "M-g I" 'consult-imenu-multi
        ;; M-s bindings (search-map)
        "M-s f" 'consult-find
        "M-s L" 'consult-locate
        "M-s g" 'consult-grep
        "M-s G" 'consult-git-grep
        "M-s r" 'consult-ripgrep
        "M-s l" 'consult-line
        "M-s m" 'consult-multi-occur
        "M-s k" 'consult-keep-lines
        "M-s u" 'consult-focus-lines
        ;; recentf
        [remap recentf-open-files] 'consult-recent-file
        ;; Isearch integration
        "M-s e" 'consult-isearch-history)
      (general-def isearch-mode-map
        ;; orig. isearch-edit-string
        "M-e" 'consult-isearch-history
        ;; orig. isearch-edit-string
        "M-s e" 'consult-isearch-history
        ;; needed by consult-line to detect isearch
        "M-s l" 'consult-line
        ;; needed by consult-line to detect isearch
        "M-s L" 'consult-line-multi)
      (my/evil-leader-def
        ;; Open the fancy consult-buffer navigator.
        "cb" 'consult-bookmark)
      :hook
      ;; Enable automatic preview at point in the *Completions* buffer.
      ;; This is relevant when you use the default completion UI,
      ;; and not necessary for Vertico, Selectrum, etc.
      (completion-list-mode . consult-preview-at-point-mode)
      ;; The :init configuration is always executed (Not lazy)
      :init
      ;; Optionally tweak the register preview window.
      ;; This adds thin lines, sorting and hides the mode line of the window.
      (advice-add #'register-preview :override #'consult-register-window)
      ;; Configure other variables and modes in the :config section,
      ;; after lazily loading the package.
      :custom
      ;; Optionally configure the register formatting. This improves the register
      ;; preview for `consult-register', `consult-register-load',
      ;; `consult-register-store' and the Emacs built-ins.
      (register-preview-delay 0)
      (register-preview-function #'consult-register-format)
      ;; Use Consult to select xref locations with preview
      (xref-show-xrefs-function #'consult-xref)
      (xref-show-definitions-function #'consult-xref)<commit_msg>emacs: Add more consult docs<commit_after>#+title:    Consult: Non-Opinionated Completion System
#+author:   <NAME>
#+email:    <EMAIL>
#+date:     2021:07:17
#+property: header-args:emacs-lisp :lexical t
#+tags:
#+STARTUP: fold

Yet another completion framework for Emacs. Jeez, you think there would be
enough of them at this point to satisfy these Emacs sycophants, but no.  Consult
is a bit of a different creature than Helm and Ivy. In fact, Consult is more
closely a relatively of Counsel than of Ivy, but whereas Counsel is a suite of
utility functions implemented on Ivy's completion system, Consult is a suite of
utility functions implemented using only Emacs' built-in =completing-read= API.
Furthermore, whereas Counsel integrates only with Ivy, Consult integrates with
any narrowing completion UI that supports =completing-read=, such as the default
Emacs completion system, =icomplete-vertical=, Selectrum, and Vertico. This
makes Consult far more flexible and widely usable than Counsel or Helm since a
myriad systems benefit from Consult's functions.

* What is Consult really?
  Consult is designed to fulfill the same role for Selectrum and Vertico that
  Counsel fills for Ivy. You can think of Selectrum/Vertico, Consult, and Embark
  as a similar tool suite to Ivy, Counsel, and Swiper, although these triplets
  do not match up one-to-one. The main difference between these two tool suites
  is that Ivy, Counsel, and Swiper are exclusive to one another, and must be
  used as a package deal. Consult is completely agnostic to the narrowing
  completion UI you choose. It could be Selectrum, Vertico, the built-in Emacs
  completion system, or any other compatible framework.

* Narrowing the completion buffer
One of the primary features of Consult is /narrowing/ the completion buffer, not
only based on a text search expression, but also based on pre-configured
/categories/ for the completion source(s). To narrow based on category, the user
must type the =consult-narrow-key= following by a key configured to narrow the
completion buffer to some category. For example:

1. =M-x consult-buffer=
2. Type the =consult-narrow-key= (usually =<= or =C-+=)
3. Type =p= to narrow the completion buffer to project buffers

* =use-package= specification
  #+begin_src emacs-lisp
    (use-package consult
      :after projectile
      :demand t
      ;; Replace bindings. Lazily loaded due by `use-package'.
      :general
      (my/user-leader-def
        ;; C-c bindings (mode-specific-map)
        "h" 'consult-history
        "m" 'consult-mode-command
        "B" 'consult-bookmark
        "k" 'consult-kmacro)
      (general-def
        ;; orig. repeat-complex-command
        "C-x M-:" 'consult-complex-command
        ;; A better alternative to `persp-switch-to-buffer'
        "C-x b" 'consult-project-buffer
        ;; orig. switch-to-buffer
        "C-x C-b" 'consult-buffer
        ;; orig. switch-to-buffer-other-window
        "C-x 4 b" 'consult-buffer-other-window
        ;; orig. switch-to-buffer-other-frame
        "C-x 5 b" 'consult-buffer-other-frame
        ;; Custom M-# bindings for fast register access
        "M-#" 'consult-register-load
        ;; orig. abbrev-prefix-mark (unrelated)
        "M-'" 'consult-register-store
        "C-M-#" 'consult-register
        ;; Other custom bindings
        ;; orig. yank-pop
        "M-y" 'consult-yank-pop
        ;; orig. apropos-command
        "<help> a" 'consult-apropos
        ;; M-g bindings (goto-map)
        "M-g e" 'consult-compile-error
        ;; Alternative: consult-flycheck
        "M-g f" 'consult-flymake
        ;; orig. goto-line
        "M-g g" 'consult-goto-line
        ;; orig. goto-line
        "M-g M-g" 'consult-goto-line
        ;; Alternative: consult-org-heading
        "M-g o" 'consult-outline
        "M-g m" 'consult-mark
        "M-g k" 'consult-global-mark
        "M-g i" 'consult-imenu
        "M-g I" 'consult-imenu-multi
        ;; M-s bindings (search-map)
        "M-s f" 'consult-find
        "M-s L" 'consult-locate
        "M-s g" 'consult-grep
        "M-s G" 'consult-git-grep
        "M-s r" 'consult-ripgrep
        "M-s l" 'consult-line
        "M-s m" 'consult-multi-occur
        "M-s k" 'consult-keep-lines
        "M-s u" 'consult-focus-lines
        ;; recentf
        [remap recentf-open-files] 'consult-recent-file
        ;; Isearch integration
        "M-s e" 'consult-isearch-history)
      (general-def isearch-mode-map
        ;; orig. isearch-edit-string
        "M-e" 'consult-isearch-history
        ;; orig. isearch-edit-string
        "M-s e" 'consult-isearch-history
        ;; needed by consult-line to detect isearch
        "M-s l" 'consult-line
        ;; needed by consult-line to detect isearch
        "M-s L" 'consult-line-multi)
      (my/evil-leader-def
        ;; Open the fancy consult-buffer navigator.
        "cb" 'consult-bookmark)
      :hook
      ;; Enable automatic preview at point in the *Completions* buffer.
      ;; This is relevant when you use the default completion UI,
      ;; and not necessary for Vertico, Selectrum, etc.
      (completion-list-mode . consult-preview-at-point-mode)
      ;; The :init configuration is always executed (Not lazy)
      :init
      ;; Optionally tweak the register preview window.
      ;; This adds thin lines, sorting and hides the mode line of the window.
      (advice-add #'register-preview :override #'consult-register-window)
      ;; Configure other variables and modes in the :config section,
      ;; after lazily loading the package.
      :custom
      ;; Optionally configure the register formatting. This improves the register
      ;; preview for `consult-register', `consult-register-load',
      ;; `consult-register-store' and the Emacs built-ins.
      (register-preview-delay 0.5)
      (register-preview-function #'consult-register-format)
      ;; Use Consult to select xref locations with preview
      (xref-show-xrefs-function #'consult-xref)
      (xref-show-definitions-function #'consult-xref)
{'fraction_non_alphanumeric': 0.10230134607034302, 'fraction_numerical': 0.0022579244463742944, 'mean_word_length': 2.6100313479623822, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3004752', 'n_tokens_mistral': 3682, 'n_tokens_neox': 3483, 'n_words': 1200}