Adding some functions to work with Lua tables.

ci/generate-docs.py

@@ -382,6 +382,10 @@ def render(self, output, depth=0, mode="mdbook"):
                 "module: wezterm.color",
                 "config/lua/wezterm.color",
             ),
+            Gen(
+                "module: wezterm.table",
+                "config/lua/wezterm.table",
+            ),
             Gen(
                 "module: wezterm.gui",
                 "config/lua/wezterm.gui",

docs/config/lua/wezterm.table/clone.md

@@ -0,0 +1,20 @@
+# `wezterm.table.clone(table)`
+
+{{since('nightly')}}
+
+This function clones the Lua table (or array) passed to it.
+
+```lua
+local wezterm = require 'wezterm'
+local clone = wezterm.table.clone
+
+local tbl1 = {
+  a = 1,
+  b = '2',
+}
+
+local tbl2 = clone(tbl1)
+
+assert(tbl1 == tbl2)
+```
+

docs/config/lua/wezterm.table/flatten.md

@@ -0,0 +1,20 @@
+# `wezterm.table.flatten(array_of_arrays)`
+
+{{since('nightly')}}
+
+This function recursively flattens Lua arrays passed to it in the form of an array.
+I.e., to flatten the Lua arrays `arr1` and `arr2` into one array,
+we can pass them to the function as `{ arr1, arr2 }`. (See below.)
+
+```lua
+local wezterm = require 'wezterm'
+local flatten = wezterm.table.flatten
+
+local arr1 = { { 1, 2 }, 3 }
+
+local arr2 = { 'a', { 'b', { 'c' } } }
+
+assert(flatten { arr1, arr2 } == { 1, 2, 3, 'a', 'b', 'c' })
+```
+
+See also [merge](merge.md).

docs/config/lua/wezterm.table/has_key.md

@@ -0,0 +1,24 @@
+# `wezterm.table.has_key(table, key)`
+
+{{since('nightly')}}
+
+This function accepts a Lua table (or array) `table` and a key `key`.
+It returns `true` if `table` contains a key equal to `key` (with non-nill value)
+and false otherwise.
+
+```lua
+local wezterm = require 'wezterm'
+local has_key = wezterm.table.has_key
+
+local tbl1 = {
+  a = 1,
+  b = '2',
+}
+local arr1 = { 'a', 'b', 'c' }
+
+assert(has_key(tbl1, 'a'))
+assert(not has_key(tbl1, 'c'))
+
+assert(has_key(arr1, 3))
+assert(not has_key(arr1, 4))
+```

docs/config/lua/wezterm.table/has_value.md

@@ -0,0 +1,24 @@
+# `wezterm.table.has_value(table, value)`
+
+{{since('nightly')}}
+
+This function accepts a Lua table (or array) `table` and a value `value`.
+It returns `true` if `table` contains an entry with value equal to `value`
+and false otherwise.
+
+```lua
+local wezterm = require 'wezterm'
+local has_value = wezterm.table.has_value
+
+local tbl1 = {
+  a = 1,
+  b = '2',
+}
+local arr1 = { 'a', 'b', 'c' }
+
+assert(has_value(tbl1, 1))
+assert(not has_value(tbl1, 'a'))
+
+assert(has_value(arr1, 'a'))
+assert(not has_value(arr1, '1'))
+```

docs/config/lua/wezterm.table/index.markdown

@@ -0,0 +1,7 @@
+# `wezterm.table` module
+
+{{since('nightly')}}
+
+The `wezterm.table` module exposes functions that work with Lua tables and arrays.
+
+## Available functions

docs/config/lua/wezterm.table/index.md

@@ -0,0 +1,17 @@
+# `wezterm.table` module
+
+{{since('nightly')}}
+
+The `wezterm.table` module exposes functions that work with Lua tables and arrays.
+
+## Available functions
+
+
+  - [clone](clone.md)
+  - [flatten](flatten.md)
+  - [has_key](has_key.md)
+  - [has_value](has_value.md)
+  - [length](length.md)
+  - [merge](merge.md)
+  - [to_string](to_string.md)
+  - [to_string_fallback](to_string_fallback.md)

docs/config/lua/wezterm.table/length.md

@@ -0,0 +1,26 @@
+# `wezterm.table.length(table)`
+
+{{since('nightly')}}
+
+This function returns the length of a Lua table (or array) passed to it.
+
+Note: The Lua function `#` also returns the length of an array, but
+`#` only works for arrays and not tables (with non-integer keys).
+
+```lua
+local wezterm = require 'wezterm'
+local length = wezterm.table.length
+
+local tbl1 = {
+  a = 1,
+  b = '2',
+}
+local arr1 = { 1, 'a', 2, 'abc' }
+
+assert(2 == length(tbl1))
+assert(4 == length(arr1))
+
+assert(0 == #tbl1)
+assert(4 == #arr1)
+```
+

docs/config/lua/wezterm.table/merge.md

@@ -0,0 +1,36 @@
+# `wezterm.table.merge(array_of_tables [, keep_first])`
+
+{{since('nightly')}}
+
+This function merges Lua tables passed to it in the form of an array.
+I.e., to merge the Lua tables `tbl1` and `tbl2`, we can pass them to
+the function as `{ tbl1, tbl2 }`. (See below.)
+
+By default this function merges tables with identical keys by taking
+the value from the last table in the array with each given key.
+
+The optional `keep_first` allows us to instead prefer values from the
+first table in the array where we see the key by passing `true` after the array.
+The default behavior is identical to what we get by passing `false`.
+
+```lua
+local wezterm = require 'wezterm'
+local merge = wezterm.table.merge
+
+local tbl1 = {
+  a = 1,
+  b = '2',
+}
+
+local tbl2 = {
+  a = '1',
+  c = 3,
+}
+
+wezterm.log_error(merge { tbl1, tbl2 })
+assert(merge { tbl1, tbl2 } == merge({ tbl1, tbl2 }, false))
+
+wezterm.log_error(merge({ tbl1, tbl2 }, true))
+```
+
+See also [flatten](flatten.md).

docs/config/lua/wezterm.table/to_string.md

@@ -0,0 +1,66 @@
+# `wezterm.table.to_string(table [, indent [, skip_outer_bracket]])`
+
+{{since('nightly')}}
+
+This function takes a Lua table and returns a string with the data of
+the table. E.g., passing in the table `{ a=1, b=2 }` the function
+will return the string:
+```
+{
+  a = 1,
+  b = 2,
+}
+```
+
+*Note:* This function is not careful about checking for recursive tables, so it can't
+be used to print e.g. `_G`. To print a recursive (or in general a very big) table,
+it is recommended that you use [to_string_fallback](to_string_fallback.md).
+
+By default this function constructs the string with 2 spaces for indentation.
+
+The optional `indent` allows us to instead prefer other (non-negative) integer values
+of spaces for the indentation.
+
+```lua
+local wezterm = require 'wezterm'
+local tbl_to_string = wezterm.table.to_string
+
+local tbl1 = {
+  a = 1,
+  {
+    b = 2,
+  },
+}
+local str1 = [[{
+    a = 1,
+    {
+        b = 2,
+    },
+}]]
+
+assert(str1 == tbl_to_string(tbl1, 4))
+```
+
+The optional `skip_outer_bracket` (which can only be used together with `indent`) is
+a boolean, which defaults to `false`. If you set it to `true`, the outer brackets are
+not included in the string (and thus everything is `indent` fewer spaces indented too).
+
+```lua
+local wezterm = require 'wezterm'
+local tbl_to_string = wezterm.table.to_string
+
+local tbl1 = {
+  a = 1,
+  {
+    b = 2,
+  },
+}
+local str1 = [[a = 1,
+{
+b = 2,
+},]]
+
+assert(str1 == tbl_to_string(tbl1, 0, true))
+```
+
+See also [to_string_fallback](to_string_fallback.md).

docs/config/lua/wezterm.table/to_string_fallback.md

@@ -0,0 +1,37 @@
+# `wezterm.table.to_string_fallback(table)`
+
+{{since('nightly')}}
+
+This function takes a Lua table and returns a string with the data of
+the table. E.g., passing in the table `{ a=1, b=2 }` the function
+will return the string:
+```
+{
+  ["a"] = 1,
+  ["b"] = 2,
+}
+```
+
+For nested tables, this function always prints a label (even for arrays).
+This can make the string look different than you might expect.
+```lua
+local wezterm = require 'wezterm'
+local tbl_to_string_fb = wezterm.table.to_string_fallback
+
+local tbl1 = {
+  a = 1,
+  {
+    b = 2,
+  },
+}
+local str1 = [[{
+  [1] = {
+    ["b"] = 2,
+  },
+  ["a"] = 1,
+}]]
+
+assert(str1 == tbl_to_string_fb(tbl1))
+```
+
+See also [to_string](to_string.md).

env-bootstrap/Cargo.toml

@@ -30,6 +30,7 @@ ssh-funcs = { path = "../lua-api-crates/ssh-funcs" }
 spawn-funcs = { path = "../lua-api-crates/spawn-funcs" }
 time-funcs = { path = "../lua-api-crates/time-funcs" }
 url-funcs = { path = "../lua-api-crates/url-funcs" }
+table-funcs = { path = "../lua-api-crates/table-funcs" }
 wezterm-version = { path = "../wezterm-version" }
 
 [target."cfg(windows)".dependencies]

env-bootstrap/src/lib.rs

@@ -206,6 +206,7 @@ fn register_lua_modules() {
         share_data::register,
         time_funcs::register,
         url_funcs::register,
+        table_funcs::register,
     ] {
         config::lua::add_context_setup_func(func);
     }

lua-api-crates/table-funcs/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "table-funcs"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+anyhow = "1.0"
+config = { path = "../../config" }
+luahelper = { path = "../../luahelper" }