https://github.com/oantolin/async-completing-read

An async-capable completing read function
https://github.com/oantolin/async-completing-read

Last synced: 12 days ago
JSON representation

An async-capable completing read function

• Host: GitHub
• URL: https://github.com/oantolin/async-completing-read
• Owner: oantolin
• License: gpl-3.0
• Created: 2020-05-28T08:04:58.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2022-08-25T14:47:34.000Z (over 2 years ago)
• Last Synced: 2024-08-07T18:31:14.494Z (5 months ago)
• Language: Emacs Lisp
• Size: 22.5 KB
• Stars: 21
• Watchers: 2
• Forks: 4
• Open Issues: 2
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

        
* Overview

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:

#+begin_src emacs-lisp

(setq completing-read-function #'async-completing-read)

#+end_src

you can prompt from any file found in the part of the directory tree

rooted at the current directory with the expression:

#+begin_src emacs-lisp

(completing-read "File: " (acr-lines-from-process "find" "."))

#+end_src

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.