add annotation to items in selection

[slk500]

Evaluate the code below to see the problem. You cannot select any item from the list - it says 'Match required'.

(completing-read "Summary: " 'org-columns--summary-types-completion-function nil t nil) ;; evaluate this line to see the problem

(defun org-columns--summary-types-completion-function (string pred flag)
    (pcase flag
      ('t (all-completions string
                           (delete-dups
                            (cons '("") ;Allow empty operator.
                                  (mapcar #'car (append
                                                 org-columns-summary-types
                                                 org-columns-summary-types-default))))
                           pred))
      ('metadata (list 'metadata
                       (cons 'annotation-function
                             (lambda (string)
                               (let* ((doc (condition-case nil (documentation (cdr (assoc string (append
                                                                                                  org-columns-summary-types
                                                                                                  org-columns-summary-types-default))))
                                             (error nil)))
                                      (doc (and doc (substring doc 0 (string-search "\n" doc)))))
                                 (if doc
                                     (format " -- %s" doc)
                                   ""))))))))

  (defun org-columns-new (&optional spec &rest attributes)
    "Insert a new column, to the left of the current column.
  Interactively fill attributes for new column.  When column format
  specification SPEC is provided, edit it instead.

  When optional argument attributes can be a list of columns
  specifications attributes to create the new column
  non-interactively.  See `org-columns-compile-format' for
  details."
    (interactive)
    (let ((new (or attributes
  		 (let ((prop
  			(completing-read
  			 "Property: "
  			 (mapcar #'list (org-buffer-property-keys t nil t))
  			 nil nil (nth 0 spec))))
  		   (list prop
                           ;; Discard useless whitespace-only titles.
  			 (org-string-nw-p
                            (read-string (format "Column title [%s]: " prop)
  				       (nth 1 spec)))
  			 ;; Use `read-string' instead of `read-number'
  			 ;; to allow empty width.
  			 (let ((w (read-string
  				   "Column width: "
  				   (and (nth 2 spec)
  					(number-to-string (nth 2 spec))))))
  			   (and (org-string-nw-p w) (string-to-number w)))
  			 (org-string-nw-p
  			  (completing-read
  			   "Summary: "
  			   'org-columns--summary-types-completion-function
  			   nil t (nth 3 spec)))
  			 (org-string-nw-p
  			  (read-string "Format: " (nth 4 spec))))))))
      (if spec
  	(progn (setcar spec (car new))
  	       (setcdr spec (cdr new)))
        (push new (nthcdr (org-current-text-column) org-columns-current-fmt-compiled)))
      (org-columns-store-format)
      (org-columns-redo)))

I wanted to add an annotation to items in selection for org-mode package 'org-columns' (column view).

When the user wants to add a new column (or edit an existing one), he executes the command `org-columns-new'. Then he can select from a few
'column attributes' (see in manual https://orgmode.org/org.html#Column-attributes-1). One of the attributes is "SUMMARY-TYPE". This attribute can be selected from the list of very enigmatic symbols such as "+", "$", "X" which do not convey any information to the user.

So I added annotation for every symbol that comes from the 'docstring' of the function assigned to that symbol.
For example:
"+ -- Compute the sum of VALUES."
"$ -- Compute the sum of VALUES, with two decimals."

Unfortunately, the solution I managed to obtain does not work with the Vertico package. You cannot select any item from the list - it says 'Match required'. Does anyone have an idea how to solve this? Should I modify my solution? Or perhaps something needs to be changed in Vertico?

[minad]

Hi! I close this, since it goes beyond the usual Vertico-specific questions. It is more about general completion behavior.

[yantar92]

I believe that it is vertico-specific. If you just take org-columns--summary-types-completion-function from the code snippet and evaluate the first line (after loading org-colview for variables), disabling/enabling vertico leads to different behavior. And there is nothing org-specific in the completion function per se.

[minad]

Actually the completion table is simply incorrect and doesn't follow the spec. Therefore it doesn't work. See completion-table-with-metadata as reference for a completion table with metadata, which handles all completion table actions properly.

[slk500]

Daniel Mendler ***@***.***> writes:

The completion table is simply incorrect and doesn't follow the spec. Therefore it doesn't work. See `completion-table-with-metadata` for reference.

It's a pretty new function: late December 2024. Thank you for the hint. I will look into that.

…

-- Slawomir Grochowski

[minad]

Yes, I am aware since I added this function to Emacs, such that it gets easier to write completion tables and avoid mistakes like in your function above. But the underlying mechanism has been there all along.