A bit off-topic: Where to ask questions about building on consult?

[magthe]

I'm trying to write my own consult-foo function and while getting something that works was easy, I'm struggling with making it nice. Given that building on to of consult is quite niche I'm not having much luck with finding answers to my questions. I'm also not very deep into the emacs community, so I'm unsure where I should turn.

Do you have any tips on where to turn to get answers and pointers on how to build on consult?

[minad]

Feel free to ask concrete questions here, in this issue. But generally there is no alternative than reading the source of this package and of some of the other consult-* packages. Maybe you find the solution to your problem there. If you struggle with certain specific details, I could improve the docstrings of the functions which are involved.

[magthe]

I was looking for a way to add preview to my config (I'm using consult--multi as I'll be adding multiple sources).

It's basically a source presenting certain lines in the current buffer so I was trying to work out how consult-line works, in particular its state function, but it's not easy to track what's happening and how it achieves the preview functionality. I think I sort of got it, and then realised that I can't really hook into it directly.

My current solution is here. Basically the steps are

1. Add the property section-pos to each candidate string.
2. The state function fetches the property and jumps to it on preview actions.
3. For the jumping I use consult--jump-1

There are mainly two things that are a little unclear

1. The sequence of actions the state function is called with is undocumented. I explored it a little and have figured out enough to get it to work, but I'm far from certain that I've understood it fully. In particular the meaning of exit and return.
2. Is using consult--jump-1 enough, or should I do more work in order to do preview well? I noticed that consult--line does a lot of work around its call to consult--jump/consult--jump-1.

[minad]

The sequence of actions the state function is called with is undocumented. I explored it a little and have figured out enough to get it to work, but I'm far from certain that I've understood it fully. In particular the meaning of exit and return.

See consult--with-preview.

Maybe this source is helpful https://github.com/minad/consult/wiki#point-register-source, since it also includes jumping?

[magthe]

I'm not sure I follow how that works, as far as I can tell

1. state is bound to the result of calling (consult--jump-state)
2. consult--jump-state returns the result of calling consult--state-with-return, which is a function taking two arguments; (lambda (action cand) ...)
3. then that state function is called with 3 arguments: (funcall state action (and cand (car (consult--get-location cand))))

Is the code in the wiki really up-to-date with what's in consult now?

[minad]

then that state function is called with 3 arguments: (funcall state action (and cand (car (consult--get-location cand))))

The function is called with two arguments.

Is the code in the wiki really up-to-date with what's in consult now?

Not everything, but this part should be.

[magthe]

Ah, yes... me and counting.

[magthe]

All right, so the function that sort of executes the preview is the lambda that's returned by (consult--jump-preview), right?

And if I'm reading it, and consult--jump-1 correctly, then the "candidate" should be something that can be passed to goto-char (or a list where (car cand) can be passed to goto-char), right?

[magthe]

This seems to work at least:

(defun consult-cabal--state ()
  "Create a state function for previewing sections."
  (let ((state (consult--jump-state)))
    (lambda (action cand)
      (when cand
        (let ((pos (get-text-property 0 'section-pos cand)))
          (funcall state action pos))))))

and it looks slightly better visually than my earlier solution.

[minad]

And if I'm reading it, and consult--jump-1 correctly, then the "candidate" should be something that can be passed to goto-char (or a list where (car cand) can be passed to goto-char), right?

I don't recall exactly, but it should be a position (integer or marker). For consult--jump-state is also the possibility to pass a list if one wants to highlight the matches.

[minad]

and it looks slightly better visually than my earlier solution.

This solution looks correct.

[magthe]

And if I'm reading it, and consult--jump-1 correctly, then the "candidate" should be something that can be passed to goto-char (or a list where (car cand) can be passed to goto-char), right?

I don't recall exactly, but it should be a position (integer or marker). For consult--jump-state is also the possibility to pass a list if one wants to highlight the matches.

What would such a list look like?

[minad]

Just saw your blog post https://magnus.therning.org/2023-03-30-more-on-tree-sitter-and-consult.html :)

What would such a list look like?

See consult--point-placement. It is a list of (beg . end) pairs, counting from the beginning of the line. This is used by consult-line and consult-grep to highlight the matches during preview. In total the argument should be (dest-pos (beg1 . end1) (beg2 . end2) ...).