Custom writer: give full access to doc in optional Setup function (#4967)

Custom writers can specify an optional `Setup` function. The function
takes the full Pandoc document as input and should not return any value.
Users can use this function to configure the writer depending on the
given document's content or its metadata.

data/sample.lua: add sample use of Setup function.
The change allows to control the image format used to encode the image
produced from dot code.

Closes #4957

1 files changed, 16 insertions, 1 deletions

diff --git a/src/Text/Pandoc/Writers/Custom.hs b/src/Text/Pandoc/Writers/Custom.hs
index 37fec9f0f..a5b0ed169 100644
--- a/src/Text/Pandoc/Writers/Custom.hs
+++ b/src/Text/Pandoc/Writers/Custom.hs
@@ -116,7 +116,7 @@ writeCustom luaFile opts doc@(Pandoc meta _) = do
     -- to handle this more gracefully):
     when (stat /= Lua.OK) $
       Lua.tostring' (-1) >>= throw . PandocLuaException . UTF8.toString
-    -- TODO - call hierarchicalize, so we have that info
+    runSetup doc
     rendered <- docToCustom opts doc
     context <- metaToJSON opts
                blockListToCustom
@@ -133,6 +133,21 @@ writeCustom luaFile opts doc@(Pandoc meta _) = do
               Left e  -> throw (PandocTemplateError e)
               Right r -> return (pack r)
 
+-- | Try to call a setup function. The function, if it exists, is passed the
+-- full pandoc document as parameter. This allows users to setup the writer
+-- depending on the content of the document. Accessing information on the
+-- document hierarchy is possible via the `pandoc.utils.hierarchicalize`
+-- function.
+runSetup :: Pandoc -> Lua ()
+runSetup doc = do
+  Lua.getglobal "Setup"
+  setup <- Lua.ltype Lua.stackTop
+  if setup /= Lua.TypeFunction
+    then Lua.pop 1
+    else do
+      Lua.push doc
+      Lua.call 1 0
+
 docToCustom :: WriterOptions -> Pandoc -> Lua String
 docToCustom opts (Pandoc (Meta metamap) blocks) = do
   body <- blockListToCustom blocks