Previous: Programmed Completion, Up: Completion [Contents][Index]

#### 19.6.8 Completion in Ordinary Buffers

Although completion is usually done in the minibuffer, the completion facility can also be used on the text in ordinary Emacs buffers. In many major modes, in-buffer completion is performed by the `C-M-i` or `M-TAB` command, bound to `completion-at-point`. See Symbol Completion in The GNU Emacs Manual. This command uses the abnormal hook variable `completion-at-point-functions`:

Variable: completion-at-point-functions

  The value of this abnormal hook should be a list of functions, which are used to compute a completion table for completing the text at point. It can be used by major modes to provide mode-specific completion tables (see Major Mode Conventions).

  When the command `completion-at-point` runs, it calls the functions in the list one by one, without any argument. Each function should return `nil` if it is unable to produce a completion table for the text at point. Otherwise it should return a list of the form

      (start end collection . props)

  start and end delimit the text to complete (which should enclose point). collection is a completion table for completing that text, in a form suitable for passing as the second argument to `try-completion` (see Basic Completion); completion alternatives will be generated from this completion table in the usual way, via the completion styles defined in `completion-styles` (see Completion Variables). props is a property list for additional information; any of the properties in `completion-extra-properties` are recognized (see Completion Variables), as well as the following additional ones:

  `:predicate`

    The value should be a predicate that completion candidates need to satisfy.

  `:exclusive`

    If the value is `no`, then if the completion table fails to match the text at point, `completion-at-point` moves on to the next function in `completion-at-point-functions` instead of reporting a completion failure.

  Supplying a function for collection is strongly recommended if generating the list of completions is an expensive operation. Emacs may internally call functions in `completion-at-point-functions` many times, but care about the value of collection for only some of these calls. By supplying a function for collection, Emacs can defer generating completions until necessary. You can use completion-table-dynamic to create a wrapper function:

      ;; 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)))))

  A function in `completion-at-point-functions` may also return a 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 `completion-at-point`.

  The first function in `completion-at-point-functions` to return a non-`nil` value is used by `completion-at-point`. The remaining functions are not called. The exception to this is when there is an `:exclusive` specification, as described above.

The following function provides a convenient way to perform completion on an arbitrary stretch of text in an Emacs buffer:

Function: completion-in-region start end collection &optional predicate

  This function completes the text in the current buffer between the positions start and end, using collection. The argument collection has the same meaning as in `try-completion` (see Basic Completion).

  This function inserts the completion text directly into the current buffer. Unlike `completing-read` (see Minibuffer Completion), it does not activate the minibuffer.

  For this function to work, point must be somewhere between start and end.

Previous: Programmed Completion, Up: Completion [Contents][Index]