Lua filters: test AST object equality via Haskell

Equality of Lua objects representing pandoc AST elements is tested by
unmarshalling the objects and comparing the result in Haskell. A new
function `equals` which performs this test has been added to the
`pandoc.utils` module.

Closes: #5092

1 files changed, 47 insertions, 1 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 57eb4e79c..b0d1884e8 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -171,7 +171,7 @@ variables.
 :   The name used to involve the filter. This value can be used
     to find files relative to the script file. This variable is
     also set in custom writers.
-    
+
 `PANDOC_STATE`
 :   The state shared by all readers and writers. It is used by
     pandoc to collect and pass information. The value of this
@@ -641,6 +641,9 @@ to create these objects.
 
 Pandoc document
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 `blocks`
 :   document content ([List] of [Block]s)
 
@@ -653,10 +656,16 @@ Pandoc document
 Meta information on a document; string-indexed collection of
 [MetaValue]s.
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 ## MetaValue {#type-ref-MetaValue}
 
 Document meta information items.
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 ### MetaBlocks {#type-ref-MetaBlocks}
 
 A list of blocks usable as meta value ([List] of [Block]s)
@@ -707,6 +716,9 @@ Plain Lua string value (string)
 
 ## Block {#type-ref-Block}
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 ### BlockQuote {#type-ref-BlockQuote}
 
 A block quote element
@@ -926,6 +938,9 @@ centered).
 
 ## Inline {#type-ref-Inline}
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 ### Cite {#type-ref-Cite}
 Citation
 
@@ -1166,6 +1181,9 @@ Superscripted text
 
 A set of element attributes
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 `identifier`
 :   element identifier (string)
 
@@ -1184,6 +1202,9 @@ indices to the list table.
 
 Single citation entry
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 `id`
 :   citation identifier, e.g., a bibtex key (string)
 
@@ -1206,6 +1227,9 @@ Single citation entry
 ### ListAttributes {#type-ref-ListAttributes}
 List attributes
 
+Object equality is determined via
+[`pandoc.utils.equals`](#utils-equals).
+
 `start`
 :   number of the first list item (integer)
 
@@ -2202,6 +2226,28 @@ functions.
         --   pandoc.Emph{ pandoc.Str 'Paragraph2' }
         -- }
 
+[`equals (element1, element2)`]{#utils-equals}
+
+:   Test equality of AST elements. Elements in Lua are considered
+    equal if and only if the objects obtained by unmarshaling are
+    equal.
+
+    Parameters:
+
+    `element1`, `element2`:
+    :   Objects to be compared. Acceptable input types are
+        [Pandoc](#type-ref-pandoc), [Meta](#type-ref-meta),
+        [MetaValue](#type-ref-MetaValue),
+        [Block](#type-ref-Block), [Inline](#type-ref-Inline),
+        [Attr](#type-ref-Attr),
+        [ListAttributes](#type-ref-ListAttributes), and
+        [Citation](#type-ref-Citation).
+
+    Returns:
+
+    -   Whether the two objects represent the same element
+        (boolean)
+
 [`hierarchicalize (blocks)`]{#utils-hierarchicalize}
 
 :   Convert list of blocks into an hierarchical list. An