T.P.Scripting: Refactor the scripting engine.

The new type CustomComponents is exported from T.P.Scripting, and the
ScriptEngine fields are changed. Instead of separate fields for custom
readers and writers, we now have a single function that loads any number
of "components" from a script: these may be custom readers, custom
writers, templates for writers, or extension configs. (Note: it's
possible to have a custom reader and a custom writer for a format
together in the same file.)

Pandoc now checks the folder `custom` in the user's data directory for a
matching script if it can't find one in the local directory. Previously,
the `readers` and `writers` data directories were search for custom
readers and writers, respectively. Scripts in those directories must be
moved to the `custom` folder.

Custom readers used to implement a fallback behavior that allowed to
consume just a string value as input to the `Reader` function. This has
been removed, the first argument is now always a list of sources. Use
`tostring` on that argument to get a string.

Closes #8417.

Signed-off-by: Albert Krewinkel <albert@zeitkraut.de>

4 files changed, 41 insertions, 23 deletions

diff --git a/src/Text/Pandoc/App.hs b/src/Text/Pandoc/App.hs
index 3e2ad6950..30a0c7530 100644
--- a/src/Text/Pandoc/App.hs
+++ b/src/Text/Pandoc/App.hs
@@ -61,7 +61,7 @@ import Text.Pandoc.Filter (Filter (JSONFilter, LuaFilter), Environment (..),
                            applyFilters)
 import qualified Text.Pandoc.Format as Format
 import Text.Pandoc.PDF (makePDF)
-import Text.Pandoc.Scripting (ScriptingEngine (..))
+import Text.Pandoc.Scripting (ScriptingEngine (..), CustomComponents(..))
 import Text.Pandoc.SelfContained (makeSelfContained)
 import Text.Pandoc.Shared (eastAsianLineBreakFilter,
          headerShift, filterIpynbOutput, tshow)
@@ -161,8 +161,13 @@ convertWithOpts' scriptingEngine istty datadir opts = do
     if ".lua" `T.isSuffixOf` readerName
        then do
             let scriptPath = T.unpack readerNameBase
-            (r, extsConf) <- engineReadCustom scriptingEngine scriptPath
-            rexts         <- Format.applyExtensionsDiff extsConf flvrd
+            components <- engineLoadCustom scriptingEngine scriptPath
+            r <- case customReader components of
+                   Nothing -> throwError $ PandocAppError $
+                               readerName <> " does not contain a custom reader"
+                   Just r -> return r
+            let extsConf = fromMaybe mempty (customExtensions components)
+            rexts <- Format.applyExtensionsDiff extsConf flvrd
             return (r, rexts)
        else if optSandbox opts
                then case runPure (getReader flvrd) of
diff --git a/src/Text/Pandoc/App/CommandLineOptions.hs b/src/Text/Pandoc/App/CommandLineOptions.hs
index a65fe5a04..30b5693fd 100644
--- a/src/Text/Pandoc/App/CommandLineOptions.hs
+++ b/src/Text/Pandoc/App/CommandLineOptions.hs
@@ -51,7 +51,7 @@ import Text.Pandoc.App.Opt (Opt (..), LineEnding (..), IpynbOutput (..),
                             fullDefaultsPath, OptInfo(..))
 import Text.Pandoc.Filter (Filter (..))
 import Text.Pandoc.Highlighting (highlightingStyles, lookupHighlightingStyle)
-import Text.Pandoc.Scripting (ScriptingEngine (..))
+import Text.Pandoc.Scripting (ScriptingEngine (..), customTemplate)
 import Text.Pandoc.Shared (safeStrRead)
 import Text.Printf
 import qualified Control.Exception as E
@@ -161,8 +161,8 @@ handleOptInfo engine info = E.handle (handleError . Left) $ do
                       getDefaultTemplate fmt
                     _ -> do
                       -- format looks like a filepath => custom writer
-                      (_, _, mt) <- engineWriteCustom engine (T.unpack fmt)
-                      case mt of
+                      components <- engineLoadCustom engine (T.unpack fmt)
+                      case customTemplate components of
                         Just t  -> pure t
                         Nothing -> E.throw $ PandocNoTemplateError fmt
       case templ of
diff --git a/src/Text/Pandoc/App/OutputSettings.hs b/src/Text/Pandoc/App/OutputSettings.hs
index 8782f56c4..928978450 100644
--- a/src/Text/Pandoc/App/OutputSettings.hs
+++ b/src/Text/Pandoc/App/OutputSettings.hs
@@ -41,7 +41,8 @@ import Text.Pandoc.App.Opt (Opt (..))
 import Text.Pandoc.App.CommandLineOptions (engines, setVariable)
 import qualified Text.Pandoc.Format as Format
 import Text.Pandoc.Highlighting (lookupHighlightingStyle)
-import Text.Pandoc.Scripting (ScriptingEngine (engineWriteCustom))
+import Text.Pandoc.Scripting (ScriptingEngine (engineLoadCustom),
+                              CustomComponents(..))
 import qualified Text.Pandoc.UTF8 as UTF8
 
 readUtf8File :: PandocMonad m => FilePath -> m T.Text
@@ -126,12 +127,18 @@ optToOutputSettings scriptingEngine opts = do
     if "lua" `T.isSuffixOf` format
     then do
       let path = T.unpack format
-      (w, extsConf, mt) <- engineWriteCustom scriptingEngine path
+      components <- engineLoadCustom scriptingEngine path
+      w <- case customWriter components of
+             Nothing -> throwError $ PandocAppError $
+                         format <> " does not contain a custom writer"
+             Just w -> return w
+      let extsConf = fromMaybe mempty $ customExtensions components
       wexts <- Format.applyExtensionsDiff extsConf flvrd
-      templ <- processCustomTemplate $ case mt of
-        Nothing -> throwError $ PandocNoTemplateError format
-        Just t  -> (runWithDefaultPartials $ compileTemplate path t) >>=
-                   templateOrThrow
+      templ <- processCustomTemplate $
+               case customTemplate components of
+                 Nothing -> throwError $ PandocNoTemplateError format
+                 Just t -> (runWithDefaultPartials $ compileTemplate path t) >>=
+                           templateOrThrow
       return (w, wexts, templ)
     else do
       tmpl <- processCustomTemplate (compileDefaultTemplate format)
diff --git a/src/Text/Pandoc/Scripting.hs b/src/Text/Pandoc/Scripting.hs
index 1942014cb..8b90a9749 100644
--- a/src/Text/Pandoc/Scripting.hs
+++ b/src/Text/Pandoc/Scripting.hs
@@ -11,6 +11,7 @@ Central data structure for scripting engines.
 -}
 module Text.Pandoc.Scripting
   ( ScriptingEngine (..)
+  , CustomComponents(..)
   , noEngine
   )
 where
@@ -26,6 +27,18 @@ import Text.Pandoc.Format (ExtensionsConfig)
 import Text.Pandoc.Readers (Reader)
 import Text.Pandoc.Writers (Writer)
 
+-- | A component of a custom reader/writer: a custom reader,
+-- a custom writer, a template for a custom writer, or a specification
+-- of the extensions used by a script and their default values.
+-- Note that a single script can contain all of these.
+data CustomComponents m =
+  CustomComponents
+  { customReader :: Maybe (Reader m)
+  , customWriter :: Maybe (Writer m)
+  , customTemplate :: Maybe Text
+  , customExtensions :: Maybe ExtensionsConfig
+  }
+
 -- | Structure to define a scripting engine.
 data ScriptingEngine = ScriptingEngine
   { engineName :: Text   -- ^ Name of the engine.
@@ -35,14 +48,9 @@ data ScriptingEngine = ScriptingEngine
                       -> Pandoc -> m Pandoc
     -- ^ Use the scripting engine to run a filter.
 
-  , engineReadCustom :: forall m. (PandocMonad m, MonadIO m)
-                     => FilePath -> m (Reader m, ExtensionsConfig)
-    -- ^ Function to parse input into a 'Pandoc' document.
-
-  , engineWriteCustom :: forall m. (PandocMonad m, MonadIO m)
-                      => FilePath
-                      -> m (Writer m, ExtensionsConfig, Maybe Text)
-    -- ^ Invoke the given script file to convert to any custom format.
+  , engineLoadCustom :: forall m. (PandocMonad m, MonadIO m)
+                     => FilePath -> m (CustomComponents m)
+    -- ^ Function to load a custom reader/writer from a script.
   }
 
 noEngine :: ScriptingEngine
@@ -50,8 +58,6 @@ noEngine = ScriptingEngine
   { engineName = "none"
   , engineApplyFilter = \_env _args _fp _doc ->
       throwError PandocNoScriptingEngine
-  , engineReadCustom = \_fp ->
-      throwError PandocNoScriptingEngine
-  , engineWriteCustom = \_fp ->
+  , engineLoadCustom = \_fp ->
       throwError PandocNoScriptingEngine
   }