emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/modules/tools/lookup
History
Henrik Lissner 51d3b1b424
💥 revise advice naming convention (1/2) 
This is first of three big naming convention updates that have been a
long time coming. With 2.1 on the horizon, all the breaking updates will
batched together in preparation for the long haul.

In this commit, we do away with the asterix to communicate that a
function is an advice function, and we replace it with the '-a' suffix.
e.g.

  doom*shut-up -> doom-shut-up-a
  doom*recenter -> doom-recenter-a
  +evil*static-reindent -> +evil--static-reindent-a

The rationale behind this change is:

1. Elisp's own formatting/indenting tools would occasionally struggle
   with | and * (particularly pp and cl-prettyprint). They have no
   problem with / and :, fortunately.
2. External syntax highlighters (like pygmentize, discord markdown or
   github markdown) struggle with it, sometimes refusing to highlight
   code beyond these symbols.
3. * and | are less expressive than - and -- in communicating the
   intended visibility, versatility and stability of a function.
4. It complicated the regexps we must use to search for them.
5. They were arbitrary and over-complicated to begin with, decided
   on haphazardly way back when Doom was simply "my private config".

Anyhow, like how predicate functions have the -p suffix, we'll adopt the
-a suffix for advice functions, -h for hook functions and -fn for
variable functions.

Other noteable changes:
- Replaces advice-{add,remove}! macro with new def-advice!
  macro. The old pair weren't as useful. The new def-advice! saves on a
  lot of space.
- Removed "stage" assertions to make sure you were using the right
  macros in the right place. Turned out to not be necessary, we'll
  employ better checks later.
2019-07-22 02:27:45 +02:00
..
autoload tools/lookup: remove duplicate code & minor fixes 2019-07-05 16:50:03 +02:00
config.el 💥 revise advice naming convention (1/2) 2019-07-22 02:27:45 +02:00
packages.el tools/lookup: update to reflect changes upstream 2019-05-12 01:45:48 -04:00
README.org tools/lookup: update README & docstrings 2019-05-03 20:44:49 -04:00

README.org

tools/lookup

Table of Contents   TOC

Description

Integrates with code navigation and documentation tools to help you quickly look up definitions, references and documentation.

  • Jump-to-definition and find-references implementations that just work.
  • Powerful xref integration for languages that support it.
  • Documentation lookup for a variety of online sources (like devdocs.io, stackoverflow or youtube).
  • Integration with Dash.app docsets.

Module Flags

  • +docsets Enable integration with Dash.app docsets.

Plugins

Prerequisites

This module has several soft dependencies:

  • the_silver_searcher or ripgrep (recommended) as a last-resort fallback for jump-to-definition/find-references.
  • sqlite3 for Dash docset support.

MacOS 

brew install the_silver_searcher ripgrep

# 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 the_silver_searcher ripgrep

Features

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. dumb-jump (a text search with aides to reduce false positives).
  4. An ordinary project-wide text search with ripgrep or the_silver_searcher.
  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" section).
  2. Any available xref backends.
  3. An ordinary project-wide text search with ripgrep or the_silver_searcher.

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 +lookup/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 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 +lookup/install-docset.

Open in eww instead of browser

To open results from +lookup/online in EWW instead of your system browser, change +lookup-open-url-fn (default: #'browse-url):

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

Appendix

Commands

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