feat: add tools.open_url option to allow overriding url handler (#58)

CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0] - 2023-11-15
+
+### Added
+
+- Add `tools.open_url` option,
+  to allow users to override how to open external docs.
+
 ## [3.5.1] - 2023-11-13
 
 ### Fixed

doc/rustaceanvim.txt

@@ -102,6 +102,7 @@ RustaceanToolsOpts                                          *RustaceanToolsOpts*
         {reload_workspace_from_cargo_toml?}  (boolean)                                    Automatically call `RustReloadWorkspace` when writing to a Cargo.toml file
         {hover_actions?}                     (RustaceanHoverActionsOpts)                  Options for hover actions
         {create_graph?}                      (RustaceanCrateGraphConfig)                  Options for showing the crate graph based on graphviz and the dot
+        {open_url?}                          (fun(url:string):nil)                        If set, overrides how to open URLs
 
 
 RustaceanHoverActionsOpts                            *RustaceanHoverActionsOpts*

lua/rustaceanvim/commands/external_docs.lua

@@ -1,41 +1,12 @@
 local M = {}
 
 local rl = require('rustaceanvim.rust_analyzer')
-local compat = require('rustaceanvim.compat')
-
----@param url string
-local function open_url(url)
-  ---@param obj table
-  local function on_exit(obj)
-    if obj.code ~= 0 then
-      vim.schedule(function()
-        vim.notify('Could not open URL: ' .. url, vim.log.levels.ERROR)
-      end)
-    end
-  end
-
-  if vim.fn.has('mac') == 1 then
-    compat.system({ 'open', url }, nil, on_exit)
-    return
-  end
-  if vim.fn.executable('sensible-browser') == 1 then
-    compat.system({ 'sensible-browser', url }, nil, on_exit)
-    return
-  end
-  if vim.fn.executable('xdg-open') == 1 then
-    compat.system({ 'xdg-open', url }, nil, on_exit)
-    return
-  end
-  local ok, err = pcall(vim.fn['netrw#BrowseX'], url, 0)
-  if not ok then
-    vim.notify('Could not open external docs. Neither xdg-open, nor netrw found: ' .. err, vim.log.levels.ERROR)
-  end
-end
 
 function M.open_external_docs()
   rl.buf_request(0, 'experimental/externalDocs', vim.lsp.util.make_position_params(), function(_, url)
     if url then
-      open_url(url)
+      local config = require('rustaceanvim.config.internal')
+      config.tools.open_url(url)
     end
   end)
 end

lua/rustaceanvim/config/check.lua

@@ -55,6 +55,7 @@ function M.validate(cfg)
     executor = { tools.executor, { 'table', 'string' } },
     on_initialized = { tools.on_initialized, 'function', true },
     reload_workspace_from_cargo_toml = { tools.reload_workspace_from_cargo_toml, 'boolean' },
+    open_url = { tools.open_url, 'function' },
   })
   if not ok then
     return false, err

lua/rustaceanvim/config/init.lua

@@ -60,6 +60,7 @@ vim.g.rustaceanvim = vim.g.rustaceanvim
 ---@field reload_workspace_from_cargo_toml? boolean Automatically call `RustReloadWorkspace` when writing to a Cargo.toml file
 ---@field hover_actions? RustaceanHoverActionsOpts Options for hover actions
 ---@field create_graph? RustaceanCrateGraphConfig Options for showing the crate graph based on graphviz and the dot
+---@field open_url? fun(url:string):nil If set, overrides how to open URLs
 
 ---@class RustaceanHoverActionsOpts
 ---@field replace_builtin_hover? boolean Whether to replace Neovim's built-in `vim.lsp.buf.hover`

lua/rustaceanvim/config/internal.lua

@@ -145,6 +145,11 @@ local RustaceanDefaultConfig = {
       ---@type string | nil
       pipe = nil,
     },
+
+    ---@type fun(url:string):nil
+    open_url = function(url)
+      require('rustaceanvim.os').open_url(url)
+    end,
   },
 
   --- all the opts to send to the LSP client

lua/rustaceanvim/os.lua

@@ -0,0 +1,36 @@
+---@mod rustaceanvim.os Utilities for interacting with the operating system
+
+local os = {}
+
+local compat = require('rustaceanvim.compat')
+
+---@param url string
+function os.open_url(url)
+  ---@param obj table
+  local function on_exit(obj)
+    if obj.code ~= 0 then
+      vim.schedule(function()
+        vim.notify('Could not open URL: ' .. url, vim.log.levels.ERROR)
+      end)
+    end
+  end
+
+  if vim.fn.has('mac') == 1 then
+    compat.system({ 'open', url }, nil, on_exit)
+    return
+  end
+  if vim.fn.executable('sensible-browser') == 1 then
+    compat.system({ 'sensible-browser', url }, nil, on_exit)
+    return
+  end
+  if vim.fn.executable('xdg-open') == 1 then
+    compat.system({ 'xdg-open', url }, nil, on_exit)
+    return
+  end
+  local ok, err = pcall(vim.fn['netrw#BrowseX'], url, 0)
+  if not ok then
+    vim.notify('Could not open external docs. Neither xdg-open, nor netrw found: ' .. err, vim.log.levels.ERROR)
+  end
+end
+
+return os