File: xref.el.html
This file provides a generic infrastructure for cross referencing commands, such as "find definition".
The unique functionality is configured by defining an xref backend.
That consists of a constructor function, and implementations for the
generic functions (using cl-defmethod).
The constructor should return a value that cl-defmethod can
dispatch on. Most often it is a plain symbol, such as elisp.
A major or minor mode would use add-hook to set itself up and add
the backend constructor to xref-backend-functions.
Some important backend methods to define are:
xref-backend-identifier-at-point,
xref-backend-identifier-completion-table,
xref-backend-definitions, xref-backend-references,
xref-backend-apropos.
And more optional ones:
xref-backend-identifier-completion-ignore-case,
xref-backend-identifier-completion-predicate,
xref-backend-xref-kinds and xref-backend-xrefs-by-kind.
The methods which return a list of results (such as "definitions")
operate with "xref" and "location" values. Locations are values that
also can be dispatched on by cl-defmethod, usually cl-structs.
One would usually call xref-make and xref-make-file-location,
xref-make-buffer-location or xref-make-bogus-location to create
them. The latter functions correspond to built-in location types.
More generally, a location must also be values that cl-defmethod
can dispatch on, usually cl-structs. Each of them implements
xref-location-group and xref-location-marker.
xref-location-line is optional.
There is a special category of xrefs we call "match xrefs", which
correspond to search results that have spans. For these values,
xref-match-length must be defined, and xref-location-marker must
return the beginning of the match.
Each identifier must be represented as a string. Definitions can use
string properties to store additional information about the
identifier, but strings in xref-backend-identifier-completion-table
should still be distinct, because the user can't see the text
properties when making the choice.
Older versions of Xref used EIEIO for implementation of the
built-in types, and included a class called xref-location which
was supposed to be inherited from. Neither is true anymore.
See the implementations in elisp-mode, eglot and etags for more
complete examples.
Defined variables (41)
global-xref-mouse-mode | Non-nil if Global Xref-Mouse mode is enabled. |
global-xref-mouse-mode-hook | Hook run after entering or leaving ‘global-xref-mouse-mode’. |
xref--current-item | Dynamically bound to the current item being processed. |
xref--fetcher | The original function to call to fetch the list of xrefs. |
xref--history | (BACKWARD-STACK . FORWARD-STACK) of markers to visited Xref locations. |
xref--original-window | The original window this xref buffer was created from. |
xref--original-window-intent | Original window-switching intent before xref buffer creation. |
xref--transient-buffer-mode-abbrev-table | Abbrev table for ‘xref--transient-buffer-mode’. |
xref--transient-buffer-mode-hook | Hook run after entering ‘xref--transient-buffer-mode’. |
xref--transient-buffer-mode-map | Keymap for ‘xref--transient-buffer-mode’. |
xref--transient-buffer-mode-syntax-table | Syntax table for ‘xref--transient-buffer-mode’. |
xref--xref-buffer-mode-abbrev-table | Abbrev table for ‘xref--xref-buffer-mode’. |
xref--xref-buffer-mode-hook | Hook run after entering ‘xref--xref-buffer-mode’. |
xref--xref-buffer-mode-map | Keymap for ‘xref--xref-buffer-mode’. |
xref--xref-buffer-mode-syntax-table | Syntax table for ‘xref--xref-buffer-mode’. |
xref-after-jump-hook | Functions called after jumping to an xref. |
xref-after-return-hook | Functions called after returning to a pre-jump location. |
xref-after-update-hook | Functions called after the xref buffer is updated. |
xref-auto-jump-to-first-definition | If t, ‘xref-find-definitions’ always jumps to the first result. |
xref-auto-jump-to-first-xref | If t, ‘xref-find-references’ always jumps to the first result. |
xref-backend-functions | Special hook to find the xref backend for the current context. |
xref-buffer-name | The name of the buffer to show xrefs. |
xref-current-item | Dynamically bound to the current item being processed. |
xref-edit--prepare-buffer-done | Whether the ‘xref-edit--prepare-buffer’ function has been called. |
xref-edit-mode-hook | Hooks run when changing to Xref-Edit mode. |
xref-edit-mode-map | Keymap for ‘xref-edit-mode’. |
xref-etags-mode | Non-nil if Xref-Etags mode is enabled. |
xref-etags-mode-hook | Hook run after entering or leaving ‘xref-etags-mode’. |
xref-file-name-display | Style of file name display in *xref* buffers. |
xref-history-storage | Function that returns xref history. |
xref-marker-ring-length | Xref marker ring length. |
xref-mouse-mode | Non-nil if Xref-Mouse mode is enabled. |
xref-mouse-mode-hook | Hook run after entering or leaving ‘xref-mouse-mode’. |
xref-num-matches-face | Face name to show the number of matches on the mode line. |
xref-prompt-for-identifier | If non-nil, prompt for the identifier to find. |
xref-references-in-directory-function | Function to find all references to a symbol in a directory. |
xref-search-program | The program to use for regexp search inside files. |
xref-search-program-alist | Association list mapping program identifiers to command templates. |
xref-show-definitions-function | Function to handle the definition search results. |
xref-show-xrefs-function | Function to display a list of search results. |
xref-truncation-width | The column to visually "truncate" each Xref buffer line to. |
Defined functions (181)
Defined faces (3)
xref-file-header | Face used to highlight file header in the xref buffer. |
xref-line-number | Face for displaying line numbers in the xref buffer. |
xref-match | Face used to highlight matches in the xref buffer. |