Lua: add new module `pandoc.image`

The module provides basic querying functions for image properties.

3 files changed, 131 insertions, 0 deletions

diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Init.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Init.hs
index 2900fea27..0ea04b635 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Init.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Init.hs
@@ -41,6 +41,7 @@ import qualified HsLua.Module.Path as Module.Path
 import qualified HsLua.Module.Zip as Module.Zip
 import qualified Text.Pandoc.Lua.Module.CLI as Pandoc.CLI
 import qualified Text.Pandoc.Lua.Module.Format as Pandoc.Format
+import qualified Text.Pandoc.Lua.Module.Image as Pandoc.Image
 import qualified Text.Pandoc.Lua.Module.JSON as Pandoc.JSON
 import qualified Text.Pandoc.Lua.Module.MediaBag as Pandoc.MediaBag
 import qualified Text.Pandoc.Lua.Module.Pandoc as Module.Pandoc
@@ -91,6 +92,7 @@ loadedModules :: [Module PandocError]
 loadedModules =
   [ Pandoc.CLI.documentedModule
   , Pandoc.Format.documentedModule
+  , Pandoc.Image.documentedModule
   , Pandoc.JSON.documentedModule
   , Pandoc.MediaBag.documentedModule
   , Pandoc.Scaffolding.documentedModule
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/ImageSize.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/ImageSize.hs
new file mode 100644
index 000000000..e56b5cd25
--- /dev/null
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/ImageSize.hs
@@ -0,0 +1,31 @@
+{-# LANGUAGE LambdaCase           #-}
+{-# LANGUAGE OverloadedStrings    #-}
+{- |
+   Module      : Text.Pandoc.Lua.Marshal.ImageSize
+   Copyright   : © 2024 Albert Krewinkel
+   License     : GPL-2.0-or-later
+   Maintainer  : Albert Krewinkel <[email protected]>
+
+Marshaling image properties.
+-}
+module Text.Pandoc.Lua.Marshal.ImageSize
+  ( pushImageType
+  , pushImageSize
+  ) where
+
+import Data.Char (toLower)
+import HsLua
+import Text.Pandoc.ImageSize
+
+-- | Pushes an 'ImageType' as a string value.
+pushImageType :: LuaError e => Pusher e ImageType
+pushImageType = pushString . map toLower . show
+
+-- | Pushes a dimensional value.
+pushImageSize :: LuaError e => Pusher e ImageSize
+pushImageSize = pushAsTable
+  [ ("width", pushIntegral . pxX)
+  , ("height", pushIntegral . pxY)
+  , ("dpi_horz", pushIntegral . dpiX)
+  , ("dpi_vert", pushIntegral . dpiY)
+  ]
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Image.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Image.hs
new file mode 100644
index 000000000..3b2465ccc
--- /dev/null
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Image.hs
@@ -0,0 +1,98 @@
+{-# LANGUAGE OverloadedStrings #-}
+{-|
+Module      : Text.Pandoc.Lua.Module.Image
+Copyright   : © 2024 Albert Krewinkel
+License     : MIT
+Maintainer  : Albert Krewinkel <[email protected]>
+
+Lua module for basic image operations.
+-}
+module Text.Pandoc.Lua.Module.Image (
+  -- * Module
+    documentedModule
+
+  -- ** Functions
+  , size
+  , format
+  )
+where
+
+import Prelude hiding (null)
+import Data.Default (Default (def))
+import Data.Maybe (fromMaybe)
+import Data.Version (makeVersion)
+import HsLua.Core
+import HsLua.Marshalling
+import HsLua.Packaging
+import Text.Pandoc.Error (PandocError)
+import Text.Pandoc.ImageSize (imageType, imageSize)
+import Text.Pandoc.Lua.PandocLua ()
+import Text.Pandoc.Lua.Marshal.ImageSize (pushImageType, pushImageSize)
+import Text.Pandoc.Lua.Marshal.WriterOptions (peekWriterOptions)
+
+import qualified Data.Text as T
+
+-- | The @pandoc.image@ module specification.
+documentedModule :: Module PandocError
+documentedModule = Module
+  { moduleName = "pandoc.image"
+  , moduleDescription = "Basic image querying functions."
+  , moduleFields = fields
+  , moduleFunctions = functions
+  , moduleOperations = []
+  , moduleTypeInitializers = []
+  }
+
+--
+-- Fields
+--
+
+-- | Exported fields.
+fields :: LuaError e => [Field e]
+fields = []
+
+--
+-- Functions
+--
+
+functions :: [DocumentedFunction PandocError]
+functions =
+  [ size `since` makeVersion [3, 1, 13]
+  , format `since` makeVersion [3, 1, 13]
+  ]
+
+-- | Find the size of an image.
+size :: DocumentedFunction PandocError
+size = defun "size"
+  ### liftPure2 (\img mwriterOpts -> imageSize (fromMaybe def mwriterOpts) img)
+  <#> parameter peekByteString "string" "image" "image data"
+  <#> opt (parameter peekWriterOptions "WriterOptions|table" "opts"
+           "writer options")
+  =#> functionResult (either (failLua . T.unpack) pushImageSize) "table"
+        "image size information or error message"
+  #? T.unlines
+     [ "Returns a table containing the size and resolution of an image;"
+     , "throws an error if the given string is not an image, or if the size"
+     , "of the image cannot be determined."
+     , ""
+     , "The resulting table has four entires: *width*, *height*, *dpi\\_horz*,"
+     , "and *dpi\\_vert*."
+     , ""
+     , "The `opts` parameter, when given, should be either a WriterOptions"
+     , "object such as `PANDOC_WRITER_OPTIONS`, or a table with a `dpi` entry."
+     , "It affects the calculation for vector image formats such as SVG."
+     ]
+
+-- | Returns the format of an image.
+format :: LuaError e => DocumentedFunction e
+format = defun "format"
+  ### liftPure imageType
+  <#> parameter peekByteString "string" "image" "binary image data"
+  =#> functionResult (maybe pushnil pushImageType) "string|nil"
+        "image format, or nil if the format cannot be determined"
+  #? T.unlines
+     [ "Returns the format of an image as a lowercase string."
+     , ""
+     , "Formats recognized by pandoc include *png*, *gif*, *tiff*, *jpeg*,"
+     , "*pdf*, *svg*, *eps*, and *emf*."
+     ]