Lua: add function pandoc.mediabag.fill (#8104)

The function allows to fill the mediabag with all images in a given
document. Images that cannot be fetched are replaced with a Span
containing the image description.

doc/lua-filters.md

@@ -3791,6 +3791,26 @@ Parameters:
 
 Clear-out the media bag, deleting all items.
 
+### fill {#pandoc.mediabag.fill}
+
+`fill (doc)`
+
+Fills the mediabag with the images in the given document. An
+image that cannot be retrieved will be replaced with a Span of
+class "image" that contains the image description.
+
+Images for which the mediabag already contains an item will
+not be processed again.
+
+Parameters:
+
+`doc`
+:   document from which to fill the mediabag ([Pandoc](#type-pandoc))
+
+Returns:
+
+-   modified document ([Pandoc](#type-pandoc))
+
 ### insert {#pandoc.mediabag.insert}
 
 `insert (filepath, mime_type, contents)`

src/Text/Pandoc/Lua/Module/MediaBag.hs

@@ -15,12 +15,13 @@ module Text.Pandoc.Lua.Module.MediaBag
 import Prelude hiding (lookup)
 import Data.Maybe (fromMaybe)
 import HsLua ( LuaE, DocumentedFunction, Module (..)
-             , (<#>), (###), (=#>), (=?>), defun, functionResult
+             , (<#>), (###), (=#>), (=?>), (#?), defun, functionResult
              , opt, parameter, stringParam, textParam)
 import Text.Pandoc.Class.CommonState (CommonState (..))
-import Text.Pandoc.Class.PandocMonad (fetchItem, getMediaBag, modifyCommonState,
-                                      setMediaBag)
+import Text.Pandoc.Class.PandocMonad (fetchItem, fillMediaBag, getMediaBag,
+                                      modifyCommonState, setMediaBag)
 import Text.Pandoc.Error (PandocError)
+import Text.Pandoc.Lua.Marshal.Pandoc (peekPandoc, pushPandoc)
 import Text.Pandoc.Lua.Marshal.List (pushPandocList)
 import Text.Pandoc.Lua.Orphans ()
 import Text.Pandoc.Lua.PandocLua (unPandocLua)
@@ -42,6 +43,7 @@ documentedModule = Module
       [ delete
       , empty
       , fetch
+      , fill
       , insert
       , items
       , list
@@ -65,6 +67,21 @@ empty = defun "empty"
   ### unPandocLua (modifyCommonState (\st -> st { stMediaBag = mempty }))
   =#> []
 
+-- | Fill the mediabag with all images in the document that aren't
+-- present yet.
+fill :: DocumentedFunction PandocError
+fill = defun "fill"
+  ### unPandocLua . fillMediaBag
+  <#> parameter peekPandoc "Pandoc" "doc"
+        "document from which to fill the mediabag"
+  =#> functionResult pushPandoc "Pandoc" "modified document"
+  #? ("Fills the mediabag with the images in the given document.\n" <>
+      "An image that cannot be retrieved will be replaced with a Span\n" <>
+      "of class \"image\" that contains the image description.\n" <>
+      "" <>
+      "Images for which the mediabag already contains an item will\n" <>
+      "not be processed again.")
+
 -- | Insert a new item into the media bag.
 insert :: DocumentedFunction PandocError
 insert = defun "insert"