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


-- | Randomized templating language DSL
--   
--   Madlang is a text templating language written in Haskell, meant to
--   explore computational creativity and generative literature.
@package madlang
@version 3.1.1.21


-- | <h1>Madlang Text Generation Library, EDSL, and Interpreted
--   Language</h1>
--   
--   <h2>Purpose</h2>
--   
--   Madlang is a text-genrating Domain-Specific Language (DSL). It is
--   similar in purpose to <a>tracery</a>, but it is written in Haskell and
--   therefore offers more flexibility.
--   
--   <h2>Example</h2>
--   
--   In file example.mad: <tt> :define gambling 1.0 "heads" 1.0 "tails"
--   :return 1.0 "The result of the coin flip was: " gambling </tt>
--   
--   <pre>
--   $ madlang run example.mad
--   tails
--   </pre>
module Text.Madlibs

-- | Parse text given a context
--   
--   <pre>
--   import qualified Data.Text.IO as TIO
--   
--   getParsed = do
--       f &lt;- TIO.readFile "template.mad"
--       parseTok "filename.mad" [] [] f
--   </pre>
parseTok :: FilePath -> [(Key, RandTok)] -> [Text] -> Text -> Either (ParseError Char (ErrorFancy Void)) RandTok

-- | Parse text as a token + context (aka a reader monad with all the other
--   functions)
parseTokM :: [Text] -> Parser (Context RandTok)

-- | Generate randomized text from a file containing a template
runFile :: [Text] -> FilePath -> IO Text

-- | Parse text as a token, suitable for printing as a tree..
parseTree :: FilePath -> [(Key, RandTok)] -> [Text] -> Text -> Either (ParseError Char (ErrorFancy Void)) RandTok

-- | Parse a template file into the <a>RandTok</a> data type
parseFile :: MonadIO m => [Text] -> FilePath -> FilePath -> m (Either (ParseError Char (ErrorFancy Void)) RandTok)

-- | Parse a template into a RandTok suitable to be displayed as a tree
makeTree :: [Text] -> FilePath -> FilePath -> IO (Either (ParseError Char (ErrorFancy Void)) RandTok)

-- | Generate randomized text from a <a>RandTok</a>
--   
--   <pre>
--   getText :: IO T.Text
--   getText = do
--       let exampleTok = List [(1.0,List [(0.5,Value "heads"),(0.5,Value "tails")])]
--       run exampleTok
--   </pre>
run :: (MonadRandom m) => RandTok -> m Text

-- | Same thing, but uses a catamorphism (slower)
runCata :: (MonadRandom m) => RandTok -> m Text

-- | Run based on text input, with nothing linked.
runText :: (MonadRandom m) => [Text] -> String -> Text -> m Text

-- | datatype for a token returning a random string
data RandTok
List :: [(Prob, RandTok)] -> RandTok
Value :: Text -> RandTok

-- | dataype for a key aka token name
type Key = Text

-- | State monad providing context, i.e. function we've already called
--   before
type Context a = State [(Key, RandTok)] a

-- | Datatype for a semantic error
data SemanticError
NoReturn :: SemanticError
CircularFunctionCalls :: Text -> Text -> SemanticError
InsufficientArgs :: Int -> Int -> SemanticError
DoubleDefinition :: Text -> SemanticError
NoContext :: Text -> SemanticError
ImportNotFound :: FilePath -> SemanticError

-- | Main program action
--   
--   Example Usage:
--   
--   <pre>
--   $ madlang run example.mad
--   some text generated
--   </pre>
runMadlang :: IO ()

-- | <a>QuasiQuoter</a> for an EDSL, e.g.
--   
--   <pre>
--   demoQQ :: T.Text
--   demoQQ = run
--   [madlang|
--   :define something
--       1.0 "hello"
--       1.0 "goodbye"
--   :return
--       1.0 something
--   |]
--   </pre>
--   
--   Note that this is in general much faster than running interpreted
--   code, though inclusions do not work in the <a>QuasiQuoter</a> or in
--   spliced expressions.
madlang :: QuasiQuoter

-- | Splice for embedding a '.mad' file, e.g.
--   
--   <pre>
--   demo :: IO T.Text
--   demo = run
--       $(madFile "twitter-bot.mad")
--   </pre>
--   
--   Note that the embedded code cannot have any inclusions
madFile :: FilePath -> Q Exp