This package provides an =async-completing-read= function that recognizes completion table with an =async= property in their metadata and treats the specially. The value associated to the =async= property should be a list of an executable program and arguments for it. This program is started asynchronously and its output collected in a buffer. The completion table can access the output buffer by calling its predicate on the symbol =output-buffer=.
A useful example of a class of async completion tables is provided: =(acr-lines-from-process prog args)= returns a completion table for which the completion candidates are lines the standard output of prog run with arguments args.
As an example, once you have evaluated:
(setq completing-read-function #'async-completing-read)
you can prompt from any file found in the part of the directory tree rooted at the current directory with the expression:
(completing-read "File: " (acr-lines-from-process "find" "."))
Note that =async-completing-read= can handle normal non-async completion tables too, so you can just "leave it on", that is use it as the value of =completing-read-function= all the time.
Configuration
=acr-completing-read-function= :: =async-completing-read= really just handles logistics of starting the process and passing the output buffer to the completion table, it delegates all actual prompting the user and reading input to =acr-completing-read-function=, which defaults to whatever =completing-read-function= was at the time this library was loaded.
=acr-refresh-completion-ui= :: set this to a function that refshes the display of your completion UI. The default value, =acr-refresh-icomplete=, obviously is meant for Icomplete. Note this variable is just about /showing/ the completions: the completions do get updated asynchronously anyway, and as soon as you typed anything you'd pick the newly available ones up.
=acr-refresh-completion-delay= :: how often to call =acr-refresh-completion-ui=, defaults to 0.3 seconds.