Implement textdocument/documentHighlight

- Using a queue/purge model like in notifying document changes.
- Using "text" scope for unknown and text kinds, "markup" for read/write.
- Add the kind of document highlights to protocol.py
- Allow users to change the presentation style:
  * Users can choose underline, stippled or squiggly.
  * Users can change the scope per kind.
- Timeout of 500ms after no selection changes before sending out a document
  highlight request.

Author: rwols

LSP.sublime-settings

@@ -155,6 +155,18 @@
   // Valid values are "underline" or "box"
   "diagnostics_highlight_style": "underline",
 
+  // Highlighting style of "highlights": accentuating nearby text entities that
+  // are related to the one under your cursor.
+  // Valid values are "underline", "stippled" or "squiggly".
+  "document_highlight_style": "underline",
+
+  "document_highlight_scopes": {
+    "unknown": "text",
+    "text": "text",
+    "read": "markup.inserted",
+    "write": "markup.changed"
+  },
+
   // Gutter marker for code diagnostics.
   // Valid values are "bookmark", "circle", "cross", "dot" or ""
   "diagnostics_gutter_marker": "dot",

boot.py

@@ -8,6 +8,7 @@
 from .plugin.diagnostics import *
 from .plugin.configuration import *
 from .plugin.formatting import *
+from .plugin.highlights import *
 from .plugin.definition import *
 from .plugin.hover import *
 from .plugin.references import *

plugin/core/protocol.py

@@ -57,6 +57,14 @@ class CompletionItemKind(object):
     Reference = 18
 
 
+class DocumentHighlightKind(object):
+    Unknown = 0
+    Text = 1
+    Read = 2
+    Write = 3
+    Count = 4
+
+
 class Request:
     def __init__(self, method: str, params: 'Optional[dict]') -> None:
         self.method = method
@@ -111,6 +119,10 @@ def rangeFormatting(cls, params: dict):
     def documentSymbols(cls, params: dict):
         return Request("textDocument/documentSymbol", params)
 
+    @classmethod
+    def documentHighlight(cls, params: dict):
+        return Request("textDocument/documentHighlight", params)
+
     @classmethod
     def resolveCompletionItem(cls, params: dict):
         return Request("completionItem/resolve", params)

plugin/core/settings.py

@@ -43,6 +43,13 @@ def __init__(self):
         self.show_diagnostics_in_view_status = True
         self.only_show_lsp_completions = False
         self.diagnostics_highlight_style = "underline"
+        self.document_highlight_style = "stippled"
+        self.document_highlight_scopes = {
+            "unknown": "text",
+            "text": "text",
+            "read": "markup.inserted",
+            "write": "markup.changed"
+        }
         self.diagnostics_gutter_marker = "dot"
         self.complete_all_chars = False
         self.completion_hint_type = "auto"
@@ -59,6 +66,14 @@ def update(self, settings_obj: sublime.Settings):
         self.show_diagnostics_phantoms = read_bool_setting(settings_obj, "show_diagnostics_phantoms", False)
         self.show_diagnostics_in_view_status = read_bool_setting(settings_obj, "show_diagnostics_in_view_status", True)
         self.diagnostics_highlight_style = read_str_setting(settings_obj, "diagnostics_highlight_style", "underline")
+        self.document_highlight_style = read_str_setting(settings_obj, "document_highlight_style", "stippled")
+        self.document_highlight_scopes = read_dict_setting(
+            settings_obj, "document_highlight_scopes", {
+                "unknown": "text",
+                "text": "text",
+                "read": "markup.inserted",
+                "write": "markup.changed"
+            })
         self.diagnostics_gutter_marker = read_str_setting(settings_obj, "diagnostics_gutter_marker", "dot")
         self.only_show_lsp_completions = read_bool_setting(settings_obj, "only_show_lsp_completions", False)
         self.complete_all_chars = read_bool_setting(settings_obj, "complete_all_chars", True)

plugin/highlights.py

@@ -0,0 +1,97 @@
+import sublime_plugin
+
+from .core.configurations import is_supported_syntax
+from .core.protocol import Request, Range, DocumentHighlightKind
+from .core.clients import client_for_view
+from .core.documents import get_document_position
+from .core.settings import settings
+
+import sublime  # only for typing
+
+
+_kind2name = {
+    DocumentHighlightKind.Unknown: "unknown",
+    DocumentHighlightKind.Text: "text",
+    DocumentHighlightKind.Read: "read",
+    DocumentHighlightKind.Write: "write"
+}
+
+
+class DocumentHighlightListener(sublime_plugin.ViewEventListener):
+
+    @classmethod
+    def is_applicable(cls, settings):
+        syntax = settings.get('syntax')
+        return syntax and is_supported_syntax(syntax)
+
+    def __init__(self, view: sublime.View) -> None:
+        super().__init__(view)
+        self._initialized = False
+        self._enabled = False
+        self._version = 0
+
+    def on_selection_modified_async(self) -> None:
+        if not self._initialized:
+            self._initialize()
+        if self._enabled:
+            self._clear_regions()
+            self._queue()
+
+    def _queue(self) -> None:
+        self._version += 1
+        current_version = self._version
+        sublime.set_timeout_async(lambda: self._purge(current_version), 500)
+
+    def _purge(self, this_version: int) -> None:
+        if this_version == self._version:
+            self._on_document_highlight()
+
+    def _clear_regions(self) -> None:
+        for kind in settings.document_highlight_scopes.keys():
+            self.view.erase_regions("LspDocumentHighlightListener_{}".format(kind))
+
+    def _on_document_highlight(self) -> None:
+        self._clear_regions()
+        if len(self.view.sel()) != 1:
+            return
+        point = self.view.sel()[0].begin()
+        if self.view.match_selector(point, "comment"):
+            # We're inside a comment, go home.
+            return
+        client = client_for_view(self.view)
+        if client:
+            params = get_document_position(self.view, point)
+            if params:
+                request = Request.documentHighlight(params)
+                client.send_request(request, self._handle_response)
+
+    def _handle_response(self, response: list) -> None:
+        if not response:
+            return
+        kind2regions = {}  # type: Dict[str, List[sublime.Region]]
+        for kind in range(0, DocumentHighlightKind.Count):
+            kind2regions[_kind2name[kind]] = []
+        for highlight in response:
+            if highlight:
+                r = Range.from_lsp(highlight["range"]).to_region(self.view)
+                kind = highlight.get("kind", DocumentHighlightKind.Unknown)
+                kind2regions[_kind2name[kind]].append(r)
+        flags = sublime.DRAW_NO_FILL | sublime.DRAW_NO_OUTLINE
+        if settings.document_highlight_style == "underline":
+            flags |= sublime.DRAW_SOLID_UNDERLINE
+        elif settings.document_highlight_style == "stippled":
+            flags |= sublime.DRAW_STIPPLED_UNDERLINE
+        elif settings.document_highlight_style == "squiggly":
+            flags |= sublime.DRAW_SQUIGGLY_UNDERLINE
+        self._clear_regions()
+        for kind, regions in kind2regions.items():
+            if regions:
+                scope = settings.document_highlight_scopes.get(kind, None)
+                self.view.add_regions("LspDocumentHighlightListener_{}".format(kind),
+                                      regions, scope=scope, flags=flags)
+
+    def _initialize(self) -> None:
+        self._initialized = True
+        client = client_for_view(self.view)
+        if client:
+            self._enabled = client.get_capability("documentHighlightProvider")