From d7cab5198269fbbdbc40f54a2ad7aeb83fee619f Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert@zeitkraut.de>
Date: Tue, 21 Dec 2021 09:40:23 +0100
Subject: Lua: add new library function `pandoc.utils.type`.

The function behaves like the default `type` function from Lua's
standard library, but is aware of pandoc userdata types. A typical
use-case would be to determine the type of a metadata value.
---
 doc/lua-filters.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 901fd6be8..e5ea90104 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -1863,7 +1863,8 @@ Fields:
 Column alignment and width specification for a single table
 column.
 
-This is a pair with the following components:
+This is a pair, i.e., a plain table, with the following
+components:
 
 1. cell alignment ([Alignment]).
 2. table column width, as a fraction of the total table width
@@ -3507,6 +3508,39 @@ Usage:
     -- create normal table block again
     table = pandoc.utils.from_simple_table(simple)
 
+### type {#pandoc.utils.type}
+
+`type (value)`
+
+Pandoc-friendly version of Lua's default `type` function,
+returning the type of a value. This function works with all types
+listed in section [Lua type reference][], except if noted
+otherwise.
+
+The function works by checking the metafield `__name`. If the
+argument has a string-valued metafield `__name`, then it returns
+that string. Otherwise it behaves just like the normal `type`
+function.
+
+Parameters:
+
+`value`
+:   any Lua value
+
+Returns:
+
+-   type of the given value (string)
+
+Usage:
+
+    -- Prints one of 'string', 'boolean', 'Inlines', 'Blocks',
+    -- 'table', and 'nil', corresponding to the Haskell constructors
+    -- MetaString, MetaBool, MetaInlines, MetaBlocks, MetaMap,
+    -- and an unset value, respectively.
+    function Meta (meta)
+      print('type of metavalue `author`:', pandoc.utils.type(meta.author))
+    end
+
 # Module pandoc.mediabag
 
 The `pandoc.mediabag` module allows accessing pandoc's media
-- 
cgit v1.2.3