Info Catalog elisp: Completion Variables elisp: Completion elisp: Completion in Buffers

elisp: Programmed Completion

 
 19.6.7 Programmed Completion
 ----------------------------
 
 Sometimes it is not possible or convenient to create an alist or an
 obarray containing all the intended possible completions ahead of time.
 In such a case, you can supply your own function to compute the
 completion of a given string.  This is called “programmed completion”.
 Emacs uses programmed completion when completing file names (File
 Name Completion), among many other cases.
 
    To use this feature, pass a function as the COLLECTION argument to
 ‘completing-read’.  The function ‘completing-read’ arranges to pass your
 completion function along to ‘try-completion’, ‘all-completions’, and
 other basic completion functions, which will then let your function do
 all the work.
 
    The completion function should accept three arguments:
 
    • The string to be completed.
 
    • A predicate function with which to filter possible matches, or
      ‘nil’ if none.  The function should call the predicate for each
      possible match, and ignore the match if the predicate returns
      ‘nil’.
 
    • A flag specifying the type of completion operation to perform.
      This flag may be one of the following values.
 
      ‘nil’
           This specifies a ‘try-completion’ operation.  The function
           should return ‘t’ if the specified string is a unique and
           exact match; if there is more than one match, it should return
           the common substring of all matches (if the string is an exact
           match for one completion alternative but also matches other
           longer alternatives, the return value is the string); if there
           are no matches, it should return ‘nil’.
 
      ‘t’
           This specifies an ‘all-completions’ operation.  The function
           should return a list of all possible completions of the
           specified string.
 
      ‘lambda’
           This specifies a ‘test-completion’ operation.  The function
           should return ‘t’ if the specified string is an exact match
           for some completion alternative; ‘nil’ otherwise.
 
      ‘(boundaries . SUFFIX)’
           This specifies a ‘completion-boundaries’ operation.  The
           function should return ‘(boundaries START . END)’, where START
           is the position of the beginning boundary in the specified
           string, and END is the position of the end boundary in SUFFIX.
 
      ‘metadata’
           This specifies a request for information about the state of
           the current completion.  The return value should have the form
           ‘(metadata . ALIST)’, where ALIST is an alist whose elements
           are described below.
 
      If the flag has any other value, the completion function should
      return ‘nil’.
 
    The following is a list of metadata entries that a completion
 function may return in response to a ‘metadata’ flag argument:
 
 ‘category’
      The value should be a symbol describing what kind of text the
      completion function is trying to complete.  If the symbol matches
      one of the keys in ‘completion-category-overrides’, the usual
      completion behavior is overridden.  Completion Variables.
 
 ‘annotation-function’
      The value should be a function for “annotating” completions.  The
      function should take one argument, STRING, which is a possible
      completion.  It should return a string, which is displayed after
      the completion STRING in the ‘*Completions*’ buffer.
 
 ‘display-sort-function’
      The value should be a function for sorting completions.  The
      function should take one argument, a list of completion strings,
      and return a sorted list of completion strings.  It is allowed to
      alter the input list destructively.
 
 ‘cycle-sort-function’
      The value should be a function for sorting completions, when
      ‘completion-cycle-threshold’ is non-‘nil’ and the user is cycling
      through completion alternatives.  (emacs)Completion
      Options.  Its argument list and return value are the same as for
      ‘display-sort-function’.
 
  -- Function: completion-table-dynamic function &optional switch-buffer
      This function is a convenient way to write a function that can act
      as a programmed completion function.  The argument FUNCTION should
      be a function that takes one argument, a string, and returns an
      alist of possible completions of it.  It is allowed to ignore the
      argument and return a full list of all possible completions.  You
      can think of ‘completion-table-dynamic’ as a transducer between
      that interface and the interface for programmed completion
      functions.
 
      If the optional argument SWITCH-BUFFER is non-‘nil’, and completion
      is performed in the minibuffer, FUNCTION will be called with
      current buffer set to the buffer from which the minibuffer was
      entered.
 
  -- Function: completion-table-with-cache function &optional ignore-case
      This is a wrapper for ‘completion-table-dynamic’ that saves the
      last argument-result pair.  This means that multiple lookups with
      the same argument only need to call FUNCTION once.  This can be
      useful when a slow operation is involved, such as calling an
      external process.
 

Info Catalog elisp: Completion Variables elisp: Completion elisp: Completion in Buffers