How to use ivy to navigate named locations of a buffer?

Question

Given a list of (point-number . title-text), how can ivy be used to show this in a list in ivy?

I have code which uses completing-read to do this (see link). This can use ivy since it extends completing-read however it doesn't seem to support all of ivy's features.

For example ivy-next-line-and-call and ivy-previous-line-and-call don't work.

How can ivy be used directly to navigate sections in a document?

Answer 1

I have code which uses completing-read to do this

Ivy's analogue to completing-read is the function ivy-read, whose operation is described in its docstring and the Ivy User Manual under (info "(ivy) API").

Given a list of (point-number . title-text), how can ivy be used to show this in a list in ivy?

Here's an example of how to achieve this:

(defun my-ivy-location (locations)
  "Goto one of LOCATIONS, using Ivy for completion.
LOCATIONS is a list of (POS . LABEL), where POS is a candidate
buffer position and LABEL is a string describing POS for the
purpose of completion."
  (ivy-read "Goto location: " (mapcar #'cdr locations)
            :require-match t
            :action (lambda (label)
                      (let ((pos (car (rassoc label locations))))
                        (when pos (goto-char pos))))
            :caller #'my-ivy-location))

Note that Ivy:

• prefers using the :action callback rather than the return value of ivy-read to operate on the selected candidate(s); and
• identifies the current completion command using the :caller property.

Depending on how you populate the LOCATIONS alist, it may be preferable to flip the order of its car and cdr, so that both built-in and Ivy completion functions can operate on it more naturally as a "completion table" (see (info "(elisp) Basic Completion")):

(defun my-ivy-location-r (locations)
  "Goto one of LOCATIONS, using Ivy for completion.
LOCATIONS is a list of (LABEL . POS), where POS is a candidate
buffer position and LABEL is a string describing POS for the
purpose of completion."
  (ivy-read "Goto location: " locations
            :require-match t
            :action (lambda (location)
                      (let ((pos (cdr-safe location)))
                        (when pos (goto-char pos))))
            :caller #'my-ivy-location-r))

How can ivy be used directly to navigate sections in a document?

Counsel is a library of handy utilities provided alongside and implemented using the Ivy API. Perhaps some of the following may also be of interest to you:

• counsel-imenu (jumping to buffer sections detected by imenu)
• counsel-mark-ring (jumping to buffer locations stored in the mark ring)
• counsel-register (jumping to buffer locations stored in registers)