fix(vim.ui)!: change open() to return `result|nil, errmsg|nil` #28612

reverts e0d92b9cc20b58179599f53dfa74ca821935a539 #28502

Problem:
`vim.ui.open()` has a `pcall()` like signature, under the assumption
that this is the Lua idiom for returning result-or-error. However, the
`result|nil, errmsg|nil` pattern:
- has precedent in:
  - `io.open`
  - `vim.uv` (`:help luv-error-handling`)
- has these advantages:
  - Can be used with `assert()`:
    ```
    local result, err = assert(foobar())
    ```
  - Allows LuaLS to infer the type of `result`:
    ```
    local result, err = foobar()
    if err then
      ...
    elseif result then
      ...
    end
    ```

Solution:
- Revert to the `result|nil, errmsg|nil` pattern.
- Document the pattern in our guidelines.

1 files changed, 7 insertions, 7 deletions

diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index b8323efa66..3c947c51b0 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -118,16 +118,16 @@ end
 --- vim.ui.open("https://neovim.io/")
 --- vim.ui.open("~/path/to/file")
 --- -- Synchronous (wait until the process exits).
---- local ok, cmd = vim.ui.open("$VIMRUNTIME")
---- if ok then
+--- local cmd, err = vim.ui.open("$VIMRUNTIME")
+--- if cmd then
 ---   cmd:wait()
 --- end
 --- ```
 ---
 ---@param path string Path or URL to open
 ---
----@return boolean # false if command not found, else true.
----@return vim.SystemObj|string # Command object, or error message on failure
+---@return vim.SystemObj|nil # Command object, or nil if not found.
+---@return nil|string # Error message on failure, or nil on success.
 ---
 ---@see |vim.system()|
 function M.open(path)
@@ -147,7 +147,7 @@ function M.open(path)
     if vim.fn.executable('rundll32') == 1 then
       cmd = { 'rundll32', 'url.dll,FileProtocolHandler', path }
     else
-      return false, 'vim.ui.open: rundll32 not found'
+      return nil, 'vim.ui.open: rundll32 not found'
     end
   elseif vim.fn.executable('wslview') == 1 then
     cmd = { 'wslview', path }
@@ -156,10 +156,10 @@ function M.open(path)
   elseif vim.fn.executable('xdg-open') == 1 then
     cmd = { 'xdg-open', path }
   else
-    return false, 'vim.ui.open: no handler found (tried: wslview, explorer.exe, xdg-open)'
+    return nil, 'vim.ui.open: no handler found (tried: wslview, explorer.exe, xdg-open)'
   end
 
-  return true, vim.system(cmd, { text = true, detach = true })
+  return vim.system(cmd, { text = true, detach = true }), nil
 end
 
 return M