feat: add vim.tbl_get (#17831)

vim.tbl_get takes a table with subsequent string arguments (variadic) that
index into the table. If the value pointed to by the set of keys exists,
the function returns the value. If the set of keys does not exist, the
function returns nil.

1 files changed, 16 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bd821c4f9e..21f44ce02e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1634,6 +1634,22 @@ tbl_flatten({t})                                           *vim.tbl_flatten()*
                 See also: ~
                     From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
+tbl_get({o}, {...})                                            *vim.tbl_get()*
+                Index into a table (first argument) via string keys passed as
+                subsequent arguments. Return `nil` if the key does not exist. Examples: >
+
+                  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
+                  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
+<
+
+                Parameters: ~
+                    {o}    Table to index
+                    {...}  Optional strings (0 or more, variadic) via which to
+                           index the table
+
+                Return: ~
+                    nested value indexed by key if it exists, else nil
+
 tbl_isempty({t})                                           *vim.tbl_isempty()*
                 Checks if a table is empty.