feat(lua): add `vim.system()`

feat(lua): add vim.system()

Problem:

  Handling system commands in Lua is tedious and error-prone:
  - vim.fn.jobstart() is vimscript and comes with all limitations attached to typval.
  - vim.loop.spawn is too low level

Solution:

  Add vim.system().
  Partly inspired by Python's subprocess module
  Does not expose any libuv objects.

2 files changed, 73 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 38289dc5d0..5e0a1edc11 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1566,6 +1566,77 @@ schedule_wrap({cb})                                      *vim.schedule_wrap()*
       • |vim.schedule()|
       • |vim.in_fast_event()|
 
+system({cmd}, {opts}, {on_exit})                                *vim.system()*
+    Run a system command
+
+    Examples: >lua
+
+      local on_exit = function(obj)
+        print(obj.code)
+        print(obj.signal)
+        print(obj.stdout)
+        print(obj.stderr)
+      end
+
+      -- Run asynchronously
+      vim.system({'echo', 'hello'}, { text = true }, on_exit)
+
+      -- Run synchronously
+      local obj = vim.system({'echo', 'hello'}, { text = true }):wait()
+      -- { code = 0, signal = 0, stdout = 'hello', stderr = '' }
+<
+
+    See |uv.spawn()| for more details.
+
+    Parameters: ~
+      • {cmd}      (string[]) Command to execute
+      • {opts}     (SystemOpts|nil) Options:
+                   • cwd: (string) Set the current working directory for the
+                     sub-process.
+                   • env: table<string,string> Set environment variables for
+                     the new process. Inherits the current environment with
+                     `NVIM` set to |v:servername|.
+                   • clear_env: (boolean) `env` defines the job environment
+                     exactly, instead of merging current environment.
+                   • stdin: (string|string[]|boolean) If `true`, then a pipe
+                     to stdin is opened and can be written to via the
+                     `write()` method to SystemObj. If string or string[] then
+                     will be written to stdin and closed. Defaults to `false`.
+                   • stdout: (boolean|function) Handle output from stdout.
+                     When passed as a function must have the signature
+                     `fun(err: string, data: string)`. Defaults to `true`
+                   • stderr: (boolean|function) Handle output from stdout.
+                     When passed as a function must have the signature
+                     `fun(err: string, data: string)`. Defaults to `true`.
+                   • text: (boolean) Handle stdout and stderr as text.
+                     Replaces `\r\n` with `\n`.
+                   • timeout: (integer)
+                   • detach: (boolean) If true, spawn the child process in a
+                     detached state - this will make it a process group
+                     leader, and will effectively enable the child to keep
+                     running after the parent exits. Note that the child
+                     process will still keep the parent's event loop alive
+                     unless the parent process calls |uv.unref()| on the
+                     child's process handle.
+      • {on_exit}  (function|nil) Called when subprocess exits. When provided,
+                   the command runs asynchronously. Receives SystemCompleted
+                   object, see return of SystemObj:wait().
+
+    Return: ~
+        SystemObj Object with the fields:
+        • pid (integer) Process ID
+        • wait (fun(timeout: integer|nil): SystemCompleted)
+          • SystemCompleted is an object with the fields:
+            • code: (integer)
+            • signal: (integer)
+            • stdout: (string), nil if stdout argument is passed
+            • stderr: (string), nil if stderr argument is passed
+
+        • kill (fun(signal: integer))
+        • write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to
+          close the stream.
+        • is_closing (fun(): boolean)
+
 
 ==============================================================================
 Lua module: inspector                                          *lua-inspector*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index af5263bcf5..4afb3429f4 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -76,6 +76,8 @@ The following new APIs or features were added.
   is resized horizontally). Note: Lines that are not visible and kept in
   |'scrollback'| are not reflown.
 
+• |vim.system()| for running system commands.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*