Merge remote-tracking branch 'upstream/master' into userreguserreg

1 files changed, 84 insertions, 27 deletions

diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index 8f5be15221..b6ddf337ce 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -1,6 +1,24 @@
 local M = {}
 
---- Prompts the user to pick a single item from a collection of entries
+--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
+--- work until `on_choice`.
+---
+--- Example:
+---
+--- ```lua
+--- vim.ui.select({ 'tabs', 'spaces' }, {
+---     prompt = 'Select tabs or spaces:',
+---     format_item = function(item)
+---         return "I'd like to choose " .. item
+---     end,
+--- }, function(choice)
+---     if choice == 'spaces' then
+---         vim.o.expandtab = true
+---     else
+---         vim.o.expandtab = false
+---     end
+--- end)
+--- ```
 ---
 ---@param items table Arbitrary items
 ---@param opts table Additional options
@@ -18,24 +36,6 @@ local M = {}
 ---               Called once the user made a choice.
 ---               `idx` is the 1-based index of `item` within `items`.
 ---               `nil` if the user aborted the dialog.
----
----
---- Example:
---- <pre>lua
---- vim.ui.select({ 'tabs', 'spaces' }, {
----     prompt = 'Select tabs or spaces:',
----     format_item = function(item)
----         return "I'd like to choose " .. item
----     end,
---- }, function(choice)
----     if choice == 'spaces' then
----         vim.o.expandtab = true
----     else
----         vim.o.expandtab = false
----     end
---- end)
---- </pre>
-
 function M.select(items, opts, on_choice)
   vim.validate({
     items = { items, 'table', false },
@@ -55,7 +55,16 @@ function M.select(items, opts, on_choice)
   end
 end
 
---- Prompts the user for input
+--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
+--- `on_confirm`.
+---
+--- Example:
+---
+--- ```lua
+--- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
+---     vim.o.shiftwidth = tonumber(input)
+--- end)
+--- ```
 ---
 ---@param opts table Additional options. See |input()|
 ---     - prompt (string|nil)
@@ -76,13 +85,6 @@ end
 ---               `input` is what the user typed (it might be
 ---               an empty string if nothing was entered), or
 ---               `nil` if the user aborted the dialog.
----
---- Example:
---- <pre>lua
---- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
----     vim.o.shiftwidth = tonumber(input)
---- end)
---- </pre>
 function M.input(opts, on_confirm)
   vim.validate({
     on_confirm = { on_confirm, 'function', false },
@@ -103,4 +105,59 @@ function M.input(opts, on_confirm)
   end
 end
 
+--- Opens `path` with the system default handler (macOS `open`, Windows `explorer.exe`, Linux
+--- `xdg-open`, …), or returns (but does not show) an error message on failure.
+---
+--- Expands "~/" and environment variables in filesystem paths.
+---
+--- Examples:
+---
+--- ```lua
+--- vim.ui.open("https://neovim.io/")
+--- vim.ui.open("~/path/to/file")
+--- vim.ui.open("$VIMRUNTIME")
+--- ```
+---
+---@param path string Path or URL to open
+---
+---@return vim.SystemCompleted|nil # Command result, or nil if not found.
+---@return string|nil # Error message on failure
+---
+---@see |vim.system()|
+function M.open(path)
+  vim.validate({
+    path = { path, 'string' },
+  })
+  local is_uri = path:match('%w+:')
+  if not is_uri then
+    path = vim.fn.expand(path)
+  end
+
+  local cmd
+
+  if vim.fn.has('mac') == 1 then
+    cmd = { 'open', path }
+  elseif vim.fn.has('win32') == 1 then
+    if vim.fn.executable('rundll32') == 1 then
+      cmd = { 'rundll32', 'url.dll,FileProtocolHandler', path }
+    else
+      return nil, 'vim.ui.open: rundll32 not found'
+    end
+  elseif vim.fn.executable('wslview') == 1 then
+    cmd = { 'wslview', path }
+  elseif vim.fn.executable('xdg-open') == 1 then
+    cmd = { 'xdg-open', path }
+  else
+    return nil, 'vim.ui.open: no handler found (tried: wslview, xdg-open)'
+  end
+
+  local rv = vim.system(cmd, { text = true, detach = true }):wait()
+  if rv.code ~= 0 then
+    local msg = ('vim.ui.open: command failed (%d): %s'):format(rv.code, vim.inspect(cmd))
+    return rv, msg
+  end
+
+  return rv, nil
+end
+
 return M