#+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
• ivy-rich-modify-columns

Below are two examples with use-package 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 (use-package ivy-rich :config (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 and shows some other configuration options via use-package:

#+begin_src elisp (use-package ivy-rich :hook (ivy-mode . ivy-rich-mode) :custom (ivy-rich-path-style 'abbrev) :config (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

** 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: