Need help with ivy-rich?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Yevgnen
320 Stars 37 Forks 116 Commits 26 Opened issues

Description

More friendly interface for ivy.

Services available

!
?

Need anything else?

Contributors list

+title: README

+date: <2020-03-22 Sun>

  • More friendly interface for ivy

This package comes with rich transformers for commands from ~ivy~ and ~counsel~. It should be easy enough to define your own transformers too.

Screenshots are available [[file:screenshots.org][here]].

** Installation

~M-x package-install RET ivy-rich RET~

** Basic Usages

+begin_src emacs-lisp

(require 'ivy-rich) (ivy-rich-mode 1)

+end_src

It is recommended to set also

+begin_src emacs-lisp

(setcdr (assq t ivy-format-functions-alist) #'ivy-format-function-line)

+end_src

** Customization :PROPERTIES: :CUSTOM_ID: h:6A171A3A-50DF-42F6-B19B-321B160F198E :END:

A transformer is just a string processing function with some format properties. The transformer format for each ~ivy~ command is defined in the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Property-Lists.html#Property-Lists][plist]] ~ivy-rich-display-transformers-list~. Each plist key is a ~ivy~ command and plist value is its transformer format definitions or a pre-defined transformer. Refer to the documentation of ~ivy-rich-display-transformers-list~ for details.

You can also define your own transformers, see [[id:20201229-how-i-can-add-icons-for-ivy-switch-buffer][this]] for an example.

** Convenience functions

Convenience functions exist for customizing column properties without rewriting the entire transformer definition

  • ~ivy-rich-modify-column~ :: Update properties of existed transformer column.
  • ~ivy-rich-modify-columns~ :: Like ~ivy-rich-modify-column~, but for multiple columns.
  • ~ivy-rich-set-columns~ :: Set/Replace transformer columns.

Below are two examples that use the default transformers, but with user-defined customizations.

This example customizes the ~:width~ and ~:face~ properties of the major mode column in the ~ivy-switch-buffer~ transformer:

+begin_src elisp

(ivy-rich-modify-column 'ivy-switch-buffer 'ivy-rich-switch-buffer-major-mode '(:width 20 :face error))

+end_src

This example customizes properties of two columns of the ~ivy-switch-buffer~ transformer:

+begin_src elisp

(ivy-rich-modify-columns 'ivy-switch-buffer '((ivy-rich-switch-buffer-size (:align right)) (ivy-rich-switch-buffer-major-mode (:width 20 :face error))))

+end_src

Refer to the docstring for more details.

** Additional settings for ~ivy-switch-buffer~

To abbreviate paths using ~abbreviate-file-name~ (e.g. replace "/home/username" with "~")

+begin_src emacs-lisp

(setq ivy-rich-path-style 'abbrev)

+end_src

To always show absolute path, set it to ~full~ or ~absolute~. Any other value will show the file path relative to the project root or =default-Directory=.

Note that this may not affect remote files. There are two variables ~ivy-rich-parse-remote-buffer~ and ~ivy-rich-parse-remote-file-path~ controls how remote buffers are processed, please refer to the docstring of them for more details if you have trouble using this function under ~tramp~.

*** Project Performance

When having many open buffers, calling and navigating ~ivy-switch-buffers~ might become slow when you have project-related columns. If that's the case, you can enable ~ivy-rich-project-root-cache-mode~, to cache each buffers project. The project for a buffer is cached until the buffer is killed, ~ivy-rich-project-root-cache-mode~ is disabled or ~ivy-rich-clear-project-root-cache~ is called.

** Notes

  1. If you modify ~ivy-rich-display-transformers-list~, you may need to disable and re-enable ~ivy-rich-mode~ again to make the changes take effect.

  2. If you define transformers for commands comes from neither ~ivy~ nor ~counsel~, e.g. ~counsel-projectile-*~, it currently may not take effect since if you enable ~ivy-rich-mode~ before loading ~counsel-projectile~, the transformer setting is overwritten by loading the package. Try to load all these packages before loading ~ivy-rich~.

  3. Disabling the minor mode ~ivy-rich-mode~ will restore the transformers to what they were before, but not necessarily to the 'built-in default' one. For example, the default transformer for ~ivy-switch-buffer~ is ~ivy-switch-buffer-transformer~ from the ~ivy~ package. But if you set the transformer to ~some-function~ before enabling ~ivy-rich-mode~, disabling the minor mode will restore it to ~some-function~ other than ~ivy-switch-buffer-transformer~.

  • Important Changes

Since the version 0.1.0 of ~ivy-rich~, the transformer format can be customized. Variables from older version like ~ivy-rich-switch-buffer-mode-max-length~ or ~ivy-rich-switch-buffer-project-max-length~ has been deprecated since they are now packed into ~ivy-rich-display-transformers-list~ as stated in the [[#h:6A171A3A-50DF-42F6-B19B-321B160F198E][customization section]].

Supports for virtual buffers and shorten file paths in ~ivy-switch-buffer~ are temporarily Removed.

  • FAQ

** Can I search buffers by ~major-mode~, ~project~ in ~ivy-switch-buffer~?

No, as far as I know, you can not right now. ~ivy-rich~ provides just transformers to display the original ~ivy~ candidates in a different way. It does not modify the original candidates. At least for now I have no idea how to add feature to search in the transformer columns. It probably requires some change in ~ivy~.

So you can not search the description of ~counsel-describe-function~ neither.

** How I can add icons for ~ivy-switch-buffer~? :PROPERTIES: :ID: 20201229-how-i-can-add-icons-for-ivy-switch-buffer :END:

The package [[https://github.com/domtronn/all-the-icons.el][all-the-icons.el]] provides functionality to use icon fonts easily in emacs. For example, you can define a transformer

+begin_src elisp

(defun ivy-rich-switch-buffer-icon (candidate) (with-current-buffer (get-buffer candidate) (let ((icon (all-the-icons-icon-for-mode major-mode))) (if (symbolp icon) (all-the-icons-icon-for-mode 'fundamental-mode) icon))))

+end_src

and add it to the plist value of ~ivy-switch-buffer~ in ~ivy-rich-display-transformers-list~

+begin_src elisp

(setq ivy-rich-display-transformers-list '(ivy-switch-buffer (:columns ((ivy-rich-switch-buffer-icon (:width 2)) (ivy-rich-candidate (:width 30)) (ivy-rich-switch-buffer-size (:width 7)) (ivy-rich-switch-buffer-indicators (:width 4 :face error :align right)) (ivy-rich-switch-buffer-major-mode (:width 12 :face warning)) (ivy-rich-switch-buffer-project (:width 15 :face success)) (ivy-rich-switch-buffer-path (:width (lambda (x) (ivy-rich-switch-buffer-shorten-path x (ivy-rich-minibuffer-width 0.3)))))) :predicate (lambda (cand) (get-buffer cand)))))

+end_src

See also [[https://github.com/seagle0128/all-the-icons-ivy-rich][all-the-icons-ivy-rich]].

  • Related Packages

  • [[https://github.com/casouri/ivy-filthy-rich][ivy-filthy-rich.el]] by @casouri

  • [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]] by @asok

  • [[https://github.com/seagle0128/all-the-icons-ivy-rich][all-the-icons-ivy-rich]] by @seagle0128

Local Variables:

fill-column: 72

End:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.