Embark support

[akirak]

Hello,

I want to get an olp entered from the user in org-ql-completing-read. Specifically, I am thinking of the following use cases:

• Let the user choose a heading to clock into. If the heading does not exist, fire org-capture with the input as the title.
• Let the user choose a heading to refile an entry into. If the heading does not exist, create a new heading.

This can be solved by adding a history variable for completing-read in the command. If the function returns nil, the user can get the latest item from the history and split the string with / to get an olp. This is hacky, but it achieves the desired effect with minimal changes to the implementation.

An alternative way is to change

(gethash selected table)

to

(or (gethash selected table)
            (when return-olp
              (split-string selected "/")))

and add :return-olp argument to the function. The extra argument is needed to avoid confusion in normal use cases, but it is more complicated (in API and implementation) than adding the history variable.

What is the best way to solve the problem?

[alphapapa]

Hi Akira,

Yes, clocking and refiling are two obvious uses for org-ql-completing-read. (Ideally Org would have a framework that would allow the function used for selecting entries for various purposes to be set by the user, and we could have a mode that would use org-ql-completing-read for that.)

Anyway, you can see the org-ql-refile command I already implemented here:

org-ql/org-ql-find.el

Line 88 in e41cdb4

(defun org-ql-refile (marker)

(That file may not be the permanent home for that command.)

As for getting an outline path, the function returns a marker, so it should be as simple as this:

(org-with-point-at (org-ql-completing-read ...)
  (org-get-outline-path))

So there should be no need to change the API.

[akirak]

Thank you for your quick response.

What I want is a unified completion API that can handle both existing entries (returning a marker) and non-existent ones (returning an olp).

I have the following function that can create a heading from an olp (even if its parent does not exist), which can be integrated with org-capture and org-refile:

(defun akirak-org-goto-or-create-olp (olp)
  (let ((level 1))
    (dolist (heading olp)
      (unless (catch 'found
                (while (re-search-forward (format org-complex-heading-regexp-format
                                                  (regexp-quote heading))
                                          nil t)
                  (when (equal level (- (match-end 1) (match-beginning 1)))
                    (throw 'found t))))
        (org-end-of-subtree)
        (insert "\n" (make-string level ?*) " " heading))
      (org-narrow-to-subtree)
      (setq level (org-get-valid-level (1+ level))))))

It would be nice if I could build the olp using org-ql-completing-read.

[alphapapa]

What I want is a unified completion API that can handle both existing entries (returning a marker) and non-existent ones (returning an olp).

That is a nice idea, but returning a non-existent heading would seem to violate the concern of org-ql-completing-read, whose purpose is to return matches for a search query (not to return non-matches). If the user selects a heading with org-ql-completing-read, how is the function to know whether the user wants that heading, or a new, non-existent one to be made under it? As well, the input given to org-ql-completing-read is not an outline path but tokens passed (by default) to the rifle predicate; it wouldn't make sense for a new outline path to be generated from that input.

I think you will need to do something like having an alternative key binding, like M-RET, that would use the heading selected with org-ql-completing-read and prompt the user to insert a new child heading under it.

[akirak]

That is a nice idea, but returning a non-existent heading would seem to violate the concern of org-ql-completing-read

I understand your point.

you will need to do something like having an alternative key binding

It doesn't look easy to define such a keybinding. It would be nice if org-ql-completing-read used a dedicated keymap!

[alphapapa]

Ok, feel free to propose a patch that adds one. :)

[akirak]

It would be nice if org-ql-completing-read used a dedicated keymap!

I tried to implement this idea, but it turns out that this is not easy, at least for vertico users. Vertico uses its own keymap:

(defun vertico--setup ()
  "Setup completion UI."
  (setq vertico--input t
        vertico--candidates-ov (make-overlay (point-max) (point-max) nil t t)
        vertico--count-ov (make-overlay (point-min) (point-min) nil t t))
  ;; Set priority for compatibility with `minibuffer-depth-indicate-mode'
  (overlay-put vertico--count-ov 'priority 1)
  (setq-local completion-auto-help nil
              completion-show-inline-help nil)
  (use-local-map vertico-map)
  (add-hook 'post-command-hook #'vertico--exhibit nil 'local))

Even if I could somehow create a heading during the minibuffer session, the completion table would never include a marker to the new entry, which would mean org-ql-completing-read returns nil for non-existent entries. The problem may not be easy to solve, so I will change the title of this ticket and leave it open.

[alphapapa]

Ok, maybe we can figure something out in the future. Thanks.

[minad]

Not sure if I understand this issue correctly, but if you want a local keymap for a command you can use minibuffer-with-setup-hook and create a new local map, composed with the existing minibuffer map. See for example jinx--correct-setup from my Jinx package:

• https://github.com/minad/jinx/blob/9982192145500bb9fa6f2d7d2ed4db6cd7f905d9/jinx.el#L706
• https://github.com/minad/jinx/blob/9982192145500bb9fa6f2d7d2ed4db6cd7f905d9/jinx.el#L630

This approach should be compatible with all completion UIs (at least as long as you don't override some important bindings which are already in use).

[alphapapa]

@minad Thanks.

Since this issue was originally filed, embark has become quite a powerful tool, and it now has support for various Org-related actions: oantolin/embark#562 So I think the best way to support this would be for org-ql to support embark, so we would gain all of its power.