-- 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 might be overkill.
@package template
@version 0.1.1.1


-- | 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 apperance of "$" in the string will result in an
--   <a>error</a> being raised.
--   
--   Here is an example of a simple substitution:
--   
--   <pre>
--   import qualified Data.ByteString.Lazy.Char8 as B
--   import Text.Template
--   
--   context = Map.fromList . map packPair
--       where packPair (x, y) = (B.pack x, B.pack y)
--   
--   helloTemplate = B.pack "Hello, $name! Want some ${fruit}s?"
--   helloContext = context [("name", "Johan"), ("fruit", "banana")]
--   
--   main = B.putStrLn $ substitute helloTemplate helloContext
--   </pre>
--   
--   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 rendering it using <a>render</a>. In fact, all that
--   <a>substitute</a> does is to combine these two steps.
module Text.Template

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

-- | A mapping with keys that match the placeholders in the template.
type Context = Map ByteString ByteString

-- | Creates a template from a template string.
template :: ByteString -> Template

-- | Performs the template substitution, returning a new <a>ByteString</a>.
--   
--   If a key is not found in the context an <a>error</a> is raised.
render :: Template -> Context -> ByteString

-- | Performs the template substitution, returning a new <a>ByteString</a>.
--   Note that
--   
--   <pre>
--   substitute tmpl ctx == render (template tmpl) ctx
--   </pre>
--   
--   If a key is not found in the context an <a>error</a> is raised.
substitute :: ByteString -> Context -> ByteString

-- | Shows the template string.
showTemplate :: Template -> ByteString

-- | Reads a template from a file lazily. Use 'text mode' on Windows to
--   interpret newlines
readTemplate :: FilePath -> IO Template

-- | Renders and writes a template to a file. This is more efficient than
--   first <a>render</a>ing the template to a <a>ByteString</a> and then
--   writing it to a file using
--   <tt>Data.ByteString.Lazy.Char8.writeFile</tt>.
renderToFile :: FilePath -> Template -> Context -> IO ()

-- | Renders and writes a template to a <a>Handle</a>. This is more
--   efficient than first <a>render</a>ing the template to a
--   <a>ByteString</a> and then writing it to a <a>Handle</a> using
--   <tt>Data.ByteString.Lazy.Char8.hPutStr</tt>.
hRender :: Handle -> Template -> Context -> IO ()
instance Show Frag
instance Show Template
instance Eq Template