[Emacs-diffs] trunk r116914: Discuss using lazy completion tables for inline completion.

[Daniel Colascione]

------------------------------------------------------------
revno: 116914
revision-id: address@hidden
parent: address@hidden
committer: Daniel Colascione <address@hidden>
branch nick: trunk
timestamp: Sun 2014-03-30 19:25:02 -0700
message:
  Discuss using lazy completion tables for inline completion.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/minibuf.texi       
minibuf.texi-20091113204419-o5vbwnq5f7feedwu-6199

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-28 01:29:54 +0000
+++ b/doc/lispref/ChangeLog     2014-03-31 02:25:02 +0000
@@ -1,3 +1,8 @@
+2014-03-31  Daniel Colascione  <address@hidden>
+
+       * minibuf.texi (Completion in Buffers): Discuss using lazy
+       completion tables for inline completion.
+
 2014-03-28  Glenn Morris  <address@hidden>
 
        * os.texi (Terminal-Specific): Mention term-file-aliases.

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2014-03-18 01:19:03 +0000
+++ b/doc/lispref/minibuf.texi  2014-03-31 02:25:02 +0000
@@ -1873,11 +1873,34 @@
 reporting a completion failure.
 @end table
 
+Supplying a function for @var{collection} is strongly recommended if
+generating the list of completions is an expensive operation.  Emacs
+may internally call functions in @code{completion-at-point-functions}
+many times, but care about the value of @var{collection} for only some
+of these calls.  By supplying a function for @var{collection}, Emacs
+can defer generating completions until necessary.  You can use
address@hidden to create a wrapper function:
+
address@hidden
+;; Avoid this pattern.
+(let ((beg ...) (end ...) (my-completions (my-make-completions)))
+  (list beg end my-completions))
+
+;; Use this instead.
+(let ((beg ...) (end ...))
+  (list beg
+        end
+        (completion-table-dynamic
+          (lambda (_)
+            (my-make-completions)))))
address@hidden smallexample
+
 A function in @code{completion-at-point-functions} may also return a
-function.  In that case, that returned function is called, with no
-argument, and it is entirely responsible for performing the
-completion.  We discourage this usage; it is intended to help convert
-old code to using @code{completion-at-point}.
+function instead of a list as described above.  In that case, that
+returned function is called, with no argument, and it is entirely
+responsible for performing the completion.  We discourage this usage;
+it is intended to help convert old code to using
address@hidden
 
 The first function in @code{completion-at-point-functions} to return a
 address@hidden value is used by @code{completion-at-point}.  The