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


-- | A lightweight markup language for story writers
--   
--   ogmarkup is a lightweight markup language for story writers.
--   <a>ogmarkup</a> also refers to a haskell library that provides a
--   generic conversion function to transform an ogmarkup document into a
--   ready-to-publish document.
@package ogmarkup
@version 4.0


-- | An abstract representation of an ogmarkup document.
module Text.Ogmarkup.Private.Ast

-- | A ogmarkup document internal representation waiting to be used in
--   order to generate an output.
type Document a = [Section a]

-- | A Section within an ogmarkup document is a sequence of paragraphs. It
--   can be part of the story or an aside section like a letter, a song,
--   etc. We make the distinction between the two cases because we want to
--   be able to apply different style depending on the situation.
data Section a

-- | The story as it goes
Story :: [Paragraph a] -> Section a

-- | Something else. Maybe a letter, a flashback, etc.
Aside :: (Maybe a) -> [Paragraph a] -> Section a
Failing :: a -> Section a

-- | A Paragraph is just a sequence of Component.
type Paragraph a = [Component a]

-- | A Component is either a narrative text, a character's line of dialogue
--   or a character's inner thought.
--   
--   We also embed an error Component in case we fail to parse a valid
--   component. This way, we can resume parsing when we meet a new
--   paragraph.
data Component a

-- | A narrative description
Teller :: [Format a] -> Component a

-- | A dialogue reply
Dialogue :: (Reply a) -> (Maybe a) -> Component a

-- | Inner dialogue of the character
Thought :: (Reply a) -> (Maybe a) -> Component a

-- | If none of the above matched, then output what follows as-is, the
--   parsing will be resumed at the next paragraph
IllFormed :: a -> Component a

-- | A character's line of dialogue. A reply may contain a descriptive
--   part, which is not part of what the character actually says or thinks.
--   We call the latter a "with say" reply untill someone gives use a
--   better name for it.
data Reply a

-- | A reply of the form: "Good morning."
Simple :: [Format a] -> Reply a

-- | A reply of the form: "Good morning," she says. "How are you?"
WithSay :: [Format a] -> [Format a] -> [Format a] -> Reply a

-- | A nested formatted text
data Format a

-- | No particular emphasis is required on this sequence
Raw :: [Atom a] -> Format a

-- | Surrounded by <tt>*</tt>.
Emph :: [Format a] -> Format a

-- | Surrounded by <tt>**</tt>.
StrongEmph :: [Format a] -> Format a
Quote :: [Format a] -> Format a

-- | An Atom is the atomic component of a Ogmarkup document. It can be
--   either a punctuation mark or a word, that is a string.
--   
--   Note that, by construction, <a>OpenQuote</a> and <a>CloseQuote</a> are
--   not valid <a>Mark</a> values here. Indeed, they are implicit with the
--   <a>Quote</a> constructor. This design allows the parser to enforce
--   that an opened quote needs to be closed.
data Atom a

-- | A wrapped string
Word :: a -> Atom a

-- | A punctuation mark
Punctuation :: Mark -> Atom a

-- | Mostly in order to deal with typographic spaces, main punctuation
--   marks are tokenized during the parsing of an Ogmarkup document.
data Mark

-- | The character <tt>;</tt>
Semicolon :: Mark

-- | The character <tt>,</tt>
Colon :: Mark

-- | The character <tt>?</tt>
Question :: Mark

-- | The character <tt>!</tt>
Exclamation :: Mark

-- | The character <tt>"</tt>
OpenQuote :: Mark

-- | The character <tt>"</tt>
CloseQuote :: Mark

-- | The character – or the sequence <tt>--</tt>
Dash :: Mark

-- | The character — or the sequence <tt>---</tt>
LongDash :: Mark

-- | The character <tt>,</tt>
Comma :: Mark

-- | The character <tt>.</tt>
Point :: Mark

-- | The character <tt>-</tt>
Hyphen :: Mark

-- | Two or more <tt>.</tt> or the character …
SuspensionPoints :: Mark

-- | The characters <tt>'</tt> or <tt>’</tt>
Apostrophe :: Mark
instance GHC.Show.Show a => GHC.Show.Show (Text.Ogmarkup.Private.Ast.Section a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Ogmarkup.Private.Ast.Section a)
instance GHC.Show.Show a => GHC.Show.Show (Text.Ogmarkup.Private.Ast.Component a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Ogmarkup.Private.Ast.Component a)
instance GHC.Show.Show a => GHC.Show.Show (Text.Ogmarkup.Private.Ast.Reply a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Ogmarkup.Private.Ast.Reply a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Ogmarkup.Private.Ast.Format a)
instance GHC.Show.Show a => GHC.Show.Show (Text.Ogmarkup.Private.Ast.Format a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Ogmarkup.Private.Ast.Atom a)
instance GHC.Show.Show a => GHC.Show.Show (Text.Ogmarkup.Private.Ast.Atom a)
instance GHC.Classes.Eq Text.Ogmarkup.Private.Ast.Mark
instance GHC.Show.Show Text.Ogmarkup.Private.Ast.Mark


-- | This module provides several parsers that can be used in order to
--   extract the <tt>Ast</tt> of an Ogmarkup document.
--   
--   Please consider that only <a>document</a> should be used outside this
--   module.
module Text.Ogmarkup.Private.Parser

-- | Keep track of the currently opened formats.
data ParserState
ParserState :: Bool -> Bool -> Bool -> ParserState

-- | Already parsing text with emphasis
[parseWithEmph] :: ParserState -> Bool

-- | Already parsing text with strong emphasis
[parseWithStrongEmph] :: ParserState -> Bool

-- | Already parsing a quote
[parseWithinQuote] :: ParserState -> Bool

-- | An ogmarkup parser processes <a>Char</a> tokens and carries a
--   <a>ParserState</a>.
type OgmarkupParser a = StateT ParserState (Parsec Void a)

-- | Update the <a>ParserState</a> to guard against nested emphasis.
enterEmph :: Stream a => OgmarkupParser a ()

-- | Update the <a>ParserState</a> to be able to parse input with emphasis
--   again.
leaveEmph :: Stream a => OgmarkupParser a ()

-- | Update the <a>ParserState</a> to guard against nested strong emphasis.
enterStrongEmph :: Stream a => OgmarkupParser a ()

-- | Update the <a>ParserState</a> to be able to parse input with strong
--   emphasis again.
leaveStrongEmph :: Stream a => OgmarkupParser a ()

-- | Update the <a>ParserState</a> to guard against nested quoted inputs.
enterQuote :: Stream a => OgmarkupParser a ()

-- | Update the <a>ParserState</a> to be able to parse an input surrounded
--   by quotes again.
leaveQuote :: Stream a => OgmarkupParser a ()

-- | A initial ParserState instance to be used at the begining of a
--   document parsing.
initParserState :: ParserState

-- | A wrapper around the <a>runParser</a> function of Megaparsec. It uses
--   <a>initParserState</a> as an initial state.
parse :: Stream a => OgmarkupParser a b -> String -> a -> Either (ParseError (Token a) Void) b

-- | Try its best to parse an ogmarkup document. When it encounters an
--   error, it returns an Ast and the remaining input.
--   
--   See <a>Document</a>.
document :: (Stream a, Token a ~ Char, IsString (Tokens a), IsString b) => OgmarkupParser a (Document b)

-- | See <a>Section</a>.
section :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Section b)

-- | See <a>Aside</a>.
aside :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Section b)

-- | See <a>Story</a>.
story :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Section b)

-- | See <a>Paragraph</a>.
paragraph :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Paragraph b)

-- | See <a>Component</a>.
component :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Component b)

-- | See <a>IllFormed</a>.
illformed :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Component b)

-- | Parse the rest of the current paragraph with no regards for the
--   ogmarkup syntax. This Parser is used when the document is ill-formed,
--   to find a new point of synchronization.
restOfParagraph :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a b

-- | See <a>Teller</a>.
teller :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Component b)

-- | See <a>Dialogue</a>.
dialogue :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Component b)

-- | See <a>Thought</a>.
thought :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Component b)

-- | <tt><a>talk</a> c c' constr</tt> wraps a reply surrounded by
--   <tt>c</tt> and <tt>c'</tt> inside <tt>constr</tt> (either
--   <a>Dialogue</a> or <a>Thought</a>).
talk :: (Stream a, Token a ~ Char, IsString b) => Char -> Char -> (Reply b -> Maybe b -> Component b) -> OgmarkupParser a (Component b)

-- | Parse the name of the character which speaks or thinks. According to
--   the ogmarkup syntax, it is surrounded by parentheses.
characterName :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a b

-- | <a>reply</a> parses a <a>Reply</a>.
reply :: (Stream a, Token a ~ Char, IsString b) => Char -> Char -> OgmarkupParser a (Reply b)

-- | See <a>Format</a>.
format :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Format b)

-- | See <a>Raw</a>.
raw :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Format b)

-- | See <a>Emph</a>.
emph :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Format b)

-- | See <a>StrongEmph</a>.
strongEmph :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Format b)

-- | See <a>Quote</a>.
quote :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Format b)

-- | See <a>Atom</a>.
atom :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Atom b)

-- | See <a>Word</a>. This parser does not consume the following spaces, so
--   the caller needs to take care of it.
word :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Atom b)

-- | Wrap a raw string surrounded by <tt>`</tt> inside a <a>Word</a>.
--   
--   <pre>
--   &gt;&gt;&gt; parse longword "" "`test *ei*`"
--   Right (Ast.Word "test *ei*")
--   </pre>
--   
--   Therefore, <tt>`</tt> can be used to insert normally reserved symbol
--   inside a generated document.
longword :: (Stream a, Token a ~ Char, IsString b) => OgmarkupParser a (Atom b)

-- | See <a>Punctuation</a>. Be aware that <a>mark</a> does not parse the
--   quotes because they are processed <a>quote</a>.
mark :: (Stream a, Token a ~ Char) => OgmarkupParser a (Atom b)

-- | See <a>OpenQuote</a>. This parser consumes the following blank (see
--   <a>blank</a>) and skip the result.
openQuote :: (Stream a, Token a ~ Char) => OgmarkupParser a ()

-- | See <a>CloseQuote</a>. This parser consumes the following blank (see
--   <a>blank</a>) and skip the result.
closeQuote :: (Stream a, Token a ~ Char) => OgmarkupParser a ()

-- | An aside section (see <a>Aside</a>) is a particular region surrounded
--   by two lines of underscores (at least three). This parser consumes one
--   such line.
asideSeparator :: (Stream a, Token a ~ Char) => OgmarkupParser a ()

-- | The end of a paragraph is the end of the document or two blank lines
--   or an aside separator, that is a line of underscores.
endOfParagraph :: (Stream a, Token a ~ Char) => OgmarkupParser a ()

-- | This parser consumes all the white spaces until it finds either an
--   aside surrounding marker (see <a>Aside</a>), the end of the document
--   or one blank line. The latter marks the end of the current paragraph.
blank :: (Stream a, Token a ~ Char) => OgmarkupParser a ()

-- | <tt>skip p</tt> parses <tt>p</tt> and skips the result.
skip :: (Stream a) => OgmarkupParser a b -> OgmarkupParser a ()


-- | This module provides the <a>Typography</a> datatype along with two
--   default instances for French and English.
module Text.Ogmarkup.Private.Typography

-- | Deal with typographic spaces, especially when it comes to separating
--   two texts. Because Space derives Ord, it is possible to use min and
--   max to determine which one to use in case of a conflict.
data Space

-- | A normal space that can be turned into a newline for displaying.
Normal :: Space

-- | A non breakable space, it cannot be turned into a newline.
Nbsp :: Space

-- | No space at all.
None :: Space

-- | A Typography is a data type that tells the caller what space should be
--   privileged before and after a text.
data Typography a
Typography :: (Mark -> (Space, Space, a)) -> (Bool -> Maybe Mark) -> (Bool -> Maybe Mark) -> Typography a

-- | For a given <a>Mark</a>, returns a tuple with the spaces to use before
--   and after the punctuation mark and its output value.
[decide] :: Typography a -> Mark -> (Space, Space, a)

-- | Which mark to use to open a dialogue. If the parameter is True, there
--   were another dialogue just before.
[openDialogue] :: Typography a -> Bool -> Maybe Mark

-- | Which mark to use to close a dialogue. If the parameter is True, there
--   is another dialogue just after.
[closeDialogue] :: Typography a -> Bool -> Maybe Mark

-- | Apply the function to each <a>Mark</a> output value

-- | From a Typography, it gives the space to privilege before the input
--   Text.
beforeAtom :: Typography a -> Atom a -> Space

-- | From a Typography, it gives the space to privilege after the input
--   Text.
afterAtom :: Typography a -> Atom a -> Space

-- | Normalize the input in order to add it to a generated Text.
normalizeAtom :: Typography a -> Atom a -> a

-- | A proposal for the French typography. It can be used with several
--   generation approaches, as it remains very generic. Requires the output
--   type to be an instance of <a>IsString</a>.
frenchTypo :: IsString a => Typography a

-- | A proposal for the English typography. It can be used with several
--   generation approaches, as it remains very generic. Requires the output
--   type to be an instance of <a>IsString</a>.
englishTypo :: IsString a => Typography a
instance GHC.Classes.Ord Text.Ogmarkup.Private.Typography.Space
instance GHC.Classes.Eq Text.Ogmarkup.Private.Typography.Space
instance GHC.Base.Functor Text.Ogmarkup.Private.Typography.Typography


-- | This module provides the <a>GenConf</a> typeclass which is used to
--   configure the <a>Generator</a>s monad.
module Text.Ogmarkup.Private.Config

-- | A <a>Template</a> is just synonym for a template of one argument.
type Template a = a -> a

-- | An instance of the <a>GenConf</a> typeclass can be given as a
--   parameter to a <a>Generator</a>. In order to prevent GHC to
--   overabstract this typeclass, there can be only one instance of GenConf
--   for one datatype. In other words, one datatype can only handle one
--   return type <tt>c</tt>.
--   
--   For each template, we give a prefered layout and some hints about the
--   default implementation (which is almost always the identity function,
--   ignoring all the parameters but the generated output.
--   
--   <b>Warning:</b> <a>GenConf</a> is a multiparam typeclass (see
--   <tt>MultiParamTypeClasses</tt> GHC extension). In order to make new
--   instances, the following extensions need to be enabled:
--   
--   <ul>
--   <li><pre>FlexibleInstances</pre></li>
--   <li><pre>MultiParamTypeClasses</pre></li>
--   </ul>
--   
--   Otherwise, GHC will not accept your instance statement.
class (IsString o, Monoid o) => GenConf c o | c -> o

-- | Returns a <a>Typography</a> instance to be used by the
--   <a>Generator</a>.
--   
--   <ul>
--   <li><b>Default implementation:</b> returns <a>englishTypo</a>.</li>
--   </ul>
typography :: GenConf c o => Typography o

-- | This template is used once the output has been completely generated.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
documentTemplate :: GenConf c o => Template o

-- | This template is used on the ill-formed portion of the ogmarkup
--   document which have been ignored during the best-effort compilation.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
errorTemplate :: GenConf c o => Template o

-- | This template is used on regular sections which focus on telling the
--   story.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
storyTemplate :: GenConf c o => Template o

-- | This template is used on aside sections which may comprised
--   flashbacks, letters or songs, for instance.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function (it ignores
--   the class name)</li>
--   </ul>
asideTemplate :: GenConf c o => Maybe o -> Template o

-- | This template is used on paragraphs within a section.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
paragraphTemplate :: GenConf c o => Template o

-- | This template is used on the narrative portion of an ogmarkup
--   document.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
tellerTemplate :: GenConf c o => Template o

-- | This template is used on audible dialogue. The class name is mandatory
--   even if the character name is optional for dialogues and thoughts in
--   the ogmarkup grammar. The <a>authorNormalize</a> function is used by
--   the generator to get a default value when no character names are
--   provided.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
dialogueTemplate :: GenConf c o => o -> Template o

-- | This template is used on unaudible dialogue. See
--   <a>dialogueTemplate</a> to get more information on why the class name
--   is not optional.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
thoughtTemplate :: GenConf c o => o -> Template o
replyTemplate :: GenConf c o => Template o

-- | Return a marker to insert between two consecutive dialogues. The
--   default use case is to return the concatenation of the ending mark and
--   the opening mark of a paragraph. a paragrap
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> <a>mempty</a></li>
--   </ul>
betweenDialogue :: GenConf c o => o

-- | A template to apply emphasis to an piece of text.
--   
--   <b>Default implementation:</b> the identity function
emphTemplate :: GenConf c o => Template o

-- | A template to apply stong emphasis (often bold) to a piece of text.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> <a>mempty</a></li>
--   </ul>
strongEmphTemplate :: GenConf c o => Template o

-- | This function is called by a Generator to derive a class name for an
--   optional character name.
--   
--   <ul>
--   <li><b>Default implementation:</b> simply unwrap the Maybe value, if
--   Nothing return <a>mempty</a>.</li>
--   </ul>
authorNormalize :: GenConf c o => Maybe o -> o

-- | Generate an output from a <a>Space</a>.
printSpace :: GenConf c o => Space -> o


-- | The generation of the output from an <a>Ast</a> is carried out by the
--   <a>Generator</a> Monad.
module Text.Ogmarkup.Private.Generator

-- | The <a>Generator</a> Monad is eventually used to generate an output
--   from a given 'Ast.Document. Internally, it keeps track of the previous
--   processed <a>Atom</a> in order to deal with atom separation.
newtype Generator c a x
Generator :: State (a, Maybe (Atom a)) x -> Generator c a x
[getState] :: Generator c a x -> State (a, Maybe (Atom a)) x

-- | Run a <a>Generator</a> monad and get the generated output. The output
--   type has to implement the class <a>Monoid</a> because the
--   <a>Generator</a> monad uses the <a>mempty</a> constant as the initial
--   state of the output and then uses <a>mappend</a> to expand the result
--   as it processes the generation.
runGenerator :: Monoid a => Generator c a x -> a

-- | Apply a template to the result of a given <a>Generator</a> before
--   appending it to the previously generated output.
apply :: Monoid a => Template a -> Generator c a x -> Generator c a ()

-- | Forget about the past and consider the next <a>Atom</a> as the first
--   to be processed.
reset :: Generator c a ()

-- | Append a new sub-output to the generated output.
raw :: Monoid a => a -> Generator c a ()

-- | Process an <a>Atom</a> and deal with the space to use to separate it
--   from the paramter of the previous call (that is the last processed
--   <a>Atom</a>).
atom :: forall c a. (Monoid a, GenConf c a) => Atom a -> Generator c a ()

-- | Call <a>atom</a> if the parameter is not <a>Nothing</a>. Otherwise, do
--   nothing.
maybeAtom :: (Monoid a, GenConf c a) => Maybe (Atom a) -> Generator c a ()

-- | Process a sequence of <a>Atom</a>.
atoms :: (Monoid a, GenConf c a) => [Atom a] -> Generator c a ()

-- | Process a <a>Format</a>.
format :: forall c a. (Monoid a, GenConf c a) => Format a -> Generator c a ()

-- | Process a sequence of <a>Format</a>.
formats :: (Monoid a, GenConf c a) => [Format a] -> Generator c a ()

-- | Process a <a>Reply</a>.
reply :: forall c a. (Monoid a, GenConf c a) => Maybe (Atom a) -> Maybe (Atom a) -> Reply a -> Generator c a ()

-- | Process a <a>Component</a>.
component :: forall c a. (Monoid a, GenConf c a) => Bool -> Bool -> Component a -> Generator c a ()

-- | Process a <a>Paragraph</a> and deal with sequence of <a>Reply</a>.
paragraph :: forall c a. (Monoid a, GenConf c a) => Paragraph a -> Generator c a ()

-- | Process a sequence of <a>Paragraph</a>.
paragraphs :: (Monoid a, GenConf c a) => [Paragraph a] -> Generator c a ()

-- | Process a <a>Section</a>.
section :: forall c a. (Monoid a, GenConf c a) => Section a -> Generator c a ()

-- | Process a sequence of <a>Section</a>.
sections :: (Monoid a, GenConf c a) => [Section a] -> Generator c a ()

-- | Process a <a>Document</a>, that is a complete Ogmarkup document.
document :: forall c a. (Monoid a, GenConf c a) => Document a -> Generator c a ()
instance Control.Monad.State.Class.MonadState (a, GHC.Base.Maybe (Text.Ogmarkup.Private.Ast.Atom a)) (Text.Ogmarkup.Private.Generator.Generator c a)
instance GHC.Base.Monad (Text.Ogmarkup.Private.Generator.Generator c a)
instance GHC.Base.Applicative (Text.Ogmarkup.Private.Generator.Generator c a)
instance GHC.Base.Functor (Text.Ogmarkup.Private.Generator.Generator c a)


-- | The ogmarkup library provides an ogmarkup document compiler. This
--   module is the only one you should need to import in your project.
--   
--   The library is still in an early stage of development, hence the
--   "experimental" stability. Be aware the exposed interface may change in
--   future realase.
module Text.Ogmarkup

-- | From a String, parse and generate an output according to a generation
--   configuration. The inner definitions of the parser and the generator
--   imply that the output type has to be an instance of the
--   <a>IsString</a> and <a>Monoid</a> classes.
ogmarkup :: forall c a b. (Stream a, Token a ~ Char, IsString (Tokens a), IsString b, Monoid b, GenConf c b) => a -> b

-- | If you don’t want to use the <tt>TypeApplications</tt> pragma, you can
--   use this functions insead (but of course, it itself uses the pragma)
ogmarkup' :: forall c a b. (Stream a, Token a ~ Char, IsString (Tokens a), IsString b, Monoid b, GenConf c b) => Proxy c -> a -> b

-- | An instance of the <a>GenConf</a> typeclass can be given as a
--   parameter to a <a>Generator</a>. In order to prevent GHC to
--   overabstract this typeclass, there can be only one instance of GenConf
--   for one datatype. In other words, one datatype can only handle one
--   return type <tt>c</tt>.
--   
--   For each template, we give a prefered layout and some hints about the
--   default implementation (which is almost always the identity function,
--   ignoring all the parameters but the generated output.
--   
--   <b>Warning:</b> <a>GenConf</a> is a multiparam typeclass (see
--   <tt>MultiParamTypeClasses</tt> GHC extension). In order to make new
--   instances, the following extensions need to be enabled:
--   
--   <ul>
--   <li><pre>FlexibleInstances</pre></li>
--   <li><pre>MultiParamTypeClasses</pre></li>
--   </ul>
--   
--   Otherwise, GHC will not accept your instance statement.
class (IsString o, Monoid o) => GenConf c o | c -> o

-- | Returns a <a>Typography</a> instance to be used by the
--   <a>Generator</a>.
--   
--   <ul>
--   <li><b>Default implementation:</b> returns <a>englishTypo</a>.</li>
--   </ul>
typography :: GenConf c o => Typography o

-- | This template is used once the output has been completely generated.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
documentTemplate :: GenConf c o => Template o

-- | This template is used on the ill-formed portion of the ogmarkup
--   document which have been ignored during the best-effort compilation.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
errorTemplate :: GenConf c o => Template o

-- | This template is used on regular sections which focus on telling the
--   story.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
storyTemplate :: GenConf c o => Template o

-- | This template is used on aside sections which may comprised
--   flashbacks, letters or songs, for instance.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function (it ignores
--   the class name)</li>
--   </ul>
asideTemplate :: GenConf c o => Maybe o -> Template o

-- | This template is used on paragraphs within a section.
--   
--   <ul>
--   <li><b>Layout:</b> block</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
paragraphTemplate :: GenConf c o => Template o

-- | This template is used on the narrative portion of an ogmarkup
--   document.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
tellerTemplate :: GenConf c o => Template o

-- | This template is used on audible dialogue. The class name is mandatory
--   even if the character name is optional for dialogues and thoughts in
--   the ogmarkup grammar. The <a>authorNormalize</a> function is used by
--   the generator to get a default value when no character names are
--   provided.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
dialogueTemplate :: GenConf c o => o -> Template o

-- | This template is used on unaudible dialogue. See
--   <a>dialogueTemplate</a> to get more information on why the class name
--   is not optional.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> the identity function</li>
--   </ul>
thoughtTemplate :: GenConf c o => o -> Template o
replyTemplate :: GenConf c o => Template o

-- | Return a marker to insert between two consecutive dialogues. The
--   default use case is to return the concatenation of the ending mark and
--   the opening mark of a paragraph. a paragrap
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> <a>mempty</a></li>
--   </ul>
betweenDialogue :: GenConf c o => o

-- | A template to apply emphasis to an piece of text.
--   
--   <b>Default implementation:</b> the identity function
emphTemplate :: GenConf c o => Template o

-- | A template to apply stong emphasis (often bold) to a piece of text.
--   
--   <ul>
--   <li><b>Layout:</b> inline</li>
--   <li><b>Default implementation:</b> <a>mempty</a></li>
--   </ul>
strongEmphTemplate :: GenConf c o => Template o

-- | This function is called by a Generator to derive a class name for an
--   optional character name.
--   
--   <ul>
--   <li><b>Default implementation:</b> simply unwrap the Maybe value, if
--   Nothing return <a>mempty</a>.</li>
--   </ul>
authorNormalize :: GenConf c o => Maybe o -> o

-- | Generate an output from a <a>Space</a>.
printSpace :: GenConf c o => Space -> o

-- | A <a>Template</a> is just synonym for a template of one argument.
type Template a = a -> a

-- | A proposal for the French typography. It can be used with several
--   generation approaches, as it remains very generic. Requires the output
--   type to be an instance of <a>IsString</a>.
frenchTypo :: IsString a => Typography a

-- | A proposal for the English typography. It can be used with several
--   generation approaches, as it remains very generic. Requires the output
--   type to be an instance of <a>IsString</a>.
englishTypo :: IsString a => Typography a

-- | A Typography is a data type that tells the caller what space should be
--   privileged before and after a text.
data Typography a
Typography :: (Mark -> (Space, Space, a)) -> (Bool -> Maybe Mark) -> (Bool -> Maybe Mark) -> Typography a

-- | For a given <a>Mark</a>, returns a tuple with the spaces to use before
--   and after the punctuation mark and its output value.
[decide] :: Typography a -> Mark -> (Space, Space, a)

-- | Which mark to use to open a dialogue. If the parameter is True, there
--   were another dialogue just before.
[openDialogue] :: Typography a -> Bool -> Maybe Mark

-- | Which mark to use to close a dialogue. If the parameter is True, there
--   is another dialogue just after.
[closeDialogue] :: Typography a -> Bool -> Maybe Mark

-- | Mostly in order to deal with typographic spaces, main punctuation
--   marks are tokenized during the parsing of an Ogmarkup document.
data Mark

-- | The character <tt>;</tt>
Semicolon :: Mark

-- | The character <tt>,</tt>
Colon :: Mark

-- | The character <tt>?</tt>
Question :: Mark

-- | The character <tt>!</tt>
Exclamation :: Mark

-- | The character <tt>"</tt>
OpenQuote :: Mark

-- | The character <tt>"</tt>
CloseQuote :: Mark

-- | The character – or the sequence <tt>--</tt>
Dash :: Mark

-- | The character — or the sequence <tt>---</tt>
LongDash :: Mark

-- | The character <tt>,</tt>
Comma :: Mark

-- | The character <tt>.</tt>
Point :: Mark

-- | The character <tt>-</tt>
Hyphen :: Mark

-- | Two or more <tt>.</tt> or the character …
SuspensionPoints :: Mark

-- | The characters <tt>'</tt> or <tt>’</tt>
Apostrophe :: Mark

-- | Deal with typographic spaces, especially when it comes to separating
--   two texts. Because Space derives Ord, it is possible to use min and
--   max to determine which one to use in case of a conflict.
data Space

-- | A normal space that can be turned into a newline for displaying.
Normal :: Space

-- | A non breakable space, it cannot be turned into a newline.
Nbsp :: Space

-- | No space at all.
None :: Space