gears.debug: add support for limited depth

This is useful with big tables and might even be necessary to prevent
infinite recursion.

To prevent the latter, the default is 10.

This adds an indicator when `depth` is reached for tables.

    awesome# return require("gears").debug.dump_return(t4, "", 2)
       string " : table: 0x1580130
      1 : table: 0x16951d0
        1 : wibox.widget.base (table) […]
        2 : wibox.widget.base (table) […]
        3 : 4 (number)
        4 : 5 (number)
        5 : foo (string)
      2 : table: 0x16ac790
        1 : table: 0x16951d0 (table) […]
      3 : table: 0x16cc500
        1 : table: 0x16951d0 (table) […]
        2 : table: 0x16ac790 (table) […]"

    awesome# return require("gears").debug.dump_return(t4, "", 1)
       string " : table: 0x1580130
      1 : table: 0x16951d0 (table) […]
      2 : table: 0x16ac790 (table) […]
      3 : table: 0x16cc500 (table) […]"

Closes https://github.com/awesomeWM/awesome/pull/372.

lib/gears/debug.lua

@@ -26,27 +26,33 @@ function debug.assert(cond, message)
 end
 
 --- Given a table (or any other data) return a string that contains its
--- tag, value and type. If data is a table then recursively call d_raw
+-- tag, value and type. If data is a table then recursively call `dump_raw`
 -- on each of its values.
 -- @param data Value to inspect.
 -- @param shift Spaces to indent lines with.
 -- @param tag The name of the value.
+-- @tparam[opt=10] int depth Depth of recursion.
 -- @return a string which contains tag, value, value type and table key/value
 -- pairs if data is a table.
-local function dump_raw(data, shift, tag)
+local function dump_raw(data, shift, tag, depth)
+    depth = depth == nil and 10 or depth or 0
     local result = ""
 
     if tag then
         result = result .. tostring(tag) .. " : "
     end
 
-    if type(data) ~= "table" then
-        return result .. tostring(data) .. " (" .. type(data) .. ")"
-    end
-
-    shift = (shift or "") .. "  "
-    for k, v in pairs(data) do
-        result = result .. "\n" .. shift .. dump_raw(v, shift, k)
+    if type(data) == "table" and depth > 0 then
+        shift = (shift or "") .. "  "
+        result = result .. tostring(data)
+        for k, v in pairs(data) do
+            result = result .. "\n" .. shift .. dump_raw(v, shift, k, depth - 1)
+        end
+    else
+        result = result .. tostring(data) .. " (" .. type(data) .. ")"
+        if depth == 0 and type(data) == "table" then
+            result = result .. " […]"
+        end
     end
 
     return result
@@ -55,16 +61,18 @@ end
 --- Inspect the value in data.
 -- @param data Value to inspect.
 -- @param tag The name of the value.
--- @return a string that contains the expanded value of data.
-function debug.dump_return(data, tag)
-    return dump_raw(data, nil, tag)
+-- @tparam[opt] int depth Depth of recursion.
+-- @return string A string that contains the expanded value of data.
+function debug.dump_return(data, tag, depth)
+    return dump_raw(data, nil, tag, depth)
 end
 
 --- Print the table (or any other value) to the console.
 -- @param data Table to print.
 -- @param tag The name of the table.
-function debug.dump(data, tag)
-    print(debug.dump_return(data, tag))
+-- @tparam[opt] int depth Depth of recursion.
+function debug.dump(data, tag, depth)
+    print(debug.dump_return(data, tag, depth))
 end
 
 return debug