1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
{-# LANGUAGE OverloadedStrings #-}
{- |
Module : Text.Pandoc.Lua.Module.Template
Copyright : Copyright © 2022-2024 Albert Krewinkel, John MacFarlane
License : GNU GPL, version 2 or above
Maintainer : Albert Krewinkel <[email protected]>
Lua module to handle pandoc templates.
-}
module Text.Pandoc.Lua.Module.Template
( documentedModule
) where
import Data.Version (makeVersion)
import HsLua
import HsLua.Module.DocLayout (peekDoc, pushDoc)
import Text.Pandoc.Error (PandocError)
import Text.Pandoc.Lua.Marshal.AST (peekMeta, pushBlocks, pushInlines)
import Text.Pandoc.Lua.Marshal.Context (peekContext, pushContext)
import Text.Pandoc.Lua.Marshal.Template (typeTemplate, peekTemplate, pushTemplate)
import Text.Pandoc.Lua.PandocLua (PandocLua (unPandocLua), liftPandocLua)
import Text.Pandoc.Writers.Shared (metaToContext')
import Text.Pandoc.Templates
( compileTemplate, getDefaultTemplate, renderTemplate
, runWithPartials, runWithDefaultPartials )
import qualified Data.Text as T
-- | The "pandoc.template" module.
documentedModule :: Module PandocError
documentedModule = Module
{ moduleName = "pandoc.template"
, moduleDescription = T.unlines
[ "Handle pandoc templates."
]
, moduleFields = []
, moduleOperations = []
, moduleFunctions = functions
, moduleTypeInitializers = [initType typeTemplate]
}
-- | Template module functions.
functions :: [DocumentedFunction PandocError]
functions =
[ defun "apply"
### liftPure2 renderTemplate
<#> parameter peekTemplate "Template" "template" "template to apply"
<#> parameter peekContext "table" "context" "variable values"
=#> functionResult pushDoc "Doc" "rendered template"
#? T.unlines
[ "Applies a context with variable assignments to a template,"
, "returning the rendered template. The `context` parameter must be a"
, "table with variable names as keys and [[Doc]], string, boolean, or"
, "table as values, where the table can be either be a list of the"
, "aforementioned types, or a nested context."
]
`since` makeVersion [3,0]
, defun "compile"
### (\template mfilepath -> unPandocLua $
case mfilepath of
Just fp -> runWithPartials (compileTemplate fp template)
Nothing -> runWithDefaultPartials
(compileTemplate "templates/default" template))
<#> parameter peekText "string" "template" "template string"
<#> opt (stringParam "templates_path"
("parameter to determine a default path and extension for " <>
"partials; uses the data files templates path by default."))
=#> functionResult (either failLua pushTemplate) "Template"
"compiled template"
#? T.unlines
[ "Compiles a template string into a [[Template]] object usable by"
, "pandoc."
, ""
, "If the `templates_path` parameter is specified, then it should be the"
, "file path associated with the template. It is used when checking"
, "for partials. Partials will be taken only from the default data"
, "files if this parameter is omitted."
, ""
, "An error is raised if compilation fails."
]
`since` makeVersion [2,17]
, defun "default"
### (\mformat -> unPandocLua $ do
let getFORMAT = liftPandocLua $ do
getglobal "FORMAT"
forcePeek $ peekText top `lastly` pop 1
format <- maybe getFORMAT pure mformat
getDefaultTemplate format)
<#> opt (textParam "writer"
("name of the writer for which the template should be " <>
"retrieved; defaults to the global `FORMAT`."))
=#> functionResult pushText "string"
"raw template"
#? T.unlines
[ "Returns the default template for a given writer as a string. An"
, "error is thrown if no such template can be found."
]
`since` makeVersion [2,17]
, defun "meta_to_context"
### (\meta blockWriterIdx inlineWriterIdx -> unPandocLua $ do
let blockWriter blks = liftPandocLua $ do
pushvalue blockWriterIdx
pushBlocks blks
callTrace 1 1
forcePeek $ peekDoc top
let inlineWriter blks = liftPandocLua $ do
pushvalue inlineWriterIdx
pushInlines blks
callTrace 1 1
forcePeek $ peekDoc top
metaToContext' blockWriter inlineWriter meta)
<#> parameter peekMeta "Meta" "meta" "document metadata"
<#> parameter pure "function" "blocks_writer"
"converter from [[Blocks]] to [[Doc]] values"
<#> parameter pure "function" "inlines_writer"
"converter from [[Inlines]] to [[Doc]] values"
=#> functionResult pushContext "table" "template context"
#? T.unlines
[ "Creates template context from the document's [[Meta]] data, using the"
, "given functions to convert [[Blocks]] and [[Inlines]] to [[Doc]]"
, "values."
]
`since` makeVersion [3,0]
]
|
