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


-- | Simple string substitution
--   
--   Simple string substitution library that supports "$"-based
--   substitution. Meant to be used when Text.Printf or string
--   concatenation would lead to code that is hard to read but when a full
--   blown templating system is overkill.
@package template
@version 0.2.0.7


-- | 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 "$".</li>
--   <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>
--   
--   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