bug#66948: [PATCH] Add Completion Preview mode

[Eshel Yaron via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 13232 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks.  If this is for core, I think there's still work to be done
> here, see the comments below.

Thanks for reviewing.  I'm attaching an updated patch (v4) following
your comments.

>> +  Completion Preview mode is a minor mode that shows you symbol
>> +completion suggestions as type.  When you enable Completion Preview
>> +mode in a buffer (with @kbd{M-x completion-preview-mode}), Emacs
>> +examines the text around point after certain commands you invoke and
>> +automatically suggests a possible completion.  Emacs displays this
>> +suggestion with an inline preview right after point, so you see in
>> +advance exactly how the text will look if you accept the completion
>> +suggestion---that's why it's called a preview.
>
> I don't think this minor mode warrants such a long and detailed
> description in the user manual.  The section where you added that just
> mentions the various similar features, it doesn't describe them in
> such great detail, so I think we should do the same for this new mode.
> IOW, just mention it and what it does in a sentence or two, and move
> the rest of the description to the Commentary section of
> completion-preview.el and/or to the relevant doc strings.

Alright, done.  I left the first paragraph in the manual, and moved the
rest to the commentary section of completion-preview.el after some
adjustments.

>> +*** New minor mode 'completion-preview-mode'.
>> +This minor mode shows you symbol completion suggestions as you type,
>> +using an inline preview.  New user options in the 'completion-preview'
>> +customization group control exactly when Emacs displays this preview.
>
> This fails to mention that (evidently) this mode is intended to be
> used only in descendants of prog-mode, i.e. that useful completions
> will be available only for editing program source.  But see below.

It is not the case that Completion Preview is intended only for
`prog-mode` descendants, it works just as well in e.g. `text-mode`.

>> +;; This library provides the Completion Preview mode.  This minor mode
>> +;; displays the top completion candidate for the symbol at point in an
>> +;; overlay after point.  If you want to enable Completion Preview mode
>> +;; in all programming modes, add the following to your Emacs init:
>> +;;
>> +;;     (add-hook 'prog-mode-hook #'completion-preview-mode)
>
> I'm not sure why this is advertised for prog-mode.

This is just an example.  I've now removed it to avoid confusion.

> Are completions produced for descendants of Text mode, for example?

Sure.  I'm running with `completion-preview-mode` in `text-mode-hook` myself.

>> +(defcustom completion-preview-exact-match-only nil
>> +  "Whether to show completion preview only when there is an exact match.
>> +
>> +If this option is non-nil, Completion Preview mode only shows the
>> +preview overlay when there is exactly one completion candidate
>            ^^^^^^^
> This is an implementation detail, better left out of the doc string.
>

Done.

>> +that matches the symbol at point, otherwise it shows the top
>> +candidate also when there are multiple matching candidates."
>
> What do you mean by "top candidate"? I can try guessing, but I think
> it is better to reword this.

Right, reworded.

>> +  :type 'boolean)
>
> Every new defcustom should have a :version tag (this comment is for
> all the defcustoms in this file).

Done.

>> +(defcustom completion-preview-commands '(self-insert-command
>> +                                         delete-backward-char
>> +                                         backward-delete-char-untabify)
>
> I think you should add insert-char to this list.

Done.

> Also, did you test this minor mode when Overwrite mode is in effect?

Yes, no surprises there AFAICT, works well.

>> +(defcustom completion-preview-minimum-symbol-length 3
>> +  "Minimum length of the symbol at point for showing completion preview."
>> +  :type 'natnum)
>
> Why do we need this defcustom?  IOW, why not show the completion after
> a single character?

Basically, a single character often has many completion candidates, and
most of them are not what you want.  After three characters, the preview
is much more likely to show you a useful candidate.  So you can think of
this option as an adjustable threshold for how much information we
require the completion backend to have before we consider its
suggestions any good.  I'm open to changing the default value, but I
think that three characters is a very sane default.

>> +(defcustom completion-preview-hook
>> +  '(completion-preview-require-certain-commands
>> +    completion-preview-require-minimum-symbol-length)
>> +  "Hook for functions that determine whether to show preview completion.
>> +
>> +Completion Preview mode calls each of these functions in order
>> +after each command, and only displays the completion preview when
>> +all of the functions return non-nil."
>
> This feature sounds like over-engineering to me.

I think this makes the mode nicely flexible, as it lets users and other
code add different conditions for when to show the preview, e.g. only in
or out of comments.  And the added complexity is negligible, really.  So
I guess we could do without this option, but I'd prefer to keep it
unless you feel strongly about that.

>> +(defface completion-preview-exact
>> +  '((t :underline t :inherit completion-preview))
>
> The underline face is not universally supported, so this defface
> should have fallbacks.

The `underline` face in faces.el has `:underline t` in the fallback
clause too, so I figured that should be alright, no?

>> +(defvar completion-preview--internal-commands
>> +  '(completion-preview-next-candidate completion-preview-prev-candidate)
>> +  "List of commands that manipulate the completion preview.")
>> +
>> +(defun completion-preview--internal-command-p ()
>> +  "Return non-nil if `this-command' manipulates the completion preview."
>> +  (memq this-command completion-preview--internal-commands))
>
> Should this be a defsubst?

Probably, it is now :)

>> +(defun completion-preview-require-certain-commands ()
>> +  "Check if `this-command' is one of `completion-preview-commands'."
>> +  (or (completion-preview--internal-command-p)
>> +      (memq this-command completion-preview-commands)))
>
> Likewise here.

Done.

>> +(defun completion-preview-require-minimum-symbol-length ()
>> +  "Check if the length of symbol at point is at least above a certain threshold.
>> +`completion-preview-minimum-symbol-length' determines that threshold."
>> +  (pcase (bounds-of-thing-at-point 'symbol)
>> +    (`(,beg . ,end)
>> +     (<= completion-preview-minimum-symbol-length (- end beg)))))
>
> Is usage of pcase really justified here, and if so, why?

Since we're relying on `completion-at-point`, that already uses `pcase`,
I'm not sure what's the cost of using `pcase` here too.  Furthermore, it
does exactly what we want here, including correctly handling the case
where `bounds-of-thing-at-point` returns nil.  So yes, it's a good use
of `pcase` IMO.  But if you prefer a different style I'm open to adjust
this part, of course.

>> +(defun completion-preview--make-overlay (pos string)
>> +  "Make a new completion preview overlay at POS showing STRING."
>> +  (if completion-preview--overlay
>> +      (move-overlay completion-preview--overlay pos pos)
>> +    (setq completion-preview--overlay (make-overlay pos pos)))
>
> Should this overlay be specific to the selected window?  IOW, do we
> really want to see the preview in all the windows showing this buffer?

Making the preview window-specific is a good idea, thanks.  Done in the
updated patch.

>> +  (add-text-properties 0 1 '(cursor 1) string)
>> +  (overlay-put completion-preview--overlay 'after-string string)
>
> Sounds like you keep calling overlay-put and adding the same property
> to the string each time this function is called, even if the overlay
> already shows the same string?

Even if the preview exists, this function is called with a different
`string` argument than the one already shown.  That `string` is a
substring of a completion candidate, and it doesn't already have the
`cursor` property.  So no, this is not redundant.  There may be room for
an optimization here, but I don't think it'd be significant.

>> +(define-minor-mode completion-preview-active-mode
>> +  "Mode for when the completion preview is active."
>                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> It is better to say "when the completion preview is shown".  "Active"
> is ambiguous here.

Makes sense, done.

>> +(defun completion-preview--exit-function (func)
>> +  "Return an exit function that hides the completion preview and calls FUNC."
>> +  (lambda (&rest args)
>> +    (completion-preview-active-mode -1)
>> +    (when func (apply func args))))
>        ^^^^^^^^^^
> Perhaps "(when (functionp func) ..."?

We're only ever called with either a function or nil here, so this is
basically equivalent.  Still done now to be more explicit.

>> +(defun completion-preview--update ()
>> +  "Update completion preview."
>> +  (pcase (let ((completion-preview-insert-on-completion nil))
>> +           (run-hook-with-args-until-success 'completion-at-point-functions))
>> +    (`(,beg ,end ,table . ,plist)
>
> Why use pcase here and not seq-let?

Because `seq-let` doesn't do the right thing (for our purposes here)
when the sequence that you pass it doesn't have the given shape.
Namely, here `pcase` correctly handles the case where the value is nil
for example, while `seq-let` would require another test in the body
(e.g. `(when beg ...)`) to see if we actually got what we expected.

Anyways, as I mentioned earlier, I'm fine with not using `pcase` here if
there's a reason for that.

>> +(defun completion-preview--show ()
>> +  "Show completion preview."
>> +  (when completion-preview-active-mode
>> +    (let* ((beg (completion-preview--get 'completion-preview-beg))
>> +           (cands (completion-preview--get 'completion-preview-cands))
>> +           (index (completion-preview--get 'completion-preview-index))
>> +           (cand (nth index cands))
>> +           (len (length cand))
>> +           (end (+ beg len))
>> +           (cur (point))
>> +           (face (get-text-property 0 'face (completion-preview--get 'after-string))))
>> +      (if (and (< beg cur end) (string-prefix-p (buffer-substring beg cur) cand))
>> +          (overlay-put (completion-preview--make-overlay
>> +                        cur (propertize (substring cand (- cur beg))
>> +                                        'face face))
>> +                       'completion-preview-end cur)
>> +        (completion-preview-active-mode -1))))
>> +  (while-no-input (completion-preview--update)))
>
> I'm puzzled by this function.  What does it do, and why is it needed?

I've added some comments in the updated patch.  This function is called
in `post-command-hook` if we determined that we want to show the
preview.  It first checks if there's already a preview.  If there is,
then we need to update it before consulting
`completion-at-point-functions` for a new completion candidate, since
that might not be immediate and we never want to show a stale preview.
So we check if the candidate of the existing preview is still applicable
after the command that just run.  If so we update it, otherwise we hide
it.  Finally, we go on to consulting the completion backends inside
`while-no-input`.

>> +(defun completion-preview--post-command ()
>> +  "Create, update or delete completion preview post last command."
>> +  (if (run-hook-with-args-until-failure 'completion-preview-hook)
>> +      (or (completion-preview--internal-command-p)
>> +          (completion-preview--show))
>> +    (completion-preview-active-mode -1)))
>
> This needs more comments to explain the non-trivial logic.

Done.

>> +(defun completion-preview--insert ()
>> +  "Completion at point function for inserting the current preview."
>
> The purpose of this function should be described either in the doc
> string or in some comment.

Sure, I've extended its docstring.

>> +(defun completion-preview-insert ()
>> +  "Insert the current completion preview."
>
> You cannot "insert the preview".  Please reword the doc string.

Right, done.

>> +  (interactive)
>> +  (let ((completion-preview-insert-on-completion t))
>> +    (completion-at-point)))
>
> Why not just insert the string you show in the preview?

This way we let `completion-at-point` to take care of things like
calling the `:exit-function`, instead of duplicating that code.

>> +(defun completion-preview-prev-candidate ()
>> +  "Cycle the preview to the previous completion suggestion."
>
> You are cycling the candidates, not the preview.

Indeed, I rephrased that part in the updated patch.

>> +(defun completion-preview-next-candidate (direction)
>> +  "Cycle the preview to the next completion suggestion in DIRECTION.
>> +
>> +DIRECTION should be either 1 which means cycle forward, or -1
>> +which means cycle backward.  Interactively, DIRECTION is the
>> +prefix argument."            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>    ^^^^^^^^^^^^^^^
> "...and defaults to 1".

Done.

Here's the new patch:


[-- Attachment #2: v4-0001-Add-Completion-Preview-mode.patch --]
[-- Type: text/x-patch, Size: 18348 bytes --]

From 6cabb941aaac089e47a23daf9704ac1d1a1b6abd Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Thu, 2 Nov 2023 16:58:31 +0100
Subject: [PATCH v4] Add Completion Preview mode

This adds a new minor mode, 'completion-preview-mode', that displays
in-buffer completion suggestions with an inline "preview" overlay.
(Bug#66948)

* lisp/completion-preview.el: New file.
* doc/emacs/programs.texi (Symbol Completion): Document it.
* etc/NEWS: Announce it.
---
 doc/emacs/programs.texi    |  15 ++
 etc/NEWS                   |   6 +
 lisp/completion-preview.el | 325 +++++++++++++++++++++++++++++++++++++
 3 files changed, 346 insertions(+)
 create mode 100644 lisp/completion-preview.el

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 7746bc8bc23..61d42723139 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1701,6 +1701,21 @@ Symbol Completion
   In Text mode and related modes, @kbd{M-@key{TAB}} completes words
 based on the spell-checker's dictionary.  @xref{Spelling}.
 
+@cindex completion preview
+@cindex preview completion
+@cindex suggestion preview
+@cindex Completion Preview mode
+@findex completion-preview-mode
+@vindex completion-preview-mode
+  Completion Preview mode is a minor mode that shows you symbol
+completion suggestions as type.  When you enable Completion Preview
+mode in a buffer (with @kbd{M-x completion-preview-mode}), Emacs
+examines the text around point after certain commands you invoke and
+automatically suggests a possible completion.  Emacs displays this
+suggestion with an inline preview right after point, so you see in
+advance exactly how the text will look if you accept the completion
+suggestion---that's why it's called a preview.
+
 @node MixedCase Words
 @section MixedCase Words
 @cindex camel case
diff --git a/etc/NEWS b/etc/NEWS
index 767e4c27b43..0841c8aa860 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1028,6 +1028,12 @@ It highlights parens via ‘show-paren-mode’ and ‘blink-matching-paren’ in
 a user-friendly way, avoids reporting alleged paren mismatches and makes
 sexp navigation more intuitive.
 
++++
+*** New minor mode 'completion-preview-mode'.
+This minor mode shows you symbol completion suggestions as you type,
+using an inline preview.  New user options in the 'completion-preview'
+customization group control exactly when Emacs displays this preview.
+
 ---
 ** The highly accessible Modus themes collection has eight items.
 The 'modus-operandi' and 'modus-vivendi' are the main themes that have
diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el
new file mode 100644
index 00000000000..43b5f8118f8
--- /dev/null
+++ b/lisp/completion-preview.el
@@ -0,0 +1,325 @@
+;;; completion-preview.el --- Preview completion with inline overlay  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2023 Free Software Foundation, Inc.
+
+;; Author: Eshel Yaron <me@eshelyaron.com>
+;; Maintainer: Eshel Yaron <me@eshelyaron.com>
+;; Keywords: abbrev convenience
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This library provides the Completion Preview mode.  This minor mode
+;; displays the top completion candidate for the symbol at point in an
+;; overlay after point.  Check out the customization group
+;; `completion-preview' for user options that you may want to tweak.
+;;
+;; To accept the completion suggestion, press TAB.  If you want to
+;; ignore a completion suggestion, just go on editing or moving around
+;; the buffer.  Completion Preview mode continues to update the
+;; suggestion as you type according to the text around point.
+;;
+;; The commands `completion-preview-next-candidate' and
+;; `completion-preview-prev-candidate' allow you to cycle the
+;; completion candidate that the preview suggests.  These commands
+;; don't have a default keybinding, but you can bind them, for
+;; example, to M-n and M-p in `completion-preview-active-mode-map' to
+;; have them handy whenever the preview is visible.
+;;
+;; If you set the user option `completion-preview-exact-match-only' to
+;; non-nil, Completion Preview mode only suggests a completion
+;; candidate when its the only possible completion for the (partial)
+;; symbol at point.  The user option `completion-preview-commands'
+;; says which commands should trigger the completion preview.  The
+;; user option `completion-preview-minimum-symbol-length' specifies a
+;; minimum number of consecutive characters with word or symbol syntax
+;; that should appear around point for Emacs to suggest a completion.
+;; By default, this option is set to 3, so Emacs suggests a completion
+;; if you type "foo", but typing just "fo" doesn't show the preview.
+;;
+;; The user option `completion-preview-insert-on-completion' controls
+;; what happens when you invoke `completion-at-point' while the
+;; completion preview is visible.  By default this option is nil,
+;; which tells `completion-at-point' to ignore the completion preview
+;; and show the list of completion candidates as usual.  If you set
+;; `completion-preview-insert-on-completion' to non-nil, then
+;; `completion-at-point' inserts the preview directly without looking
+;; for more candidates.
+
+;;; Code:
+
+(defgroup completion-preview nil
+  "In-buffer completion preview."
+  :group 'completion)
+
+(defcustom completion-preview-exact-match-only nil
+  "Whether to show completion preview only when there is an exact match.
+
+If this option is non-nil, Completion Preview mode only shows the
+preview when there is exactly one completion candidate that
+matches the symbol at point.  Otherwise, if this option is nil,
+when there are multiple matching candidates the preview shows the
+first candidate, and you can cycle between the candidates with
+\\[completion-preview-next-candidate] and
+\\[completion-preview-prev-candidate]."
+  :type 'boolean
+  :version "30.1")
+
+(defcustom completion-preview-commands '(self-insert-command
+                                         insert-char
+                                         delete-backward-char
+                                         backward-delete-char-untabify)
+  "List of commands that should trigger completion preview."
+  :type '(repeat (function :tag "Command" :value self-insert-command))
+  :version "30.1")
+
+(defcustom completion-preview-minimum-symbol-length 3
+  "Minimum length of the symbol at point for showing completion preview."
+  :type 'natnum
+  :version "30.1")
+
+(defcustom completion-preview-hook
+  '(completion-preview-require-certain-commands
+    completion-preview-require-minimum-symbol-length)
+  "Hook for functions that determine whether to show preview completion.
+
+Completion Preview mode calls each of these functions in order
+after each command, and only displays the completion preview when
+all of the functions return non-nil."
+  :type 'hook
+  :version "30.1")
+
+(defcustom completion-preview-insert-on-completion nil
+  "Whether \\[completion-at-point] inserts the previewed suggestion."
+  :type 'boolean
+  :version "30.1")
+
+(defvar completion-preview-sort-function #'minibuffer--sort-by-length-alpha
+  "Sort function to use for choosing a completion candidate to preview.")
+
+(defface completion-preview
+  '((t :inherit shadow))
+  "Face for completion preview overlay."
+  :version "30.1")
+
+(defface completion-preview-exact
+  '((t :underline t :inherit completion-preview))
+  "Face for exact completion preview overlay."
+  :version "30.1")
+
+(defvar-keymap completion-preview-active-mode-map
+  :doc "Keymap for Completion Preview Active mode."
+  "C-i" #'completion-preview-insert
+  ;; "M-n" #'completion-preview-next-candidate
+  ;; "M-p" #'completion-preview-prev-candidate
+  )
+
+(defvar-local completion-preview--overlay nil)
+
+(defvar completion-preview--internal-commands
+  '(completion-preview-next-candidate completion-preview-prev-candidate)
+  "List of commands that manipulate the completion preview.")
+
+(defsubst completion-preview--internal-command-p ()
+  "Return non-nil if `this-command' manipulates the completion preview."
+  (memq this-command completion-preview--internal-commands))
+
+(defsubst completion-preview-require-certain-commands ()
+  "Check if `this-command' is one of `completion-preview-commands'."
+  (or (completion-preview--internal-command-p)
+      (memq this-command completion-preview-commands)))
+
+(defun completion-preview-require-minimum-symbol-length ()
+  "Check if the length of symbol at point is at least above a certain threshold.
+`completion-preview-minimum-symbol-length' determines that threshold."
+  (pcase (bounds-of-thing-at-point 'symbol)
+    (`(,beg . ,end)
+     (<= completion-preview-minimum-symbol-length (- end beg)))))
+
+(defun completion-preview-hide ()
+  "Hide the completion preview."
+  (when completion-preview--overlay
+    (delete-overlay completion-preview--overlay)
+    (setq completion-preview--overlay nil)))
+
+(defun completion-preview--make-overlay (pos string)
+  "Make a new completion preview overlay at POS showing STRING."
+  (if completion-preview--overlay
+      (move-overlay completion-preview--overlay pos pos)
+    (setq completion-preview--overlay (make-overlay pos pos)))
+  (add-text-properties 0 1 '(cursor 1) string)
+  (overlay-put completion-preview--overlay 'after-string string)
+  (overlay-put completion-preview--overlay 'window (selected-window))
+  completion-preview--overlay)
+
+(defun completion-preview--get (prop)
+  "Return property PROP of the completion preview overlay."
+  (overlay-get completion-preview--overlay prop))
+
+(define-minor-mode completion-preview-active-mode
+  "Mode for when the completion preview is shown."
+  :interactive nil
+  (if completion-preview-active-mode
+      (add-hook 'completion-at-point-functions #'completion-preview--insert -1 t)
+    (remove-hook 'completion-at-point-functions #'completion-preview--insert t)
+    (completion-preview-hide)))
+
+(defun completion-preview--exit-function (func)
+  "Return an exit function that hides the completion preview and calls FUNC."
+  (lambda (&rest args)
+    (completion-preview-active-mode -1)
+    (when (functionp func) (apply func args))))
+
+(defun completion-preview--update ()
+  "Update completion preview."
+  (pcase (let ((completion-preview-insert-on-completion nil))
+           (run-hook-with-args-until-success 'completion-at-point-functions))
+    (`(,beg ,end ,table . ,plist)
+     (let* ((pred (plist-get plist :predicate))
+            (exit-fn (completion-preview--exit-function
+                      (plist-get plist :exit-function)))
+            (string (buffer-substring beg end))
+            (md (completion-metadata string table pred))
+            (sort-fn (or (completion-metadata-get md 'cycle-sort-function)
+                         (completion-metadata-get md 'display-sort-function)
+                         completion-preview-sort-function))
+            (all (let ((completion-lazy-hilit t))
+                   (completion-all-completions string table pred
+                                               (- (point) beg) md)))
+            (last (last all))
+            (base (or (cdr last) 0))
+            (bbeg (+ beg base))
+            (prefix (substring string base)))
+       (when last
+         (setcdr last nil)
+         (let* ((filtered (remove prefix (all-completions prefix all)))
+                (sorted (funcall sort-fn filtered))
+                (multi (cadr sorted))   ; multiple candidates
+                (cand (car sorted)))
+           (when (and cand (not (and multi completion-preview-exact-match-only)))
+             (let* ((face (if multi 'completion-preview 'completion-preview-exact))
+                    (after (propertize (substring cand (length prefix)) 'face face))
+                    (ov (completion-preview--make-overlay end after)))
+               (overlay-put ov 'completion-preview-beg bbeg)
+               (overlay-put ov 'completion-preview-end end)
+               (overlay-put ov 'completion-preview-index 0)
+               (overlay-put ov 'completion-preview-cands sorted)
+               (overlay-put ov 'completion-preview-exit-fn exit-fn)
+               (completion-preview-active-mode)))))))))
+
+(defun completion-preview--show ()
+  "Show completion preview."
+  (when completion-preview-active-mode
+    ;; We were already showing a preview before this command, so we
+    ;; check if the text before point is still a prefix of the
+    ;; candidate that the preview suggested, and if so we first update
+    ;; existing preview according to the changes made by this command,
+    ;; and only then try to get a new candidate.  This ensures that we
+    ;; never display a stale preview and that the preview doesn't
+    ;; flicker, even with slow completion backends.
+    (let* ((beg (completion-preview--get 'completion-preview-beg))
+           (cands (completion-preview--get 'completion-preview-cands))
+           (index (completion-preview--get 'completion-preview-index))
+           (cand (nth index cands))
+           (len (length cand))
+           (end (+ beg len))
+           (cur (point))
+           (face (get-text-property 0 'face (completion-preview--get 'after-string))))
+      (if (and (< beg cur end) (string-prefix-p (buffer-substring beg cur) cand))
+          ;; The previous preview is still applicable, update it
+          (overlay-put (completion-preview--make-overlay
+                        cur (propertize (substring cand (- cur beg))
+                                        'face face))
+                       'completion-preview-end cur)
+        (completion-preview-active-mode -1))))
+  ;; Reconsult the completion backends to get a possibly new candidate
+  (while-no-input (completion-preview--update)))
+
+(defun completion-preview--post-command ()
+  "Create, update or delete completion preview post last command."
+  (if (run-hook-with-args-until-failure 'completion-preview-hook)
+      ;; We should show the preview
+      (or
+       ;; If we're called after a command that itself updates the
+       ;; preview, don't do anything
+       (completion-preview--internal-command-p)
+       ;; Otherwise, show the preview
+       (completion-preview--show))
+    (completion-preview-active-mode -1)))
+
+(defun completion-preview--insert ()
+  "Completion at point function for inserting the current preview.
+
+When `completion-preview-insert-on-completion' is nil, this
+function returns nil.  Completion Preview mode adds this function
+to `completion-at-point-functions' when the preview is shown,
+such that `completion-at-point' inserts the preview candidate if
+and only if `completion-preview-insert-on-completion' is non-nil."
+  (when (and completion-preview-active-mode
+             completion-preview-insert-on-completion)
+    (list (completion-preview--get 'completion-preview-beg)
+          (completion-preview--get 'completion-preview-end)
+          (list (nth (completion-preview--get 'completion-preview-index)
+                     (completion-preview--get 'completion-preview-cands)))
+          :exit-function (completion-preview--get 'completion-preview-exit-fn))))
+
+(defun completion-preview-insert ()
+  "Insert the completion candidate that the preview shows."
+  (interactive)
+  (let ((completion-preview-insert-on-completion t))
+    (completion-at-point)))
+
+(defun completion-preview-prev-candidate ()
+  "Cycle the candidate that the preview shows to the previous suggestion."
+  (interactive)
+  (completion-preview-next-candidate -1))
+
+(defun completion-preview-next-candidate (direction)
+  "Cycle the candidate that the preview shows in direction DIRECTION.
+
+DIRECTION should be either 1 which means cycle forward, or -1
+which means cycle backward.  Interactively, DIRECTION is the
+prefix argument and defaults to 1."
+  (interactive "p")
+  (when completion-preview-active-mode
+    (let* ((beg (completion-preview--get 'completion-preview-beg))
+           (all (completion-preview--get 'completion-preview-cands))
+           (cur (completion-preview--get 'completion-preview-index))
+           (len (length all))
+           (new (mod (+ cur direction) len))
+           (str (nth new all))
+           (pos (point)))
+      (while (or (<= (+ beg (length str)) pos)
+                 (not (string-prefix-p (buffer-substring beg pos) str)))
+        (setq new (mod (+ new direction) len) str (nth new all)))
+      (let ((aft (propertize (substring str (- pos beg))
+                             'face (if (< 1 len)
+                                       'completion-preview
+                                     'completion-preview-exact))))
+        (add-text-properties 0 1 '(cursor 1) aft)
+        (overlay-put completion-preview--overlay 'completion-preview-index new)
+        (overlay-put completion-preview--overlay 'after-string aft)))))
+
+;;;###autoload
+(define-minor-mode completion-preview-mode
+  "Show in-buffer completion preview as you type."
+  :lighter " CP"
+  (if completion-preview-mode
+      (add-hook 'post-command-hook #'completion-preview--post-command nil t)
+    (remove-hook 'post-command-hook #'completion-preview--post-command t)
+    (completion-preview-active-mode -1)))
+
+(provide 'completion-preview)
+;;; completion-preview.el ends here
-- 
2.42.0