-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Pandoc-style document templates
--   
--   This is the text templating system used by pandoc. It supports
--   variable interpolation, iteration, tests for non-blank values, pipes,
--   and partials. Templates are rendered to doclayout Docs, and variable
--   values may come from a variety of different sources, including aeson
--   Values.
@package doctemplates
@version 0.9


module Text.DocTemplates.Internal

-- | Render a compiled template in a "context" which provides values for
--   the template's variables.
renderTemplate :: (TemplateTarget a, ToContext a b) => Template a -> b -> Doc a

-- | A <a>TemplateMonad</a> defines a function to retrieve a partial (from
--   the file system, from a database, or using a default value).
class Monad m => TemplateMonad m
getPartial :: TemplateMonad m => FilePath -> m Text

-- | A <a>Context</a> defines values for template's variables.
newtype Context a
Context :: Map Text (Val a) -> Context a
[unContext] :: Context a -> Map Text (Val a)

-- | A variable value.
data Val a
SimpleVal :: Doc a -> Val a
ListVal :: [Val a] -> Val a
MapVal :: Context a -> Val a
BoolVal :: Bool -> Val a
NullVal :: Val a

-- | The <a>ToContext</a> class provides automatic conversion to a
--   <a>Context</a> or <a>Val</a>.
class ToContext a b
toContext :: ToContext a b => b -> Context a
toVal :: ToContext a b => b -> Val a

-- | The <a>FromContext</a> class provides functions for extracting values
--   from <a>Val</a> and <a>Context</a>.
class FromContext a b
fromVal :: FromContext a b => Val a -> Maybe b
lookupContext :: FromContext a b => Text -> Context a -> Maybe b
type TemplateTarget a = (HasChars a, ToText a, FromText a)

-- | A template.
data Template a
Interpolate :: Variable -> Template a
Conditional :: Variable -> Template a -> Template a -> Template a
Iterate :: Variable -> Template a -> Template a -> Template a
Nested :: Template a -> Template a
Partial :: [Pipe] -> Template a -> Template a
Literal :: Doc a -> Template a
Concat :: Template a -> Template a -> Template a
Empty :: Template a

-- | A variable which may have several parts (<tt>foo.bar.baz</tt>).
data Variable
Variable :: [Text] -> [Pipe] -> Variable
[varParts] :: Variable -> [Text]
[varPipes] :: Variable -> [Pipe]
data Pipe
ToPairs :: Pipe
ToUppercase :: Pipe
ToLowercase :: Pipe
ToLength :: Pipe
Reverse :: Pipe
FirstItem :: Pipe
LastItem :: Pipe
Rest :: Pipe
AllButLast :: Pipe
Chomp :: Pipe
ToAlpha :: Pipe
ToRoman :: Pipe
NoWrap :: Pipe
Block :: Alignment -> Int -> Border -> Pipe
data Alignment
LeftAligned :: Alignment
Centered :: Alignment
RightAligned :: Alignment
data Border
Border :: Text -> Text -> Border
[borderLeft] :: Border -> Text
[borderRight] :: Border -> Text
instance GHC.Classes.Ord Text.DocTemplates.Internal.Alignment
instance GHC.Classes.Eq Text.DocTemplates.Internal.Alignment
instance GHC.Generics.Generic Text.DocTemplates.Internal.Alignment
instance Data.Data.Data Text.DocTemplates.Internal.Alignment
instance GHC.Read.Read Text.DocTemplates.Internal.Alignment
instance GHC.Show.Show Text.DocTemplates.Internal.Alignment
instance GHC.Classes.Ord Text.DocTemplates.Internal.Border
instance GHC.Classes.Eq Text.DocTemplates.Internal.Border
instance GHC.Generics.Generic Text.DocTemplates.Internal.Border
instance Data.Data.Data Text.DocTemplates.Internal.Border
instance GHC.Read.Read Text.DocTemplates.Internal.Border
instance GHC.Show.Show Text.DocTemplates.Internal.Border
instance GHC.Classes.Ord Text.DocTemplates.Internal.Pipe
instance GHC.Classes.Eq Text.DocTemplates.Internal.Pipe
instance GHC.Generics.Generic Text.DocTemplates.Internal.Pipe
instance Data.Data.Data Text.DocTemplates.Internal.Pipe
instance GHC.Read.Read Text.DocTemplates.Internal.Pipe
instance GHC.Show.Show Text.DocTemplates.Internal.Pipe
instance GHC.Classes.Ord Text.DocTemplates.Internal.Variable
instance GHC.Classes.Eq Text.DocTemplates.Internal.Variable
instance GHC.Generics.Generic Text.DocTemplates.Internal.Variable
instance Data.Data.Data Text.DocTemplates.Internal.Variable
instance GHC.Read.Read Text.DocTemplates.Internal.Variable
instance GHC.Show.Show Text.DocTemplates.Internal.Variable
instance GHC.Base.Functor Text.DocTemplates.Internal.Template
instance Data.Traversable.Traversable Text.DocTemplates.Internal.Template
instance Data.Foldable.Foldable Text.DocTemplates.Internal.Template
instance GHC.Classes.Ord a => GHC.Classes.Ord (Text.DocTemplates.Internal.Template a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.DocTemplates.Internal.Template a)
instance GHC.Generics.Generic (Text.DocTemplates.Internal.Template a)
instance Data.Data.Data a => Data.Data.Data (Text.DocTemplates.Internal.Template a)
instance GHC.Read.Read a => GHC.Read.Read (Text.DocTemplates.Internal.Template a)
instance GHC.Show.Show a => GHC.Show.Show (Text.DocTemplates.Internal.Template a)
instance Data.Data.Data a => Data.Data.Data (Text.DocTemplates.Internal.Context a)
instance GHC.Base.Functor Text.DocTemplates.Internal.Context
instance Data.Foldable.Foldable Text.DocTemplates.Internal.Context
instance Data.Traversable.Traversable Text.DocTemplates.Internal.Context
instance GHC.Base.Monoid (Text.DocTemplates.Internal.Context a)
instance GHC.Base.Semigroup (Text.DocTemplates.Internal.Context a)
instance GHC.Show.Show a => GHC.Show.Show (Text.DocTemplates.Internal.Context a)
instance Data.Data.Data a => Data.Data.Data (Text.DocTemplates.Internal.Val a)
instance GHC.Base.Functor Text.DocTemplates.Internal.Val
instance Data.Foldable.Foldable Text.DocTemplates.Internal.Val
instance Data.Traversable.Traversable Text.DocTemplates.Internal.Val
instance GHC.Show.Show a => GHC.Show.Show (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateMonad Data.Functor.Identity.Identity
instance Text.DocTemplates.Internal.TemplateMonad GHC.Types.IO
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.FromContext a (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.FromContext a (Text.DocLayout.Doc a)
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.FromContext a a
instance Text.DocTemplates.Internal.TemplateTarget [a] => Text.DocTemplates.Internal.FromContext [a] [a]
instance Text.DocTemplates.Internal.FromContext a b => Text.DocTemplates.Internal.FromContext a [b]
instance Text.DocTemplates.Internal.ToContext a (Text.DocTemplates.Internal.Context a)
instance Text.DocTemplates.Internal.ToContext a (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.ToContext a a
instance Text.DocTemplates.Internal.ToContext a a => Text.DocTemplates.Internal.ToContext a (Text.DocLayout.Doc a)
instance Text.DocTemplates.Internal.ToContext a b => Text.DocTemplates.Internal.ToContext a [b]
instance Text.DocTemplates.Internal.TemplateTarget [a] => Text.DocTemplates.Internal.ToContext [a] [a]
instance Text.DocTemplates.Internal.ToContext a b => Text.DocTemplates.Internal.ToContext a (Data.Map.Internal.Map Data.Text.Internal.Text b)
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.ToContext a GHC.Types.Bool
instance Text.DocTemplates.Internal.TemplateTarget a => Text.DocTemplates.Internal.ToContext a Data.Aeson.Types.Internal.Value
instance Text.DocTemplates.Internal.TemplateTarget a => Data.Aeson.Types.FromJSON.FromJSON (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.Aeson.Types.FromJSON.FromJSON (Text.DocTemplates.Internal.Context a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.YAML.FromYAML (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.YAML.FromYAML (Text.DocTemplates.Internal.Context a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.Aeson.Types.ToJSON.ToJSON (Text.DocTemplates.Internal.Context a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.Aeson.Types.ToJSON.ToJSON (Text.DocTemplates.Internal.Val a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.YAML.ToYAML (Text.DocTemplates.Internal.Context a)
instance Text.DocTemplates.Internal.TemplateTarget a => Data.YAML.ToYAML (Text.DocTemplates.Internal.Val a)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Text.DocTemplates.Internal.Template a)
instance GHC.Base.Semigroup a => GHC.Base.Monoid (Text.DocTemplates.Internal.Template a)
instance GHC.Base.Semigroup Text.DocTemplates.Internal.Variable
instance GHC.Base.Monoid Text.DocTemplates.Internal.Variable


module Text.DocTemplates.Parser

-- | Compile a template. The FilePath parameter is used to determine a
--   default path and extension for partials and may be left empty if
--   partials are not used.
compileTemplate :: (TemplateMonad m, TemplateTarget a) => FilePath -> Text -> m (Either String (Template a))


-- | This is the text templating system used by pandoc. Its basic function
--   is to fill variables in a template. Variables are provided by a
--   “context.” Any instance of the <tt>ToContext</tt> typeclass (such as
--   an aeson <tt>Value</tt>) can serve as the context, or a
--   <tt>Context</tt> value can be constructed manually.
--   
--   Control structures are provided to test whether a variable has a
--   non-blank value and to iterate over the items of a list. Partials—that
--   is, subtemplates defined in different files—are supported. Pipes can
--   be used to transform the values of variables or partials. The provided
--   pipes make it possible to do list enumeration and tabular layout in
--   templates.
--   
--   Templates are rendered to a doclayout <tt>Doc</tt> (which is
--   polymorphic in the underlying string type). If <tt>Doc</tt> values are
--   used in the context, rendered documents will be able to wrap flexibly
--   on breaking spaces. This feature makes doctemplates more suitable than
--   other template engines for plain-text formats (like Markdown).
--   
--   Unlike the various HTML-centered template engines, doctemplates is
--   output-format agnostic, so no automatic escaping is done on
--   interpolated values. Values are assumed to be escaped properly in the
--   Context.
--   
--   <h2>Example of use</h2>
--   
--   <pre>
--   import Data.Text (Text)
--   import qualified Data.Text.IO as T
--   import Data.Aeson
--   import Text.DocTemplates
--   import Text.DocLayout (render)
--   
--   data Employee = Employee { firstName :: String
--                            , lastName  :: String
--                            , salary    :: Maybe Int }
--   instance ToJSON Employee where
--     toJSON e = object [ "name" .= object [ "first" .= firstName e
--                                          , "last"  .= lastName e ]
--                       , "salary" .= salary e ]
--   
--   template :: Text
--   template = "$for(employee)$Hi, $employee.name.first$. $if(employee.salary)$You make $employee.salary$.$else$No salary data.$endif$$sep$\n$endfor$"
--   
--   main :: IO ()
--   main = do
--     res &lt;- compileTemplate "mytemplate.txt" template
--     case res of
--            Left e    -&gt; error e
--            Right t   -&gt; T.putStrLn $ render Nothing $ renderTemplate t $ object
--                           ["employee" .=
--                             [ Employee "John" "Doe" Nothing
--                             , Employee "Omar" "Smith" (Just 30000)
--                             , Employee "Sara" "Chen" (Just 60000) ]
--                           ]
--   </pre>
--   
--   <h2>Delimiters</h2>
--   
--   To mark variables and control structures in the template, either
--   <tt>$</tt>…<tt>$</tt> or <tt>${</tt>…<tt>}</tt> may be used as
--   delimiters. The styles may also be mixed in the same template, but the
--   opening and closing delimiter must match in each case. The opening
--   delimiter may be followed by one or more spaces or tabs, which will be
--   ignored. The closing delimiter may be followed by one or more spaces
--   or tabs, which will be ignored.
--   
--   To include a literal <tt>$</tt> in the document, use <tt>$$</tt>.
--   
--   <h2>Comments</h2>
--   
--   Anything between the sequence <tt>$--</tt> and the end of the line
--   will be treated as a comment and omitted from the output.
--   
--   <h2>Interpolated variables</h2>
--   
--   A slot for an interpolated variable is a variable name surrounded by
--   matched delimiters. Variable names must begin with a letter and can
--   contain letters, numbers, <tt>_</tt>, <tt>-</tt>, and <tt>.</tt>. The
--   keywords <tt>it</tt>, <tt>if</tt>, <tt>else</tt>, <tt>endif</tt>,
--   <tt>for</tt>, <tt>sep</tt>, and <tt>endfor</tt> may not be used as
--   variable names. Examples:
--   
--   <pre>
--   $foo$
--   $foo.bar.baz$
--   $foo_bar.baz-bim$
--   $ foo $
--   ${foo}
--   ${foo.bar.baz}
--   ${foo_bar.baz-bim}
--   ${ foo }
--   </pre>
--   
--   The values of variables are determined by the <tt>Context</tt> that is
--   passed as a parameter to <tt>renderTemplate</tt>. So, for example,
--   <tt>title</tt> will return the value of the <tt>title</tt> field, and
--   <tt>employee.salary</tt> will return the value of the <tt>salary</tt>
--   field of the object that is the value of the <tt>employee</tt> field.
--   
--   <ul>
--   <li>If the value of the variable is simple value, it will be rendered
--   verbatim. (Note that no escaping is done; the assumption is that the
--   calling program will escape the strings appropriately for the output
--   format.)</li>
--   <li>If the value is a list, the values will be concatenated.</li>
--   <li>If the value is a map, the string <tt>true</tt> will be
--   rendered.</li>
--   <li>Every other value will be rendered as the empty string.</li>
--   </ul>
--   
--   When a <tt>Context</tt> is derived from an aeson (JSON)
--   <tt>Value</tt>, the following conversions are done:
--   
--   <ul>
--   <li>If the value is a number, it will be rendered as an integer if
--   possible, otherwise as a floating-point number.</li>
--   <li>If the value is a JSON boolean, it will be rendered as
--   <tt>true</tt> if true, and as the empty string if false.</li>
--   </ul>
--   
--   <h2>Conditionals</h2>
--   
--   A conditional begins with <tt>if(variable)</tt> (enclosed in matched
--   delimiters) and ends with <tt>endif</tt> (enclosed in matched
--   delimiters). It may optionally contain an <tt>else</tt> (enclosed in
--   matched delimiters). The <tt>if</tt> section is used if
--   <tt>variable</tt> has a non-empty value, otherwise the <tt>else</tt>
--   section is used (if present). (Note that even the string
--   <tt>false</tt> counts as a true value.) Examples:
--   
--   <pre>
--   $if(foo)$bar$endif$
--   
--   $if(foo)$
--     $foo$
--   $endif$
--   
--   $if(foo)$
--   part one
--   $else$
--   part two
--   $endif$
--   
--   ${if(foo)}bar${endif}
--   
--   ${if(foo)}
--     ${foo}
--   ${endif}
--   
--   ${if(foo)}
--   ${ foo.bar }
--   ${else}
--   no foo!
--   ${endif}
--   </pre>
--   
--   The keyword <tt>elseif</tt> may be used to simplify complex nested
--   conditionals. Thus
--   
--   <pre>
--   $if(foo)$
--   XXX
--   $elseif(bar)$
--   YYY
--   $else$
--   ZZZ
--   $endif$
--   </pre>
--   
--   is equivalent to
--   
--   <pre>
--   $if(foo)$
--   XXX
--   $else$
--   $if(bar)$
--   YYY
--   $else$
--   ZZZ
--   $endif$
--   $endif$
--   </pre>
--   
--   <h2>For loops</h2>
--   
--   A for loop begins with <tt>for(variable)</tt> (enclosed in matched
--   delimiters) and ends with <tt>endfor</tt> (enclosed in matched
--   delimiters.
--   
--   <ul>
--   <li>If <tt>variable</tt> is an array, the material inside the loop
--   will be evaluated repeatedly, with <tt>variable</tt> being set to each
--   value of the array in turn, and concatenated.</li>
--   <li>If <tt>variable</tt> is a map, the material inside will be set to
--   the map.</li>
--   <li>If the value of the associated variable is not an array or a map,
--   a single iteration will be performed on its value.</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   $for(foo)$$foo$$sep$, $endfor$
--   
--   $for(foo)$
--     - $foo.last$, $foo.first$
--   $endfor$
--   
--   ${ for(foo.bar) }
--     - ${ foo.bar.last }, ${ foo.bar.first }
--   ${ endfor }
--   
--   $for(mymap)$
--   $it.name$: $it.office$
--   $endfor$
--   </pre>
--   
--   You may optionally specify a separator between consecutive values
--   using <tt>sep</tt> (enclosed in matched delimiters). The material
--   between <tt>sep</tt> and the <tt>endfor</tt> is the separator.
--   
--   <pre>
--   ${ for(foo) }${ foo }${ sep }, ${ endfor }
--   </pre>
--   
--   Instead of using <tt>variable</tt> inside the loop, the special
--   anaphoric keyword <tt>it</tt> may be used.
--   
--   <pre>
--   ${ for(foo.bar) }
--     - ${ it.last }, ${ it.first }
--   ${ endfor }
--   </pre>
--   
--   <h2>Partials</h2>
--   
--   Partials (subtemplates stored in different files) may be included
--   using the syntax
--   
--   <pre>
--   ${ boilerplate() }
--   </pre>
--   
--   The partials are obtained using <tt>getPartial</tt> from the
--   <tt>TemplateMonad</tt> class. This may be implemented differently in
--   different monads. The path passed to <tt>getPartial</tt> is computed
--   on the basis of the original template path (a parameter to
--   <tt>compileTemplate</tt>) and the partial’s name. The partial’s name
--   is substituted for the <i>base name</i> of the original template path
--   (leaving the original template’s extension), unless the partial has an
--   explicit extension, in which case this is kept. So, with the
--   <tt>TemplateMonad</tt> instance for IO, partials will be sought in the
--   directory containing the main template, and will be assumed to have
--   the extension of the main template.
--   
--   Partials may optionally be applied to variables using a colon:
--   
--   <pre>
--   ${ date:fancy() }
--   
--   ${ articles:bibentry() }
--   </pre>
--   
--   If <tt>articles</tt> is an array, this will iterate over its values,
--   applying the partial <tt>bibentry()</tt> to each one. So the second
--   example above is equivalent to
--   
--   <pre>
--   ${ for(articles) }
--   ${ it:bibentry() }
--   ${ endfor }
--   </pre>
--   
--   Note that the anaphoric keyword <tt>it</tt> must be used when
--   iterating over partials. In the above examples, the <tt>bibentry</tt>
--   partial should contain <tt>it.title</tt> (and so on) instead of
--   <tt>articles.title</tt>.
--   
--   Final newlines are omitted from included partials.
--   
--   Partials may include other partials. If you exceed a nesting level of
--   50, though, in resolving partials, the literal <tt>(loop)</tt> will be
--   returned, to avoid infinite loops.
--   
--   A separator between values of an array may be specified in square
--   brackets, immediately after the variable name or partial:
--   
--   <pre>
--   ${months[, ]}$
--   
--   ${articles:bibentry()[; ]$
--   </pre>
--   
--   The separator in this case is literal and (unlike with <tt>sep</tt> in
--   an explicit <tt>for</tt> loop) cannot contain interpolated variables
--   or other template directives.
--   
--   <h2>Nesting</h2>
--   
--   To ensure that content is “nested,” that is, subsequent lines
--   indented, use the <tt>^</tt> directive:
--   
--   <pre>
--   $item.number$  $^$$item.description$ ($item.price$)
--   </pre>
--   
--   In this example, if <tt>item.description</tt> has multiple lines, they
--   will all be indented to line up with the first line:
--   
--   <pre>
--   00123  A fine bottle of 18-year old
--          Oban whiskey. ($148)
--   </pre>
--   
--   To nest multiple lines to the same level, align them with the
--   <tt>^</tt> directive in the template. For example:
--   
--   <pre>
--   $item.number$  $^$$item.description$ ($item.price$)
--                  (Available til $item.sellby$.)
--   </pre>
--   
--   will produce
--   
--   <pre>
--   00123  A fine bottle of 18-year old
--          Oban whiskey. ($148)
--          (Available til March 30, 2020.)
--   </pre>
--   
--   If a variable occurs by itself on a line, preceded by whitespace and
--   not followed by further text or directives on the same line, and the
--   variable’s value contains multiple lines, it will be nested
--   automatically.
--   
--   <h2>Breakable spaces</h2>
--   
--   When rendering to a <tt>Doc</tt>, a distinction can be made between
--   breakable and unbreakable spaces. Normally, spaces in the template
--   itself (as opposed to values of the interpolated variables) are not
--   breakable, but they can be made breakable in part of the template by
--   using the <tt>~</tt> keyword (ended with another <tt>~</tt>).
--   
--   <pre>
--   $~$This long line may break if the document is rendered
--   with a short line length.$~$
--   </pre>
--   
--   The <tt>~</tt> keyword has no effect when rendering to <tt>Text</tt>
--   or <tt>String</tt>.
--   
--   <h2>Pipes</h2>
--   
--   A pipe transforms the value of a variable or partial. Pipes are
--   specified using a slash (<tt>/</tt>) between the variable name (or
--   partial) and the pipe name. Example:
--   
--   <pre>
--   $for(name)$
--   $name/uppercase$
--   $endfor$
--   
--   $for(metadata/pairs)$
--   - $it.key$: $it.value$
--   $endfor$
--   
--   $employee:name()/uppercase$
--   </pre>
--   
--   Pipes may be chained:
--   
--   <pre>
--   $for(employees/pairs)$
--   $it.key/alpha/uppercase$. $it.name$
--   $endfor$
--   </pre>
--   
--   Some pipes take parameters:
--   
--   <pre>
--   |----------------------|------------|
--   $for(employee)$
--   $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
--   $endfor$
--   |----------------------|------------|
--   </pre>
--   
--   Currently the following pipes are predefined:
--   
--   <ul>
--   <li><tt>pairs</tt>: Converts a map or array to an array of maps, each
--   with <tt>key</tt> and <tt>value</tt> fields. If the original value was
--   an array, the <tt>key</tt> will be the array index, starting with
--   1.</li>
--   <li><tt>first</tt>: Returns the first value of an array, if applied to
--   a non-empty array; otherwise returns the original value.</li>
--   <li><tt>last</tt>: Returns the last value of an array, if applied to a
--   non-empty array; otherwise returns the original value.</li>
--   <li><tt>rest</tt>: Returns all but the first value of an array, if
--   applied to a non-empty array; otherwise returns the original
--   value.</li>
--   <li><tt>allbutlast</tt>: Returns all but the last value of an array,
--   if applied to a non-empty array; otherwise returns the original
--   value.</li>
--   <li><tt>uppercase</tt>: Converts text to uppercase.</li>
--   <li><tt>lowercase</tt>: Converts text to lowercase.</li>
--   <li><tt>length</tt>: Returns the length of the value: number of
--   characters for a textual value, number of elements for a map or
--   array.</li>
--   <li><tt>reverse</tt>: Reverses a textual value or array, and has no
--   effect on other values.</li>
--   <li><tt>chomp</tt>: Removes trailing newlines (and breakable
--   space).</li>
--   <li><tt>nowrap</tt>: Disables line wrapping on breakable spaces.</li>
--   <li><tt>alpha</tt>: Converts textual values that can be read as an
--   integer into lowercase alphabetic characters <tt>a..z</tt> (mod 26).
--   This can be used to get lettered enumeration from array indices. To
--   get uppercase letters, chain with <tt>uppercase</tt>.</li>
--   <li><tt>roman</tt>: Converts textual values that can be read as an
--   integer into lowercase roman numerials. This can be used to get
--   lettered enumeration from array indices. To get uppercase roman, chain
--   with <tt>uppercase</tt>.</li>
--   <li><tt>left n "leftborder" "rightborder"</tt>: Renders a textual
--   value in a block of width <tt>n</tt>, aligned to the left, with an
--   optional left and right border. Has no effect on other values. This
--   can be used to align material in tables. Widths are positive integers
--   indicating the number of characters. Borders are strings inside double
--   quotes; literal <tt>"</tt> and <tt>\</tt> characters must be
--   backslash-escaped.</li>
--   <li><tt>right n "leftborder" "rightborder"</tt>: Renders a textual
--   value in a block of width <tt>n</tt>, aligned to the right, and has no
--   effect on other values.</li>
--   <li><tt>center n "leftborder" "rightborder"</tt>: Renders a textual
--   value in a block of width <tt>n</tt>, aligned to the center, and has
--   no effect on other values.</li>
--   </ul>
module Text.DocTemplates

-- | Render a compiled template in a "context" which provides values for
--   the template's variables.
renderTemplate :: (TemplateTarget a, ToContext a b) => Template a -> b -> Doc a

-- | Compile a template. The FilePath parameter is used to determine a
--   default path and extension for partials and may be left empty if
--   partials are not used.
compileTemplate :: (TemplateMonad m, TemplateTarget a) => FilePath -> Text -> m (Either String (Template a))

-- | Compile a template from a file. IO errors will be raised as
--   exceptions; template parsing errors result in Left return values.
compileTemplateFile :: TemplateTarget a => FilePath -> IO (Either String (Template a))

-- | Compile a template and apply it to a context. This is just a
--   convenience function composing <a>compileTemplate</a> and
--   <a>renderTemplate</a>. If a template will be rendered more than once
--   in the same process, compile it separately for better performance.
applyTemplate :: (TemplateMonad m, TemplateTarget a, ToContext a b) => FilePath -> Text -> b -> m (Either String (Doc a))

-- | A <a>TemplateMonad</a> defines a function to retrieve a partial (from
--   the file system, from a database, or using a default value).
class Monad m => TemplateMonad m
getPartial :: TemplateMonad m => FilePath -> m Text
type TemplateTarget a = (HasChars a, ToText a, FromText a)

-- | A <a>Context</a> defines values for template's variables.
newtype Context a
Context :: Map Text (Val a) -> Context a
[unContext] :: Context a -> Map Text (Val a)

-- | A variable value.
data Val a
SimpleVal :: Doc a -> Val a
ListVal :: [Val a] -> Val a
MapVal :: Context a -> Val a
BoolVal :: Bool -> Val a
NullVal :: Val a

-- | The <a>ToContext</a> class provides automatic conversion to a
--   <a>Context</a> or <a>Val</a>.
class ToContext a b
toContext :: ToContext a b => b -> Context a
toVal :: ToContext a b => b -> Val a

-- | The <a>FromContext</a> class provides functions for extracting values
--   from <a>Val</a> and <a>Context</a>.
class FromContext a b
fromVal :: FromContext a b => Val a -> Maybe b
lookupContext :: FromContext a b => Text -> Context a -> Maybe b

-- | A template.
data Template a

-- | Document, including structure relevant for layout.
data Doc a

-- | Text with specified width.
Text :: Int -> a -> Doc a

-- | A block with a width and lines.
Block :: Int -> [a] -> Doc a

-- | A vertically expandable block; when concatenated with a block, expands
--   to height of block, with each line containing the specified text.
VFill :: Int -> a -> Doc a

-- | Doc with each line prefixed with text. Note that trailing blanks are
--   omitted from the prefix when the line after it is empty.
Prefixed :: Text -> Doc a -> Doc a

-- | Doc that renders only before nonblank.
BeforeNonBlank :: Doc a -> Doc a

-- | Doc laid out flush to left margin.
Flush :: Doc a -> Doc a

-- | A space or line break, in context.
BreakingSpace :: Doc a

-- | Text printed only at start of line.
AfterBreak :: Text -> Doc a

-- | Newline unless we're at start of line.
CarriageReturn :: Doc a

-- | newline.
NewLine :: Doc a

-- | Ensure a number of blank lines.
BlankLines :: Int -> Doc a

-- | Two documents concatenated.
Concat :: Doc a -> Doc a -> Doc a
Empty :: Doc a
