File: xref.el.html

This file provides a somewhat generic infrastructure for cross referencing commands, in particular "find-definition".

Some part of the functionality must be implemented in a language dependent way and that's done by defining an xref backend.

That consists of a constructor function, which should return a backend value, and a set of implementations for the generic functions:

xref-backend-identifier-at-point, xref-backend-identifier-completion-table, xref-backend-definitions, xref-backend-references, xref-backend-apropos, which see.

A major mode would normally use add-hook to add the backend constructor to xref-backend-functions.

The last three methods operate with "xref" and "location" values.

One would usually call xref-make and xref-make-file-location, xref-make-buffer-location or xref-make-bogus-location to create them. More generally, a location must be an instance of a type for which methods xref-location-group and xref-location-marker are implemented.

There's a special kind of xrefs we call "match xrefs", which correspond to search results. 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. Implementers can use string properties to store additional information about the identifier, but they should keep in mind that values returned from xref-backend-identifier-completion-table should still be distinct, because the user can't see the 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 etags and elisp-mode implementations for full examples.

Defined variables (33)

xref--current-itemDynamically bound to the current item being processed.
xref--fetcherThe original function to call to fetch the list of xrefs.
xref--history(BACKWARD-STACK . FORWARD-STACK) of markers to visited Xref locations.
xref--original-windowThe original window this xref buffer was created from.
xref--original-window-intentOriginal window-switching intent before xref buffer creation.
xref--transient-buffer-mode-abbrev-tableAbbrev table for ‘xref--transient-buffer-mode’.
xref--transient-buffer-mode-hookHook run after entering ‘xref--transient-buffer-mode’.
xref--transient-buffer-mode-mapKeymap for ‘xref--transient-buffer-mode’.
xref--transient-buffer-mode-syntax-tableSyntax table for ‘xref--transient-buffer-mode’.
xref--xref-buffer-mode-abbrev-tableAbbrev table for ‘xref--xref-buffer-mode’.
xref--xref-buffer-mode-hookHook run after entering ‘xref--xref-buffer-mode’.
xref--xref-buffer-mode-mapKeymap for ‘xref--xref-buffer-mode’.
xref--xref-buffer-mode-syntax-tableSyntax table for ‘xref--xref-buffer-mode’.
xref-after-jump-hookFunctions called after jumping to an xref.
xref-after-return-hookFunctions called after returning to a pre-jump location.
xref-after-update-hookFunctions called after the xref buffer is updated.
xref-auto-jump-to-first-definitionIf t, ‘xref-find-definitions’ always jumps to the first result.
xref-auto-jump-to-first-xrefIf t, ‘xref-find-references’ always jumps to the first result.
xref-backend-functionsSpecial hook to find the xref backend for the current context.
xref-buffer-nameThe name of the buffer to show xrefs.
xref-current-itemDynamically bound to the current item being processed.
xref-etags-modeNon-nil if Xref-Etags mode is enabled.
xref-etags-mode-hookHook run after entering or leaving ‘xref-etags-mode’.
xref-file-name-displayStyle of file name display in *xref* buffers.
xref-history-storageFunction that returns xref history.
xref-marker-ring-lengthXref marker ring length.
xref-num-matches-faceFace name to show the number of matches on the mode line.
xref-prompt-for-identifierIf non-nil, prompt for the identifier to find.
xref-search-programThe program to use for regexp search inside files.
xref-search-program-alistAssociation list mapping program identifiers to command templates.
xref-show-definitions-functionFunction to handle the definition search results.
xref-show-xrefs-functionFunction to display a list of search results.
xref-truncation-widthThe column to visually "truncate" each Xref buffer line to.

Defined functions (164)

(setf xref-item-location)(xref-item-location\) VAL X)
(setf xref-item-summary)(xref-item-summary\) VAL X)
(setf xref-match-item-length)(xref-match-item-length\) VAL X)
(setf xref-match-item-location)(xref-match-item-location\) VAL X)
(setf xref-match-item-summary)(xref-match-item-summary\) VAL X)
copy-xref-bogus-location(ARG)
copy-xref-buffer-location(ARG)
copy-xref-file-location(ARG)
copy-xref-item(ARG)
copy-xref-match-item(ARG)
make-xref-bogus-location
make-xref-bogus-location--cmacro
make-xref-buffer-location
make-xref-buffer-location--cmacro
make-xref-file-location
make-xref-file-location--cmacro
make-xref-item
make-xref-match-item
xref--add-log-current-defun()
xref--alistify(LIST KEY)
xref--analyze(XREFS)
xref--auto-jump-first(BUF VALUE)
xref--buf-pairs-iterator(XREFS)
xref--collect-matches(HIT REGEXP TMP-BUFFER SYNTAX-NEEDED)
xref--collect-matches-1(REGEXP FILE LINE LINE-BEG LINE-END SYNTAX-NEEDED)
xref--completing-read-group(CAND TRANSFORM)
xref--convert-hits(HITS REGEXP)
xref--create-fetcher(INPUT KIND ARG)
xref--defstruct(NAME &rest FIELDS)
xref--display-buffer-in-other-window(BUFFER ALIST)
xref--display-buffer-in-window(BUFFER ALIST)
xref--ensure-default-directory(DD BUFFER)
xref--find-definitions(ID DISPLAY-ACTION)
xref--find-file-buffer(FILE)
xref--find-ignores-arguments(IGNORES DIR)
xref--find-xrefs(INPUT KIND ARG DISPLAY-ACTION)
xref--get-history()
xref--goto-char(POS)
xref--goto-location(LOCATION)
xref--group-name-for-display(GROUP PROJECT-ROOT)
xref--imenu-extract-index-name()
xref--imenu-prev-index-position()
xref--insert-propertized(PROPS &rest STRINGS)
xref--insert-xrefs(XREF-ALIST)
xref--make-xref-history()
xref--mouse-2(EVENT)
xref--next-error-function(N RESET?)
xref--not-found-error(KIND INPUT)
xref--outdated-p(ITEM)
xref--process-file-region(START END PROGRAM &optional BUFFER DISPLAY &rest ARGS)
xref--project-root(PROJECT)
xref--prompt-p(COMMAND)
xref--push-backward(M)
xref--push-forward(M)
xref--push-markers(BUF PT WIN)
xref--query-replace-1(FROM TO ITER)
xref--read-identifier(PROMPT)
xref--regexp-syntax-dependent-p(STR)
xref--regexp-to-extended(STR)
xref--revert-buffer(&rest _)
xref--rgrep-command(REGEXP FILES DIR IGNORES)
xref--search-property(PROPERTY &optional BACKWARD)
xref--set-arrow()
xref--show-common-initialize(XREF-ALIST FETCHER ALIST)
xref--show-defs(XREFS DISPLAY-ACTION)
xref--show-defs-buffer(FETCHER ALIST)
xref--show-defs-buffer-at-bottom(FETCHER ALIST)
xref--show-defs-minibuffer(FETCHER ALIST)
xref--show-location(LOCATION &optional SELECT)
xref--show-pos-in-buf(POS BUF)
xref--show-xref-buffer(FETCHER ALIST)
xref--show-xrefs(FETCHER DISPLAY-ACTION &optional ALWAYS-SHOW-LIST)
xref--switch-to-buffer(BUF)
xref--transient-buffer-mode()
xref--with-connection-local-variables(&rest BODY)
xref--with-dedicated-window(&rest BODY)
xref--xref-buffer-mode()
xref-apropos-regexp(PATTERN)
xref-backend-apropos(BACKEND PATTERN)
xref-backend-definitions(BACKEND IDENTIFIER)
xref-backend-identifier-at-point(BACKEND)
xref-backend-identifier-completion-ignore-case(BACKEND)
xref-backend-identifier-completion-table(BACKEND)
xref-backend-references(BACKEND IDENTIFIER)
xref-bogus-location-message(xref-bogus-location-message X)
xref-bogus-location-message--inliner(INLINE--FORM X)
xref-bogus-location-p(X)
xref-bogus-location-p--inliner(INLINE--FORM X)
xref-buffer-location-buffer(xref-buffer-location-buffer X)
xref-buffer-location-buffer--inliner(INLINE--FORM X)
xref-buffer-location-p(X)
xref-buffer-location-p--inliner(INLINE--FORM X)
xref-buffer-location-position(xref-buffer-location-position X)
xref-buffer-location-position--inliner(INLINE--FORM X)
xref-clear-marker-stack()
xref-collect-matches(REGEXP FILES DIR IGNORES)
xref-collect-references(SYMBOL DIR)
xref-etags-mode(&optional ARG)
xref-file-location-column(xref-file-location-column X)
xref-file-location-column--inliner(INLINE--FORM X)
xref-file-location-file(xref-file-location-file X)
xref-file-location-file--inliner(INLINE--FORM X)
xref-file-location-line(xref-file-location-line X)
xref-file-location-line--inliner(INLINE--FORM X)
xref-file-location-p(X)
xref-file-location-p--inliner(INLINE--FORM X)
xref-find-apropos(PATTERN)
xref-find-definitions(IDENTIFIER)
xref-find-definitions-at-mouse(EVENT)
xref-find-definitions-other-frame(IDENTIFIER)
xref-find-definitions-other-window(IDENTIFIER)
xref-find-references(IDENTIFIER)
xref-find-references-and-replace(FROM TO)
xref-find-references-at-mouse(EVENT)
xref-forward-history-empty-p()
xref-global-history(&optional NEW-VALUE)
xref-go-back()
xref-go-forward()
xref-goto-xref(&optional QUIT)
xref-item-location(xref-item-location X)
xref-item-p(X)
xref-item-summary(xref-item-summary X)
xref-location-group(LOCATION)
xref-location-line(LOCATION)
xref-location-marker(LOCATION)
xref-make(SUMMARY LOCATION)
xref-make-bogus-location(MESSAGE)
xref-make-bogus-location--cmacro(CL-WHOLE-ARG MESSAGE)
xref-make-buffer-location(BUFFER POSITION)
xref-make-buffer-location--cmacro(CL-WHOLE-ARG BUFFER POSITION)
xref-make-file-location(FILE LINE COLUMN)
xref-make-file-location--cmacro(CL-WHOLE-ARG FILE LINE COLUMN)
xref-make-match(SUMMARY LOCATION LENGTH)
xref-marker-stack-empty-p()
xref-match-item-length(xref-match-item-length X)
xref-match-item-location(xref-match-item-location X)
xref-match-item-p(X)
xref-match-item-summary(xref-match-item-summary X)
xref-match-length(ITEM)
xref-matches-in-directory(REGEXP FILES DIR IGNORES)
xref-matches-in-files(REGEXP FILES)
xref-next-group()
xref-next-line()
xref-next-line-no-show()
xref-pop-marker-stack()
xref-pop-to-location(ITEM &optional ACTION)
xref-prev-group()
xref-prev-line()
xref-prev-line-no-show()
xref-push-marker-stack(&optional M)
xref-query-replace-in-results(FROM TO)
xref-quit-and-goto-xref()
xref-quit-and-pop-marker-stack()
xref-references-in-directory(SYMBOL DIR)
xref-revert-buffer(&optional IGNORE-AUTO NOCONFIRM PRESERVE-MODES)
xref-revert-buffer-restore-point()
xref-select-and-show-xref(EVENT)
xref-set-marker-ring-length(VAR VAL)
xref-show-definitions-buffer(FETCHER ALIST)
xref-show-definitions-buffer-at-bottom(FETCHER ALIST)
xref-show-definitions-completing-read(FETCHER ALIST)
xref-show-location-at-point()
xref-show-xrefs(FETCHER DISPLAY-ACTION)
xref-window-local-history(&optional NEW-VALUE)

Defined faces (3)

xref-file-headerFace used to highlight file header in the xref buffer.
xref-line-numberFace for displaying line numbers in the xref buffer.
xref-matchFace used to highlight matches in the xref buffer.