Improved Helm module (#4561)
* Improved Helm module + Added README + Added posframe + Added icons * Requested changes * Remove helm-posframe and merge upstream * Removed redundant line
This commit is contained in:
Ellis Kenyő
GitHub
parent
71281bb52e
commit
473f4b1e12
3 changed files with 208 additions and 7 deletions
191
modules/completion/helm/README.org
Normal file
191
modules/completion/helm/README.org
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
#+TITLE: completion/helm
|
||||
#+DATE: January 22, 2021
|
||||
#+SINCE: v2.0
|
||||
#+STARTUP: inlineimages
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#install][Install]]
|
||||
- [[#macos][MacOS]]
|
||||
- [[#arch-linux][Arch Linux]]
|
||||
- [[#opensuse][openSUSE]]
|
||||
- [[#features][Features]]
|
||||
- [[#jump-to-navigation][Jump-to navigation]]
|
||||
- [[#project-search--replace][Project search & replace]]
|
||||
- [[#search][Search]]
|
||||
- [[#replace][Replace]]
|
||||
- [[#in-buffer-searching][In-buffer searching]]
|
||||
- [[#helm-integration-for-various-completing-commands][Helm integration for various completing commands]]
|
||||
- [[#general][General]]
|
||||
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
|
||||
- [[#search-1][Search]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#icons][Icons]]
|
||||
- [[#posframe][Posframe]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
|
||||
* Description
|
||||
This module provides Helm integration for a variety of Emacs commands, as well as
|
||||
a unified interface for project search and replace, powered by ripgrep.
|
||||
|
||||
#+begin_quote
|
||||
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
|
||||
lighter, simpler and faster in many cases.
|
||||
#+end_quote
|
||||
|
||||
Ivy is considered a first-class citizen in Doom, however it is still possible to use Helm if you so desire.
|
||||
|
||||
** Module Flags
|
||||
+ =+fuzzy= Enables fuzzy completion for Helm searches.
|
||||
+ =+childframe= Causes Helm to display in a floating child frame, above Emacs.
|
||||
+ =+icons= Enables icons (supports both =all-the-icons= and =treemacs= icons)
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/emacs-helm/helm][helm]]
|
||||
+ [[https://github.com/microamp/helm-rg][helm-rg]]
|
||||
+ [[https://github.com/emacs-jp/helm-c-yasnippet][helm-c-yasnippet]]
|
||||
+ [[https://github.com/tuhdo/helm-company][helm-company]]
|
||||
+ [[https://github.com/emacs-helm/helm-describe-modes][helm-describe-modes]]
|
||||
+ [[https://github.com/bbatsov/helm-projectile][helm-projectile]]
|
||||
+ [[https://github.com/abo-abo/swiper-helm][helm-swiper]]
|
||||
+ [[https://github.com/emacs-helm/helm-descbinds][helm-descbinds]]
|
||||
+ [[https://github.com/PythonNut/helm-flx][helm-flx]]* (=+fuzzy=)
|
||||
+ [[https://github.com/tumashu/helm-posframe][helm-posframe]]* (=+childframe=)
|
||||
+ [[https://github.com/emacs-helm/helm-org][helm-org]]* (=:lang org=)
|
||||
+ [[https://github.com/yyoncho/helm-icons][helm-icons]]* (=+icons=)
|
||||
|
||||
* Prerequisites
|
||||
This module depends on:
|
||||
|
||||
+ [[https://github.com/BurntSushi/ripgrep][ripgrep]] (rg)
|
||||
|
||||
** Install
|
||||
*** MacOS
|
||||
#+BEGIN_SRC sh
|
||||
brew install ripgrep
|
||||
#+END_SRC
|
||||
|
||||
*** Arch Linux
|
||||
#+BEGIN_SRC sh :dir /sudo::
|
||||
sudo pacman --needed --noconfirm -S ripgrep
|
||||
#+END_SRC
|
||||
|
||||
*** openSUSE
|
||||
#+BEGIN_SRC sh :dir /sudo::
|
||||
sudo zypper install ripgrep
|
||||
#+END_SRC
|
||||
|
||||
* Features
|
||||
Much like Ivy, Helm is a /large/ framework and as such
|
||||
covering everything is not in scope, however a number
|
||||
of Doom-specific features are shown below:
|
||||
|
||||
** Jump-to navigation
|
||||
Similar to Ivy, this module provides an interface to
|
||||
navigate within a project using =projectile=:
|
||||
|
||||
| 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 also provides interacetive text search and replace using ripgrep
|
||||
|
||||
*** Search
|
||||
|
||||
| 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 |
|
||||
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.
|
||||
|
||||
*** Replace
|
||||
|
||||
These keybindings are available while a search is active:
|
||||
|
||||
| Keybind | Description |
|
||||
|-----------+-----------------------------------------------|
|
||||
| =C-c C-o= | 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-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).
|
||||
|
||||
** In-buffer searching
|
||||
The =swiper= package provides an interactive buffer search powered by helm. It
|
||||
can be invoked with:
|
||||
|
||||
+ =SPC s s= (~swiper-isearch~)
|
||||
+ =SPC s S= (~swiper-isearch-thing-at-point~)
|
||||
+ =SPC s b= (~swiper~)
|
||||
+ ~:sw[iper] [QUERY]~
|
||||
|
||||
A wgrep buffer can be opened from swiper with =C-c C-e=.
|
||||
** Helm integration for various completing commands
|
||||
Helm also has a number of overrides for built-in functionality:
|
||||
|
||||
*** General
|
||||
| Keybind | Description |
|
||||
|------------+---------------------------|
|
||||
| =M-x=, =SPC := | Smarter, smex-powered M-x |
|
||||
| =SPC '= | Resume last ivy 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 |
|
||||
|
||||
*** 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) |
|
||||
|
||||
* Configuration
|
||||
** Icons
|
||||
Icons are now included, and support 2 providers ([[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/Alexander-Miller/treemacs][treemacs]]).
|
||||
By default, to maintain consistency we use =all-the-icons=; however if you wish
|
||||
to modify this you can do so using the below snippet:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(after! helm
|
||||
(setq helm-icons-provider 'treemacs))
|
||||
#+end_src
|
||||
|
||||
** Posframe
|
||||
|
||||
* Troubleshooting
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
;;; completion/helm/config.el -*- lexical-binding: t; -*-
|
||||
|
||||
;; Posframe (requires +childframe)
|
||||
(defvar +helm-posframe-handler #'+helm-poshandler-frame-center-near-bottom-fn
|
||||
"The function that determines the location of the childframe. It should return
|
||||
a cons cell representing the X and Y coordinates. See
|
||||
(defvar +helm-posframe-handler #'posframe-poshandler-frame-center
|
||||
"The function that determines the location of the childframe.
|
||||
It should return a cons cell representing the X and Y coordinates. See
|
||||
`posframe-poshandler-frame-center' as a reference.")
|
||||
|
||||
(defvar +helm-posframe-text-scale 1
|
||||
"The text-scale to use in the helm childframe. Set to nil for no scaling. Can
|
||||
be negative.")
|
||||
"The text-scale to use in the helm childframe. Set to nil for no scaling.
|
||||
Can be negative.")
|
||||
|
||||
(defvar +helm-posframe-parameters
|
||||
'((internal-border-width . 8)
|
||||
|
|
@ -16,8 +16,7 @@ be negative.")
|
|||
(height . 0.35)
|
||||
(min-width . 80)
|
||||
(min-height . 16))
|
||||
"TODO")
|
||||
|
||||
"Default parameters for the helm childframe.")
|
||||
|
||||
;;
|
||||
;;; Packages
|
||||
|
|
@ -189,3 +188,12 @@ be negative.")
|
|||
|
||||
(use-package! helm-descbinds
|
||||
:hook (helm-mode . helm-descbinds-mode))
|
||||
|
||||
|
||||
(use-package! helm-icons
|
||||
:after helm
|
||||
:when (featurep! +icons)
|
||||
:init
|
||||
(setq helm-icons-provider 'all-the-icons)
|
||||
:config
|
||||
(helm-icons-enable))
|
||||
|
|
|
|||
|
|
@ -16,4 +16,6 @@
|
|||
(package! posframe :pin "efd7ea490defc53a5b78e7469a3a35d225b766cc"))
|
||||
(when (featurep! :lang org)
|
||||
(package! helm-org :pin "b7a18dfc17e8b933956d61d68c435eee03a96c24"))
|
||||
(when (featurep! +icons)
|
||||
(package! helm-icons :pin "dbc5c41da07d5d182f0cd1ea46fab47085fe070d"))
|
||||
(package! helm-descbinds :pin "b72515982396b6e336ad7beb6767e95a80fca192")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue