Skip to content

Latest commit

 

History

History
254 lines (209 loc) · 9.2 KB

README.org

File metadata and controls

254 lines (209 loc) · 9.2 KB
Raw

:tools lookup

Description

This module adds code navigation and documentation lookup tools to help you quickly look up definitions, references, documentation, dictionary definitions or synonyms.

  • Jump-to-definition and find-references implementations that just work.
  • Powerful xref integration for languages that support it.
  • Search online providers like devdocs.io, stackoverflow, google, duckduckgo, or youtube (duckduckgo and google have live suggestions).
  • Integration with Dash.app docsets.
  • Support for online (and offline) dictionaries and thesauruses.

Maintainers

  • @hlissner

Become a maintainer?

Module flags

+dictionary
Enable word definition and thesaurus lookup functionality.
+docsets
Enable integration with Dash.app docsets.
+offline
Install and prefer offline dictionary/thesaurus (with doom-module:+dictionary).

Packages

  • doom-package:dumb-jump
  • doom-package:helm-xref if doom-module::completion helm
  • doom-package:ivy-xref if doom-module::completion ivy
  • doom-package:request
  • if doom-module:+docsets
    • doom-package:dash-docs
    • doom-package:counsel-dash if doom-module::completion ivy
    • doom-package:helm-dash if doom-module::completion helm
  • if doom-module:+dictionary
    • if macOS
      • doom-package:osx-dictionary
    • else
      • doom-package:define-word
      • doom-package:powerthesaurus
      • if doom-module:+offline
        • doom-package:wordnut
        • doom-package:synosaurus

Hacks

No hacks documented for this module.

Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has several optional dependencies:

  • ripgrep as a last-resort fallback for jump-to-definition/find-references.
  • sqlite3 for Dash docset support (if you have doom-module:+docsets enabled)
  • wordnet for offline dictionary and thesaurus support (if you have doom-module:+dictionary and doom-module:+offline enabled).

MacOS

brew install ripgrep wordnet

# An older version of sqlite is included in MacOS. If it causes you problems (and
# folks have reported it will), install it through homebrew:
brew install sqlite
# Note that it's keg-only, meaning it isn't symlinked to /usr/local/bin. You'll
# have to add it to PATH yourself (or symlink it into your PATH somewhere). e.g.
export PATH="/usr/local/opt/sqlite/bin:$PATH"

Arch Linux

sudo pacman -S sqlite ripgrep
yay -S wordnet-cli

NixOS

environment.systemPackages = with pkgs; [
  ripgrep
  sqlite
  wordnet
];

Usage

Jump to definition

Use +lookup/definition (bound to gd in normal mode) to jump to the definition of the symbol at point.

This module provides a goto-definition implementation that will try the following sources before giving up:

  1. Whatever :definition function is registered for the current buffer with the :lookup setting (see “Configuration” section).
  2. Any available xref backends.
  3. doom-package:dumb-jump (a text search with aides to reduce false positives).
  4. An ordinary project-wide text search with ripgrep.
  5. If evil-mode is active, use evil-goto-definition, which preforms a simple text search within the current buffer.

If there are multiple results, you will be prompted to select one.

Find references

Use +lookup/references (bound to gD in normal mode) to see a list of references for the symbol at point from throughout your project.

Like +lookup/definition, this tries a number of sources before giving up. It will try:

  1. Whatever :references function is registered for the current buffer with the :lookup setting (see Configuration).
  2. Any available doom-package:xref backends.
  3. An ordinary project-wide text search with ripgrep.

If there are multiple results, you will be prompted to select one.

Look up documentation

+lookup/documentation (bound to K in normal mode) will open documentation for the symbol at point.

Depending on your configuration, this will try a list of sources:

  1. Whatever :documentation function is registered for the current buffer with the :lookup setting (see “Configuration” section).
  2. Any Dash.app docsets, if any are installed for the current major mode.
  3. devdocs.io, if it has a docset for the current mode.
  4. An online search; using the last engine used (it will prompt you the first time, or if current-prefix-arg is non-nil).

Search a specific documentation backend

You can perform a documentation lookup on any backends directly:

  • Dash Docsets: +lookup/in-docsets, or :dash QUERY for evil users.
  • Online (generic): +lookup/online or +lookup/online-select (bound to SPC / o), or :lo[okup] QUERY for evil users.

Dash.app Docset integration

You can install dash docsets with M-x dash-docs-install-docset and search them offline with M-x +lookup/in-docsets, or with +lookup/documentation in modes that don’t have a specialized :documentation lookup handler.

Configuration

Associating lookup handlers with major modes

set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE XREF-BACKEND ASYNC

Use set-lookup-handlers! to register lookup targets for MODES (a major or minor mode symbol or list thereof). PLIST accepts the following optional properties:

:definition FN
Run when jumping to a symbol’s definition. Used by +lookup/definition.
:references FN
Run when looking for usage references of a symbol in the current project. Used by +lookup/references.
:documentation FN
Run when looking up documentation for a symbol. Used by +lookup/documentation.
:file FN
Run when looking up the file for a symbol/string. Typically a file path. Used by +lookup/file.
:xref-backend FN
Defines an doom-package:xref backend, which implicitly provides :definition and :references handlers. If you specify them anyway, they will take precedence over the xref backend, however.

E.g.

;; For python-mode, anaconda-mode offers a backend for all three lookup
;; functions. We can register them like so:
(set-lookup-handlers! 'python-mode
  :definition #'anaconda-mode-find-definitions
  :references #'anaconda-mode-find-references
  :documentation #'anaconda-mode-show-doc)

;; If a language or plugin provides a custom xref backend available for it, use
;; that instead. It will provide the best jump-to-definition and find-references
;; experience. You can specify custom xref backends with:
(set-lookup-handlers! 'js2-mode :xref-backend #'xref-js2-xref-backend)
;; NOTE: xref doesn't provide a :documentation backend.

Associating Dash docsets with major modes

set-docsets! MODES &rest DOCSETS...

Use set-docsets! to register DOCSETS (one string or list of strings) for MODES (one major mode symbol or a list of them). It is used by +lookup/in-docsets and +lookup/documentation.

E.g.

(set-docsets! 'js2-mode "JavaScript" "JQuery")
;; Add docsets to minor modes by starting DOCSETS with :add
(set-docsets! 'rjsx-mode :add "React")
;; Or remove docsets from minor modes
(set-docsets! 'nodejs-mode :remove "JQuery")

This determines what docsets to implicitly search for when you use +lookup/documentation in a mode with no :documentation handler. Those docsets must be installed with dash-docs-install-docset.

Open in eww instead of browser

+lookup/online opens the search results with in +lookup-open-url-fn (default: #'browse-url). Here is how to change this to EWW (so it opens inside Emacs):

(setq +lookup-open-url-fn #'eww)

📌 +lookup/in-docsets consults dash-docs-browser-func instead, which is already set to #'eww by default.

Open in Xwidget WebKit instead of browser

To open results from +lookup/online or +lookup/in-docsets in Xwidget WebKit instead of your system browser, set +lookup-open-url-fn and/or dash-docs-browser-func to +lookup-xwidget-webkit-open-url-fn (needs Emacs with Xwidgets support):

(setq +lookup-open-url-fn #'+lookup-xwidget-webkit-open-url-fn)
(after! dash-docs
  (setq dash-docs-browser-func #'+lookup-xwidget-webkit-open-url-fn))

Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

This module has no FAQs yet. Ask one?

Appendix

🔨 This module’s appendix is incomplete. Write more?

Commands

  • +lookup/definition
  • +lookup/references
  • +lookup/documentation
  • +lookup/online
  • +lookup/online-select
  • +lookup/in-devdocs
  • +lookup/in-docsets