Info Catalog elisp: Reading File Names elisp: Completion elisp: Programmed Completion

elisp: Completion Variables

 
 19.6.6 Completion Variables
 ---------------------------
 
 Here are some variables that can be used to alter the default completion
 behavior.
 
  -- User Option: completion-styles
      The value of this variable is a list of completion style (symbols)
      to use for performing completion.  A “completion style” is a set of
      rules for generating completions.  Each symbol occurring this list
      must have a corresponding entry in ‘completion-styles-alist’.
 
  -- Variable: completion-styles-alist
      This variable stores a list of available completion styles.  Each
      element in the list has the form
 
           (STYLE TRY-COMPLETION ALL-COMPLETIONS DOC)
 
      Here, STYLE is the name of the completion style (a symbol), which
      may be used in the ‘completion-styles’ variable to refer to this
      style; TRY-COMPLETION is the function that does the completion;
      ALL-COMPLETIONS is the function that lists the completions; and DOC
      is a string describing the completion style.
 
      The TRY-COMPLETION and ALL-COMPLETIONS functions should each accept
      four arguments: STRING, COLLECTION, PREDICATE, and POINT.  The
      STRING, COLLECTION, and PREDICATE arguments have the same meanings
      as in ‘try-completion’ (Basic Completion), and the POINT
      argument is the position of point within STRING.  Each function
      should return a non-‘nil’ value if it performed its job, and ‘nil’
      if it did not (e.g., if there is no way to complete STRING
      according to the completion style).
 
      When the user calls a completion command like ‘minibuffer-complete’
      (Completion Commands), Emacs looks for the first style
      listed in ‘completion-styles’ and calls its TRY-COMPLETION
      function.  If this function returns ‘nil’, Emacs moves to the next
      listed completion style and calls its TRY-COMPLETION function, and
      so on until one of the TRY-COMPLETION functions successfully
      performs completion and returns a non-‘nil’ value.  A similar
      procedure is used for listing completions, via the ALL-COMPLETIONS
      functions.
 
      (emacs)Completion Styles, for a description of the
      available completion styles.
 
  -- User Option: completion-category-overrides
      This variable specifies special completion styles and other
      completion behaviors to use when completing certain types of text.
      Its value should be an alist with elements of the form ‘(CATEGORY .
      ALIST)’.  CATEGORY is a symbol describing what is being completed;
      currently, the ‘buffer’, ‘file’, and ‘unicode-name’ categories are
      defined, but others can be defined via specialized completion
      functions (Programmed Completion).  ALIST is an association
      list describing how completion should behave for the corresponding
      category.  The following alist keys are supported:
 
      ‘styles’
           The value should be a list of completion styles (symbols).
 
      ‘cycle’
           The value should be a value for ‘completion-cycle-threshold’
           ((emacs)Completion Options) for this category.
 
      Additional alist entries may be defined in the future.
 
  -- Variable: completion-extra-properties
      This variable is used to specify extra properties of the current
      completion command.  It is intended to be let-bound by specialized
      completion commands.  Its value should be a list of property and
      value pairs.  The following properties are supported:
 
      ‘:annotation-function’
           The value should be a function to add annotations in the
           completions buffer.  This function must accept one argument, a
           completion, and should either return ‘nil’ or a string to be
           displayed next to the completion.
 
      ‘:exit-function’
           The value should be a function to run after performing
           completion.  The function should accept two arguments, STRING
           and STATUS, where STRING is the text to which the field was
           completed, and STATUS indicates what kind of operation
           happened: ‘finished’ if text is now complete, ‘sole’ if the
           text cannot be further completed but completion is not
           finished, or ‘exact’ if the text is a valid completion but may
           be further completed.
 

Info Catalog elisp: Reading File Names elisp: Completion elisp: Programmed Completion