awful.spawn: add easy_async_with_shell and fixed easy_async doc (#1541)

lib/awful/spawn.lua

@@ -323,14 +323,14 @@ end
 --- Asynchronously spawn a program and capture its output.
 -- (wraps `spawn.with_line_callback`).
 -- @tparam string|table cmd The command.
--- @tab callback Function with the following arguments
+-- @function callback Function with the following arguments:
--- @tparam string callback.stdout Output on stdout.
+--   @tparam string callback.stdout Output on stdout.
--- @tparam string callback.stderr Output on stderr.
+--   @tparam string callback.stderr Output on stderr.
--- @tparam string callback.exitreason Exit Reason.
+--   @tparam string callback.exitreason Exit Reason.
--- The reason can be "exit" or "signal".
+--   @tparam integer callback.exitcode Exit code.
--- @tparam integer callback.exitcode Exit code.
+--   The exitreason argument can either be "exit" or "signal".
--- For "exit" reason it's the exit code.
+--   For "exit" reason it's the exit code.
--- For "signal" reason — the signal causing process termination.
+--   For "signal" reason it's the signal causing process termination.
 -- @treturn[1] Integer the PID of the forked process.
 -- @treturn[2] string Error message.
 -- @see spawn.with_line_callback
@@ -372,6 +372,24 @@ function spawn.easy_async(cmd, callback)
     })
 end
 
+--- Call spawn.easy_async with a shell.
+-- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`).
+-- @tparam string|table cmd The command.
+-- @function callback Function with the following arguments:
+--   @tparam string callback.stdout Output on stdout.
+--   @tparam string callback.stderr Output on stderr.
+--   @tparam string callback.exitreason Exit Reason.
+--   @tparam integer callback.exitcode Exit code.
+--   The exitreason argument can either be "exit" or "signal".
+--   For "exit" reason it's the exit code.
+--   For "signal" reason it's the signal causing process termination.
+-- @treturn[1] Integer the PID of the forked process.
+-- @treturn[2] string Error message.
+-- @see spawn.with_line_callback
+function spawn.easy_async_with_shell(cmd, callback)
+    return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback)
+end
+
 --- Read lines from a Gio input stream
 -- @tparam Gio.InputStream input_stream The input stream to read from.
 -- @tparam function line_callback Function that is called with each line

tests/test-spawn.lua

@@ -4,6 +4,7 @@ local runner = require("_runner")
 local spawn = require("awful.spawn")
 
 local spawns_done = 0
+local async_spawns_done = 0
 local exit_yay, exit_snd = nil, nil
 
 -- * Using spawn with array is already covered by the test client.
@@ -40,6 +41,16 @@ local steps = {
 
     function(count)
         if count == 1 then
+            spawn.easy_async("echo yay", function(stdout)
+                if stdout:match("yay") then
+                    async_spawns_done = async_spawns_done + 1
+                end
+            end)
+            spawn.easy_async_with_shell("true && echo yay", function(stdout)
+                if stdout:match("yay") then
+                    async_spawns_done = async_spawns_done + 1
+                end
+            end)
             local steps_yay = 0
             spawn.with_line_callback("echo yay", {
                                      stdout = function(line)
@@ -90,9 +101,10 @@ local steps = {
         if spawns_done == 2 then
             assert(exit_yay == 0)
             assert(exit_snd == 42)
+            assert(async_spawns_done == 2)
             return true
         end
-    end,
+    end
 }
 
 runner.run_steps(steps)