-- 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.8

-- | A simple string substitution library that supports "$"-based
--   substitution. Substitution uses the following rules:
--   
--   
--   
- "$$" is an escape; it is replaced with a single "$".
--   
- "$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.
--   
- "${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".
--   
--   
--   Any other appearance of "$" in the string will result in an
--   error being raised.
--   
--   If you render the same template multiple times it's faster to first
--   convert it to a more efficient representation using template
--   and then render it using render. In fact, all that
--   substitute does is to combine these two steps.
module Data.Text.Template

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

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

-- | Like Context, 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 error.
template :: Text -> Template

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

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

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

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

-- | Like render, 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 ctx of key-value
--   pairs and a Template tmpl:
--   
--   
--   renderA tmpl (flip lookup ctx)
--   
--   
--   will return Nothing if any of the placeholders in the template
--   don't appear in ctx and Just text otherwise.
renderA :: Applicative f => Template -> ContextA f -> f Text

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