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


-- | Stupid simple bytestring templates.
--   
--   A template library that has two functions and a type in its API.
--   
--   Sometimes you need a powerful template library which allows for
--   looping and conditional evaluation, deserialization from nearly every
--   standard Haskell type, and manipulation of contexts abstractly. In
--   those cases, I suggest <tt>hastache</tt>.
--   
--   Sometimes you just need to insert <tt>ByteString</tt>s into other
--   <tt>ByteString</tt>s. In those cases, I suggest this library.
@package inserts
@version 0.1.2


-- | The internal workings of <tt>inserts</tt>. In most cases you don't
--   want to be digging around in this module, but it's useful if you want
--   to somehow analyze or transform the <a>Template</a> type.
--   
--   The usual caveat applies: this module is not a public API and is
--   subject to modification without warning.
module Text.Template.Inserts.Internal
newtype Template
Template :: DList TemplateC -> Template
unTemplate :: Template -> DList TemplateC

-- | <a>Template</a> chunks are either <a>Literal</a>s or <a>Hole</a>s to
--   be filled by a runtime key lookup later.
data TemplateC
Literal :: Builder -> TemplateC
Hole :: ByteString -> TemplateC

-- | <a>Got</a> is the "purely <a>Applicative</a>" <a>Either</a> with
--   <tt>[S.ByteString]</tt> as its <a>Left</a> type. When both the left
--   and right arguments to '(<a>*</a>)' are <a>Miss</a> their errors are
--   <a>mappend</a>ed together.
data Got a
Miss :: (DList ByteString) -> Got a
Got :: a -> Got a
gotEither :: Got a -> Either [ByteString] a

-- | Outputs either the successfully interpolated template or the list of
--   missing keys. For fast operation, try building the lookup function
--   using <tt>unordered-containers</tt> <tt>HashMap</tt>s.
runTemplate :: (ByteString -> Maybe ByteString) -> Template -> Either [ByteString] ByteString

-- | We can build a lazy <a>ByteString</a> much more quickly, so if you
--   need to quickly show your templates then this might be nicer than
--   using <a>show</a> directly.
showTemplate :: Template -> ByteString

-- | Try to parse a <a>ByteString</a> as a <a>Template</a>.
parseTemplate :: ByteString -> Either String Template

-- | An <tt>attoparsec</tt> <a>Parser</a> for <a>Template</a>s. This is
--   useful if you'd like to embed <a>Template</a>s into a more
--   sophisticated, parseable type of your own.
templateParser :: Parser Template
instance Functor Got
instance IsString Template
instance Show Template
instance Monoid a => Monoid (Got a)
instance Applicative Got
instance Monoid Template
instance Show TemplateC


-- | Completely trivial, interpolation-only <a>Template</a>s; for when you
--   want an API that fits on a business card. <a>Text.Template.Inserts</a>
--   implements a subset of Mustache syntax. It uses template strings with
--   named holes deliminted by "mustaches":
--   
--   <pre>
--   import Data.HashMap.Strict as Map
--   import Data.ByteString     as S
--   
--   context :: HashMap ByteString ByteString
--   context = Map.fromList [ ("country", "Morocco")
--                          , ("favoriteFruit", "bananas")
--                          ]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runTemplate (flip Map.lookup context) "I live in {{country}} and love {{favoriteFruit}}."
--   Right "I live in Morocco and love bananas"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runTemplate (flip Map.lookup context) "My address is {{ address }}"
--   Left ["address"]
--   </pre>
--   
--   <a>Text.Template.Inserts</a> seeks to be as unsurprising and simple as
--   possible sacrificing all kinds of niceities. Sometimes though, all you
--   need is obvious, trivial string interpolation
module Text.Template.Inserts
data Template

-- | Outputs either the successfully interpolated template or the list of
--   missing keys. For fast operation, try building the lookup function
--   using <tt>unordered-containers</tt> <tt>HashMap</tt>s.
runTemplate :: (ByteString -> Maybe ByteString) -> Template -> Either [ByteString] ByteString

-- | Try to parse a <a>ByteString</a> as a <a>Template</a>.
parseTemplate :: ByteString -> Either String Template

-- | An <tt>attoparsec</tt> <a>Parser</a> for <a>Template</a>s. This is
--   useful if you'd like to embed <a>Template</a>s into a more
--   sophisticated, parseable type of your own.
templateParser :: Parser Template