T.P.Lua: expose more useful internals (API change)

Newly exported from Text.Pandoc.Lua:

- `runFilterFile` to run a Lua filter from file;
- data type `Global` and its constructors; and
- `setGlobals` to add globals to a Lua environment.

This module also contains `Pushable` and `Peekable` instances required
to get pandoc's data types to and from Lua. Low-level Lua operation
remain hidden in Text.Pandoc.Lua.

5 files changed, 37 insertions, 30 deletions

diff --git a/src/Text/Pandoc/Filter/Lua.hs b/src/Text/Pandoc/Filter/Lua.hs
index 48aa66834..a6dc7b6cc 100644
--- a/src/Text/Pandoc/Filter/Lua.hs
+++ b/src/Text/Pandoc/Filter/Lua.hs
@@ -33,19 +33,14 @@ module Text.Pandoc.Filter.Lua (apply) where
 import Prelude
 import Control.Exception (throw)
 import Control.Monad ((>=>))
-import Foreign.Lua (Lua)
 import Text.Pandoc.Class (PandocIO)
 import Text.Pandoc.Definition (Pandoc)
 import Text.Pandoc.Error (PandocError (PandocFilterError))
 import Text.Pandoc.Filter.Path (expandFilterPath)
-import Text.Pandoc.Lua (LuaException (..), runLua)
-import Text.Pandoc.Lua.Filter (LuaFilter, walkMWithLuaFilter)
-import Text.Pandoc.Lua.Global (Global (..), setGlobals)
-import Text.Pandoc.Lua.Util (dofileWithTraceback)
+import Text.Pandoc.Lua (Global (..), LuaException (..),
+                        runLua, runFilterFile, setGlobals)
 import Text.Pandoc.Options (ReaderOptions)
 
-import qualified Foreign.Lua as Lua
-
 -- | Run the Lua filter in @filterPath@ for a transformation to the
 -- target format (first element in args). Pandoc uses Lua init files to
 -- setup the Lua interpreter.
@@ -64,23 +59,9 @@ apply ropts args f doc = do
                , PANDOC_READER_OPTIONS ropts
                , PANDOC_SCRIPT_FILE filterPath
                ]
-    top <- Lua.gettop
-    stat <- dofileWithTraceback filterPath
-    if stat /= Lua.OK
-      then Lua.throwTopMessage
-      else do
-        newtop <- Lua.gettop
-        -- Use the returned filters, or the implicitly defined global
-        -- filter if nothing was returned.
-        luaFilters <- if newtop - top >= 1
-                      then Lua.peek Lua.stackTop
-                      else Lua.pushglobaltable *> fmap (:[]) Lua.popValue
-        runAll luaFilters doc
+    runFilterFile filterPath doc
 
 forceResult :: FilePath -> Either LuaException Pandoc -> PandocIO Pandoc
 forceResult fp eitherResult = case eitherResult of
   Right x               -> return x
   Left (LuaException s) -> throw (PandocFilterError fp s)
-
-runAll :: [LuaFilter] -> Pandoc -> Lua Pandoc
-runAll = foldr ((>=>) . walkMWithLuaFilter) return
diff --git a/src/Text/Pandoc/Lua.hs b/src/Text/Pandoc/Lua.hs
index 3f4d2df07..0a7e6e721 100644
--- a/src/Text/Pandoc/Lua.hs
+++ b/src/Text/Pandoc/Lua.hs
@@ -1,3 +1,4 @@
+{-# LANGUAGE NoImplicitPrelude #-}
 {-
 Copyright © 2017–2018 Albert Krewinkel <tarleb+pandoc@moltkeplatz.de>
 
@@ -15,7 +16,6 @@ You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 -}
-{-# LANGUAGE NoImplicitPrelude #-}
 {- |
    Module      : Text.Pandoc.Lua
    Copyright   : Copyright © 2017–2018 Albert Krewinkel
@@ -27,9 +27,17 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Running pandoc Lua filters.
 -}
 module Text.Pandoc.Lua
-  ( LuaException (..)
-  , runLua
+  ( runLua
+  , LuaException (..)
+  -- * Lua globals
+  , Global (..)
+  , setGlobals
+  -- * Filters
+  , runFilterFile
   ) where
 
+import Text.Pandoc.Lua.Filter (runFilterFile)
+import Text.Pandoc.Lua.Global (Global (..), setGlobals)
 import Text.Pandoc.Lua.Init (LuaException (..), runLua)
+import Text.Pandoc.Lua.StackInstances ()
 
diff --git a/src/Text/Pandoc/Lua/Filter.hs b/src/Text/Pandoc/Lua/Filter.hs
index d17f9a969..d47d3bd9b 100644
--- a/src/Text/Pandoc/Lua/Filter.hs
+++ b/src/Text/Pandoc/Lua/Filter.hs
@@ -30,6 +30,7 @@ Types and functions for running Lua filters.
 -}
 module Text.Pandoc.Lua.Filter ( LuaFilterFunction
                               , LuaFilter
+                              , runFilterFile
                               , tryFilter
                               , runFilterFunction
                               , walkMWithLuaFilter
@@ -54,6 +55,25 @@ import qualified Data.Map.Strict as Map
 import qualified Foreign.Lua as Lua
 import qualified Text.Pandoc.Lua.Util as LuaUtil
 
+-- | Transform document using the filter defined in the given file.
+runFilterFile :: FilePath -> Pandoc -> Lua Pandoc
+runFilterFile filterPath doc = do
+  top <- Lua.gettop
+  stat <- LuaUtil.dofileWithTraceback filterPath
+  if stat /= Lua.OK
+    then Lua.throwTopMessage
+    else do
+      newtop <- Lua.gettop
+      -- Use the returned filters, or the implicitly defined global
+      -- filter if nothing was returned.
+      luaFilters <- if newtop - top >= 1
+                    then Lua.peek Lua.stackTop
+                    else Lua.pushglobaltable *> fmap (:[]) Lua.popValue
+      runAll luaFilters doc
+
+runAll :: [LuaFilter] -> Pandoc -> Lua Pandoc
+runAll = foldr ((>=>) . walkMWithLuaFilter) return
+
 -- | Filter function stored in the registry
 newtype LuaFilterFunction = LuaFilterFunction Lua.Reference
 
diff --git a/src/Text/Pandoc/Lua/Init.hs b/src/Text/Pandoc/Lua/Init.hs
index e922e3d93..e69447ae5 100644
--- a/src/Text/Pandoc/Lua/Init.hs
+++ b/src/Text/Pandoc/Lua/Init.hs
@@ -30,7 +30,6 @@ module Text.Pandoc.Lua.Init
   ( LuaException (..)
   , LuaPackageParams (..)
   , runLua
-  , initLuaState
   , luaPackageParams
   ) where
 
@@ -94,7 +93,7 @@ luaPackageParams = do
     , luaPkgMediaBag = mbRef
     }
 
--- Initialize the lua state with all required values
+-- | Initialize the lua state with all required values
 initLuaState :: LuaPackageParams -> Lua ()
 initLuaState luaPkgParams = do
   Lua.openlibs
diff --git a/src/Text/Pandoc/Writers/Custom.hs b/src/Text/Pandoc/Writers/Custom.hs
index acf18fba9..f38385950 100644
--- a/src/Text/Pandoc/Writers/Custom.hs
+++ b/src/Text/Pandoc/Writers/Custom.hs
@@ -43,9 +43,8 @@ import Foreign.Lua (Lua, Pushable)
 import Text.Pandoc.Class (PandocIO)
 import Text.Pandoc.Definition
 import Text.Pandoc.Error
-import Text.Pandoc.Lua.Global (Global (..), setGlobals)
-import Text.Pandoc.Lua.Init (LuaException (LuaException), runLua)
-import Text.Pandoc.Lua.StackInstances ()
+import Text.Pandoc.Lua (Global (..), LuaException (LuaException),
+                        runLua, setGlobals)
 import Text.Pandoc.Lua.Util (addField, dofileWithTraceback)
 import Text.Pandoc.Options
 import Text.Pandoc.Templates