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


-- | Simple string substitution
--   
@package template
@version 0.2.0.10


-- | A simple string substitution library that supports "$"-based
--   substitution. Substitution uses the following rules:
--   
--   <ul>
--   <li>"$$" is an escape; it is replaced with a single
--   "$".<ul><li>"$identifier" names a substitution placeholder matching a
--   mapping key of "identifier". "identifier" must spell a Haskell
--   identifier. The first non-identifier character after the "$" character
--   terminates this placeholder specification.</li><li>"${identifier}" is
--   equivalent to "$identifier". It is required when valid identifier
--   characters follow the placeholder but are not part of the placeholder,
--   such as "${noun}ification".</li></ul></li>
--   </ul>
--   
--   Any other appearance of "$" in the string will result in an
--   <a>error</a> being raised.
--   
--   If you render the same template multiple times it's faster to first
--   convert it to a more efficient representation using <a>template</a>
--   and then render it using <a>render</a>. In fact, all that
--   <a>substitute</a> does is to combine these two steps.
module Data.Text.Template

-- | A representation of a <a>Text</a> template, supporting efficient
--   rendering.
data Template

-- | A mapping from placeholders in the template to values.
type Context = Text -> Text

-- | Like <a>Context</a>, but with an applicative lookup function.
type ContextA f = Text -> f Text

-- | Create a template from a template string. A malformed template string
--   will raise an <a>error</a>.
template :: Text -> Template

-- | Create a template from a template string. A malformed template string
--   will cause <a>templateSafe</a> to return <tt>Left (row, col)</tt>,
--   where <tt>row</tt> starts at 1 and <tt>col</tt> at 0.
templateSafe :: Text -> Either (Int, Int) Template

-- | Perform the template substitution, returning a new <a>Text</a>.
render :: Template -> Context -> Text

-- | Perform the template substitution, returning a new <a>Text</a>. A
--   malformed template string will raise an <a>error</a>. Note that
--   
--   <pre>
--   substitute tmpl ctx == render (template tmpl) ctx
--   </pre>
substitute :: Text -> Context -> Text

-- | Show the template string.
showTemplate :: Template -> Text

-- | Like <a>render</a>, but allows the lookup to have side effects. The
--   lookups are performed in order that they are needed to generate the
--   resulting text.
--   
--   You can use this e.g. to report errors when a lookup cannot be made
--   successfully. For example, given a list <tt>ctx</tt> of key-value
--   pairs and a <a>Template</a> <tt>tmpl</tt>:
--   
--   <pre>
--   renderA tmpl (flip lookup ctx)
--   </pre>
--   
--   will return <a>Nothing</a> if any of the placeholders in the template
--   don't appear in <tt>ctx</tt> and <tt>Just text</tt> otherwise.
renderA :: Applicative f => Template -> ContextA f -> f Text

-- | Perform the template substitution in the given <a>Applicative</a>,
--   returning a new <a>Text</a>. Note that
--   
--   <pre>
--   substituteA tmpl ctx == renderA (template tmpl) ctx
--   </pre>
substituteA :: Applicative f => Text -> ContextA f -> f Text
instance Show Frag
instance Show Template
instance Eq Template