jeffvalk / ivy-rich

More friendly interface for ivy.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

README

Table of Contents

More friendly interface for ivy

The package current comes with support for ivy-switch-buffer, counsel-M-x, counsel-describe-function and counsel-describe-variable, but it should be easy enough to define your own transformers. Screenshots are available here.

Installation

package-install RET ivy-rich RET

Basic Usages

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

It is recommended to set also

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

Customization

The transformer format for each ivy command is defined in plist ivy-rich-display-transformers-list, which has a default value

'(ivy-switch-buffer
  (:columns
   ((ivy-switch-buffer-transformer (:width 30))    ; add face by the original transformer
    (ivy-rich-switch-buffer-size (:width 7))  ; return buffer size
    (ivy-rich-switch-buffer-indicators (:width 4 :face error :align right))  ; return buffer indicator
    (ivy-rich-switch-buffer-major-mode (:width 12 :face warning))            ; return major mode info
    (ivy-rich-switch-buffer-project (:width 15 :face success))               ; return project name `projectile'
    (ivy-rich-switch-buffer-path (:width (lambda (x) (ivy-rich-switch-buffer-shorten-path x (ivy-rich-minibuffer-width 0.3))))))  ; return file path relative to project root or `default-directory' if project is nil
   :predicate
   (lambda (cand) (get-buffer cand)))
  counsel-find-file
  (:columns
   ((ivy-read-file-transformer)
    (ivy-rich-counsel-find-file-truename (:face font-lock-doc-face))))
  counsel-M-x
  (:columns
   ((counsel-M-x-transformer (:width 40))
    (ivy-rich-counsel-function-docstring (:face font-lock-doc-face)))) ; return docstring of the command
  counsel-describe-function
  (:columns
   ((counsel-describe-function-transformer (:width 40))
    (ivy-rich-counsel-function-docstring (:face font-lock-doc-face))))  ; return docstring of the function
  counsel-describe-variable
  (:columns
   ((counsel-describe-variable-transformer (:width 40))
    (ivy-rich-counsel-variable-docstring (:face font-lock-doc-face))))  ; return docstring of the variable
  counsel-recentf
  (:columns
   ((ivy-rich-candidate (:width 0.8))
    (ivy-rich-file-last-modified-time (:face font-lock-comment-face))))  ; return last modified time of the file
  package-install
  (:columns
   ((ivy-rich-candidate (:width 30))
    (ivy-rich-package-version (:width 16 :face font-lock-comment-face))  ; return package version
    (ivy-rich-package-archive-summary (:width 7 :face font-lock-builtin-face))  ; return archive summary
    (ivy-rich-package-install-summary (:face font-lock-doc-face)))))  ; return package description

A transformer is just a string processing function with some format properties. 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.

Convenience functions exist for customizing column properties without rewriting the entire transformer definition. 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:

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

This example customizes properties of two columns of the ivy-switch-buffer transformer and shows some other configuration options via use-package:

(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)))))

Example

counsel-M-x

For example, the transformer for counsel-M-x

counsel-M-x
(:columns
 ((counsel-M-x-transformer (:width 40))
  (ivy-rich-counsel-function-docstring (:face font-lock-doc-face))))

it defines two columns. The first one is the original built-in transformer with max width of 40 chars and the second one transforms the string candidate into a docstring with face font-lock-doc-face.

Add icons for ivy-switch-buffer

The package all-the-icons.el provides functionality to use icon fonts easily in emacs. For example, you can define a transformer

(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))))

and add it to the ivy-rich-display-transformers-list

(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)))))

You will get

screenshots/all-the-icons.png

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. I am considering to add a :package keyword in the transformer definition to deal with this.
  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.

Screenshots and details

ivy-switch-buffer

screenshots/buffer.png

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

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

Note that this may not affect remote files. 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.

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.

counsel-M-x

screenshots/counsel-m-x.png

counsel-describe-variable

screenshots/counsel-describe-variable.png

counsel-recentf

screenshots/counsel-recentf.png

counsel-bookmark

screenshots/counsel-bookmark.png

package-install

screenshots/package-install.png

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 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.

Related Packages

About

More friendly interface for ivy.


Languages

Language:Emacs Lisp 100.0%