search

minad / consult

:mag: consult.el - Consulting completing-read
GNU General Public License v3.0
1.26k stars 107 forks source link

Command wishlist #6

Closed minad closed 1 year ago

minad commented 3 years ago

todo/open for discussion

Seems feature complete? ;)

done

rejected

Contributions and new proposals are welcome. Note that Consult focuses on Emacs core functionality. Integrations with external packages should be provided by external packages, e.g., consult-lsp, consult-notmuch, ...

In many cases it is sufficient to use the built-in Emacs completing-read functionality. Therefore dedicated consult-* packages may not be necessary.

doolio commented 3 years ago

An equivalent to counsel-linux-app would be great.

minad commented 3 years ago

@doolio For now I am focused on the core commands, which are Emacs related and uncontroversial. But certainly some of the others like accessing linux apps could be added as well. Since I am not experienced with ivy, I would love some kind of usage statistics or experience reports regarding the most used commands. For example there is counsel-rythmbox which I doubt to be useful for many people. Then there are other commands which are already covered better by other packages I guess.

Luis-Henriquez-Perez commented 3 years ago

I would really like the selectrum-info command. Also, I'd like a command for selecting org capture templates akin to counsel-org-capture-string and something to select org tags like counsel-org-tag. I have implementations in my config for the last two if you want them.

tomfitzhenry commented 3 years ago

consult-comint-ring that read from (ring-elements comint-input-ring) would be useful. Users would bind that to C-r in shell-mode-map, to behave like fzf in bash.

tomfitzhenry commented 3 years ago

consult-imenu that browses imenu via completing-read.

tomfitzhenry commented 3 years ago

consult-completion-at-point that performs completion-at-point using completing-read. I use company-mode but sometimes there are so many results that I'd like to narrow them via completing-read.

Apologies for the multiple messages. I took inspiration from my current init file, and my todo list.

doolio commented 3 years ago

For now I am focused on the core commands, which are Emacs related and uncontroversial.

That makes sense.

minad commented 3 years ago

@Luis-Henriquez-Perez

I would really like the selectrum-info command. Also, I'd like a command for selecting org capture templates akin to counsel-org-capture-string and something to select org tags like counsel-org-tag. I have implementations in my config for the last two if you want them.

Yes, please open PRs! We can discuss over there then!

minad commented 3 years ago

@tomfitzhenry

consult-imenu that browses imenu via completing-read.

Is this needed? imenu already uses completing-read for me? Take a look at the function imenu-choose-buffer-index. What should be different?

consult-completion-at-point that performs completion-at-point using completing-read. I use company-mode but sometimes there are so many results that I'd like to narrow them via completing-read.

Same question here. I am not sure if this should be part of consult. I think selectrum alone can already do this by itself. What do you use for completion? Selectrum?

tomfitzhenry commented 3 years ago

Is this needed? imenu already uses completing-read for me? Take a look at the function imenu-choose-buffer-index. What should be different?

Ah yes, imenu uses completing-read (recursively) as it descends the imenu tree, setting the list of candidates to that node's children. i.e. multiple calls to completing-read are made. This interface feels awkward, since I typically know the leaf I want, but not the imenu tree structure.

I'm suggesting consult-imenu traverses the entire imenu tree and sets the list of candidates to all tree leafs. i.e. one call to completing-read is made.

This is what counsel-imenu does.

tomfitzhenry commented 3 years ago

Same question here. I am not sure if this should be part of consult. I think selectrum alone can already do this by itself. What do you use for completion? Selectrum?

I use icomplete. It sounds like Selectrum somehow manages to act as the Completion buffer. I'll look into it, thanks.

minad commented 3 years ago

@tomfitzhenry

Ah yes, imenu uses completing-read (recursively) as it descends the imenu tree, setting the list of candidates to that node's children. i.e. multiple calls to completing-read are made. This interface feels awkward, since I typically know the leaf I want, but not the imenu tree structure.

Thank you I got it. It is flattening the imenu. There is already flimenu for that but I look into if I can do anything about that here. flimenu also looks like a pretty simple package which does nearly nothing. The confusion thing is that the imenu on my Emacs already looks flat, I don't know what is causing this. But my overall feeling is that consult is not the right place to add something like this if it can be easily solved on another level.

tomfitzhenry commented 3 years ago

There is already flimenu for that

Perfect, thanks.

oantolin commented 3 years ago

consult-completion-at-point that performs completion-at-point using completing-read. I use company-mode but sometimes there are so many results that I'd like to narrow them via completing-read.

I wrote this function, @tomfitzhenry:

(defun completing-read-in-region (start end collection &optional predicate)
  "Prompt for completion of region in the minibuffer if non-unique.
Use as a value for `completion-in-region-function'."
  (if (and (minibufferp) (not (string= (minibuffer-prompt) "Eval: ")))
      (completion--in-region start end collection predicate)
    (let* ((initial (buffer-substring-no-properties start end))
           (limit (car (completion-boundaries initial collection predicate "")))
           (all (completion-all-completions initial collection predicate
                                            (length initial)))
           (completion (cond
                        ((atom all) nil)
                        ((and (consp all) (atom (cdr all)))
                         (concat (substring initial 0 limit) (car all)))
                        (t (completing-read
                            "Completion: " collection predicate t initial)))))
      (if (null completion)
          (progn (message "No completion") nil)
        (delete-region start end)
        (insert completion)
        t))))

To use it you just (setq completion-in-region-function #'completing-read-in-region). I'll contribute it soon to consult: even if selectrum already does this, icomplete users would benefit.

minad commented 3 years ago

@oantolin Cool, please do!

Luis-Henriquez-Perez commented 3 years ago

This might be out of the scope of consult but here goes. I have also wanted a richer set of org refile functions. Right now org-refile is very limited in the sense that the files have to be in the org-refile-targets. Would be nice to have a function that could refile to any org buffer. Since it seems consult will contain generally useful commands, this might be a good addition.

minad commented 3 years ago

@Luis-Henriquez-Perez please describe a bit more precisely what these functions are supposed to do. It is nice to have a bit more context. There is a plethora of functionality in Emacs and not everyone is aware of everything.

Luis-Henriquez-Perez commented 3 years ago

The function would move subtrees to different places. They would be very similar to the function that doom has to address this same problem.

oantolin commented 3 years ago

I sometimes wish ispell used completing-read when prompting you for a spelling correction.

okamsn commented 3 years ago

I sometimes wish ispell used completing-read when prompting you for a spelling correction.

Have you tried the package flyspell-correct? It uses completing-read (or other UIs) to select corrections, and also allows jumping to the underlined Flyspell errors.

oantolin commented 3 years ago

Thanks, @okamsn! I'll be sure to check it out, it looks like there are a bunch of UIs to choose from (I bet I'll land on avy). By the way, I think I fixed your file dialog problem with embark.

oantolin commented 3 years ago

What about a function to open a file in the default application for it according to the operating system? It would use open on Windows and Mac OS, xdg-open on Linux and cygstart undey Cygwin. Counsel has something like this in counsel-locate-action-extern and Embark has it in embark-open-externally.

minad commented 3 years ago

@oantolin I think counsel-locate-action-extern or embark-open-externally fits better into an action library, like Embark, not here.

oantolin commented 3 years ago

I am completely fine with that, @minad. But for future reference, can you explain why you think it fits better into an action library? Here's the code from embark (suggestively renamed :P). As you can see it has no embark-specific details in it at all. It is a useful function, that uses completion to select a file and then opens it:

(defun consult-open-externally (file)
  "Open FILE using system's default application."
  (interactive "fOpen: ")
  (if (and (eq system-type 'windows-nt)
           (fboundp 'w32-shell-execute))
      (w32-shell-execute "open" target)
    (call-process (pcase system-type
                    ('darwin "open")
                    ('cygwin "cygstart")
                    (_ "xdg-open"))
                  nil 0 nil
                  (expand-file-name file))))

Is it because it relies on external commands that you think it shouldn't be in consult? (That would be a reasonable reason, but is it your reason?)

minad commented 3 years ago

Sorry, I misunderstood - I thought it is only used as an action, I should have looked more closely. What you propose selects a file, opens it externally, that's perfectly fine and I think it belongs here. Please make a PR. Why is the counsel function called like this with the "action" in the name?

EDIT: I just saw (defalias 'counsel-find-file-extern #'counsel-locate-action-extern)

minad commented 3 years ago

I think I should also add consult-doctor but I am not sure yet what it should do.

manuel-uberti commented 3 years ago

A consult-flymake next to consult-flycheck would be great as well.

minad commented 3 years ago

@manuel-uberti @doolio I implemented flycheck support for now, because this is what I am using. consult-flycheck works great. In particular using the preview and jumping back and forth between errors. Flymake support would also be nice to have, but I am not sure if we should do this as a separate command or at least share some code with the flycheck command. I don't know by how much flycheck and flymake differ.

minad commented 3 years ago

@tomfitzhenry I added consult-imenu in https://github.com/minad/consult/commit/e37fbf233ac1824ce413d765020eaab8ea854238. It also supports preview in contrast to flimenu

tomfitzhenry commented 3 years ago

@tomfitzhenry I added consult-imenu in e37fbf2. It also supports preview in contrast to flimenu

Daily improvements to consult.el is my advent calendar. Thanks! 🎅

oantolin commented 3 years ago

Poor flimenu, I booted it from my config immediately. It would be nice that if consult-imenu is called from an Emacs Lisp buffer, the candidates were of category symbol and you got docstring annotations. I guess this is another argument for candidate transformers.

minad commented 3 years ago

@oantolin Good idea regarding the category! Right, it will only work if you have the transformers :(

hmelman commented 3 years ago

A consult-descbinds that works like counsel-descbinds to replace describe-bindings. The candidates are a string with the keybinding and function name and the selected function is looked up with describe-function (or could be executed or looked up in info)

minad commented 3 years ago

@hmelman While I have also wished for a better interface to the keybindings, I am not sure what the right way is. I think it would probably be sufficient to just have a better keybinding buffer (with function description, colors etc - does something like this exist? In the style of helpful) instead of the default describe-bindings. Then inside that buffer you can use consult-line/isearch as a search. I am not sure if adding this to consult is actually worth it if the default action is then to call describe-function. More often I want to lookup things and I already know what the functions will do or the oneliner docstring is sufficient. This means if there would be consult-binding, I would probably search for the thing I am looking for and then press C-g.

hmelman commented 3 years ago

I haven't played with it yet but I assume embark could be used to give different actions on the result whatever the default action is. I think I'd appreciate a fast way to get to binding searching/filtering without having to use one command to open the bindings buffer and another to filter it. Personally I don't use descbind much myself, but I know others that do.

minad commented 3 years ago

@hmelman I see there are benefits, but I think they are rather marginal in contrast to the benefits provided by other commands , which bring something new to the table, where we have preview etc. My point was just that if one has a better buffer view+consult-line you are almost there - sure you don't have actions and cannot run the commands, but I am unsure if consult-bind should be used as command launcher. I have to think about this. I am not very happy with the describe-bindings and describe-personal-keybindings buffer and I would like something with more information.

minad commented 3 years ago

@doolio Since you proposed consult-linux-app, I want to let you know, that I think it is out of scope of this project for the following reasons/missed criteria:

  1. The command is not Emacs-related, and too operation-system specific
  2. I don't see advantages of maintaining it as part of this package, since it would not make use of the facilities offered by consult--read. It could be as well maintained as part of some other launcher.el package working directly with the completing-read API.
  3. It seems to require relatively complex parsing of the desktop-files (bad benefit/cost ratio, given that it does not make use of the facilities offered here by consult)
  4. More personally, I am not particularly interested in using such a command - I launch programs via the shell in contrast to desktop files

Alternatively we could consider adding such a command to a consult-linux-app.el package if for some reason we would find that it makes sense to maintain this command as part of consult. But so far, I don't see this (point 2).

minad commented 3 years ago

@veronikazaglotova You proposed originally in https://github.com/raxod502/selectrum/issues/241 a command to search through docstrings. I tried to implement a consult-help command which allows to search through all symbol documentation strings. The formatting of the documentation strings is provided by marginalia, see #67. Unfortunately the command is too slow to be useful, selectrum/icomplete seems to be unable to handle that many strings.

@clemera Ping, just in case you need a command to see if there are still potential improvements to the selectrum performance... ;)

doolio commented 3 years ago

You make all valid points. Thank you for giving my suggestion due consideration. I use EXWM and so the command was a better alternative to the EXWM method.

minad commented 3 years ago

@doolio I think the command itself makes sense - I only question if it makes sense within the context of this project. My suggestion would be to extract the corresponding code from counsel.el and rework it such that it is based on completing-read, and then maybe create a new package. Generally I think it makes sense to have smaller more focused packages and Consult is already problematic in that sense due to its kitchen-sink nature. But by adding a few restrictions as I argued above, I guess this package can stay focused.

doolio commented 3 years ago

Agreed. I will attempt to make the function generic and report here or on the selectrum wiki if successful. Thanks again for your time and this package.

minad commented 3 years ago

You could very well make this a freestanding package and submit it to MELPA. But before doing that please check if something similar or equivalent already exists.

irigone commented 3 years ago

The formatting of the documentation strings is provided by marginalia

Yeah that's why I installed marginalia in the first place, thank a bunch for the great package

Unfortunately the command is too slow to be useful, selectrum/icomplete seems to be unable to handle that many strings.

That's sad. I can still use consult-apropos + M-x though, so it's not that bad.

minad commented 3 years ago

@veronikazaglotova You can try the command from here https://github.com/minad/consult/tree/consult-help and see if you would use something like this. For me it is too slow. These are simply too many too long strings for selectrum to handle. Maybe selectrum could be optimized further or gcc-emacs helps, I don't know.

clemera commented 3 years ago

I think its mainly sorting and filtering that make consult-help slow, I quickly tested it and if you deactivate sort and set selectrum-refine-candidates-function to the default it is much more responsive for me.

hmelman commented 3 years ago

FYI, apropos-documentation does this (search docstrings), though not with interactive narrowing (probably because of the performance issues).

minad commented 3 years ago

@clemera Thank you for the info - maybe we can make this work!

SebastienWae commented 3 years ago

@doolio I'm using EXWM too and moving from Ivy to the Selectrum/Consult/Embark completion stack, so I extracted counsel-linux-app to make it work with Emacs native completion system. It's not on MELPA but you can get it here https://github.com/SebastienWae/app-launcher

irigone commented 3 years ago

@veronikazaglotova You can try the command from here https://github.com/minad/consult/tree/consult-help and see if you would use something like this. For me it is too slow. These are simply too many too long strings for selectrum to handle. Maybe selectrum could be optimized further or gcc-emacs helps, I don't know.

Tbh I don't know how to use straight to install packages from git. I installed consult with it and it works, but copy&pasting the code from consult doesn't really work on other packages. I don't want to install packages by hand. Perhaps we can shorten the string before passing it to selectrum? For example, org-mode has a very long docstring (I read it with C-h f). If we shorten it to just Outline-based notes management and organizer, alias "Carsten’s outline-mode for keeping track of everything."it will get faster? After this there's a lot about keybindings and stuff which the user probably won't know about. The second paragraph has "Org mode develops organizational tasks" and can be useful too, though. Most (if not all) interactive functions I've seen have a short explanation in the first 1-2 paragraphs.

minad commented 3 years ago

@veronikazaglotova Well, we are already using only the first line of the docstring.