-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A lightweight markup language for story writers -- -- Please see README.md @package ogmarkup @version 2.2 -- | 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 *. Emph :: [Format a] -> Format a -- | Surrounded by **. 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, OpenQuote and CloseQuote are -- not valid Mark values here. Indeed, they are implicit with the -- Quote 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 ; Semicolon :: Mark -- | The character , Colon :: Mark -- | The character ? Question :: Mark -- | The character ! Exclamation :: Mark -- | The character " OpenQuote :: Mark -- | The character " CloseQuote :: Mark -- | The character – or the sequence -- Dash :: Mark -- | The character — or the sequence --- LongDash :: Mark -- | The character , Comma :: Mark -- | The character . Point :: Mark -- | The character - Hyphen :: Mark -- | Two or more . or the character … SuspensionPoints :: Mark -- | The characters ' or ’ 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 Ast of an Ogmarkup document. -- -- Please consider that only document 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 -- | Update the ParserState to guard against nested emphasis. enterEmph :: OgmarkupParser () -- | Update the ParserState to be able to parse input with emphasis -- again. leaveEmph :: OgmarkupParser () -- | Update the ParserState to guard against nested strong emphasis. enterStrongEmph :: OgmarkupParser () -- | Update the ParserState to be able to parse input with strong -- emphasis again. leaveStrongEmph :: OgmarkupParser () -- | Update the ParserState to guard against nested quoted inputs. enterQuote :: OgmarkupParser () -- | Update the ParserState to be able to parse an input surrounded -- by quotes again. leaveQuote :: OgmarkupParser () -- | A initial ParserState instance to be used at the begining of a -- document parsing. initParserState :: ParserState -- | An ogmarkup parser processes Char tokens and carries a -- ParserState. type OgmarkupParser = GenParser Char ParserState -- | A wrapper around the runParser function of Parsec. It uses -- initParserState as an initial state. parse :: OgmarkupParser a -> String -> String -> Either ParseError a -- | Try its best to parse an ogmarkup document. When it encounters an -- error, it returns an Ast and the remaining input. -- -- See Document. document :: IsString a => OgmarkupParser (Document a, String) -- | See Section. section :: IsString a => OgmarkupParser (Section a) -- | See Aside. aside :: IsString a => OgmarkupParser (Section a) -- | See Story. story :: IsString a => OgmarkupParser (Section a) -- | See Paragraph. paragraph :: IsString a => OgmarkupParser (Paragraph a) -- | See Component. component :: IsString a => OgmarkupParser (Component a) -- | See IllFormed. illformed :: IsString a => OgmarkupParser (Component a) -- | 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 :: IsString a => OgmarkupParser a -- | See Teller. teller :: IsString a => OgmarkupParser (Component a) -- | See Dialogue. dialogue :: IsString a => OgmarkupParser (Component a) -- | See Thought. thought :: IsString a => OgmarkupParser (Component a) -- | talk c c' constr wraps a reply surrounded by -- c and c' inside constr (either -- Dialogue or Thought). talk :: IsString a => Char -> Char -> (Reply a -> Maybe a -> Component a) -> OgmarkupParser (Component a) -- | Parse the name of the character which speaks or thinks. According to -- the ogmarkup syntax, it is surrounded by parentheses. characterName :: IsString a => OgmarkupParser a -- | reply parses a Reply. reply :: IsString a => Char -> Char -> OgmarkupParser (Reply a) -- | See Format. format :: IsString a => OgmarkupParser (Format a) -- | See Raw. raw :: IsString a => OgmarkupParser (Format a) -- | See Emph. emph :: IsString a => OgmarkupParser (Format a) -- | See StrongEmph. strongEmph :: IsString a => OgmarkupParser (Format a) -- | See Quote. quote :: IsString a => OgmarkupParser (Format a) -- | See Atom. atom :: IsString a => OgmarkupParser (Atom a) -- | See Word. This parser does not consume the following spaces, so -- the caller needs to take care of it. word :: IsString a => OgmarkupParser (Atom a) -- | Wrap a raw string surrounded by ` inside a Word. -- -- 
--   >>> parse longword "" "`test *ei*`"
--   Right (Ast.Word "test *ei*")
--
-- -- Therefore, ` can be used to insert normally reserved symbol -- inside a generated document. longword :: IsString a => OgmarkupParser (Atom a) -- | See Punctuation. Be aware that mark does not parse the -- quotes because they are processed quote. mark :: OgmarkupParser (Atom a) -- | See OpenQuote. This parser consumes the following blank (see -- blank) and skip the result. openQuote :: OgmarkupParser () -- | See CloseQuote. This parser consumes the following blank (see -- blank) and skip the result. closeQuote :: OgmarkupParser () -- | An aside section (see Aside) is a particular region surrounded -- by two lines of underscores (at least three). This parser consumes one -- such line. asideSeparator :: OgmarkupParser () -- | 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 :: OgmarkupParser () -- | This parser consumes all the white spaces until it finds either an -- aside surrounding marker (see Aside), the end of the document -- or one blank line. The latter marks the end of the current paragraph. blank :: OgmarkupParser () -- | skip p parses p and skips the result. skip :: OgmarkupParser a -> OgmarkupParser () -- | This module provides the Typography 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 Mark, 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 Mark 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 IsString. 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 IsString. 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 GenConf typeclass which is used to -- configure the Generators monad. module Text.Ogmarkup.Private.Config -- | A Template is just synonym for a template of one argument. type Template a = a -> a -- | An instance of the GenConf typeclass can be given as a -- parameter to a Generator. 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 c. -- -- 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. -- -- Warning: GenConf is a multiparam typeclass (see -- MultiParamTypeClasses GHC extension). In order to make new -- instances, the following extensions need to be enabled: -- -- -- -- Otherwise, GHC will not accept your instance statement. class (IsString o, Monoid o) => GenConf c o | c -> o where typography _ = englishTypo documentTemplate _ = id errorTemplate _ = id storyTemplate _ = id asideTemplate _ _ = id paragraphTemplate _ = id tellerTemplate _ = id dialogueTemplate _ _ = id thoughtTemplate _ _ = id replyTemplate _ = id betweenDialogue _ = mempty emphTemplate _ = id strongEmphTemplate _ = id authorNormalize _ = maybe mempty id -- | Returns a Typography instance to be used by the -- Generator. -- -- typography :: GenConf c o => c -> Typography o -- | This template is used once the output has been completely generated. -- -- documentTemplate :: GenConf c o => c -> Template o -- | This template is used on the ill-formed portion of the ogmarkup -- document which have been ignored during the best-effort compilation. -- -- errorTemplate :: GenConf c o => c -> Template o -- | This template is used on regular sections which focus on telling the -- story. -- -- storyTemplate :: GenConf c o => c -> Template o -- | This template is used on aside sections which may comprised -- flashbacks, letters or songs, for instance. -- -- asideTemplate :: GenConf c o => c -> Maybe o -> Template o -- | This template is used on paragraphs within a section. -- -- paragraphTemplate :: GenConf c o => c -> Template o -- | This template is used on the narrative portion of an ogmarkup -- document. -- -- tellerTemplate :: GenConf c o => c -> 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 authorNormalize function is used by -- the generator to get a default value when no character names are -- provided. -- -- dialogueTemplate :: GenConf c o => c -> o -> Template o -- | This template is used on unaudible dialogue. See -- dialogueTemplate to get more information on why the class name -- is not optional. -- -- thoughtTemplate :: GenConf c o => c -> o -> Template o replyTemplate :: GenConf c o => c -> 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 -- -- betweenDialogue :: GenConf c o => c -> o -- | A template to apply emphasis to an piece of text. -- -- Default implementation: the identity function emphTemplate :: GenConf c o => c -> Template o -- | A template to apply stong emphasis (often bold) to a piece of text. -- -- strongEmphTemplate :: GenConf c o => c -> Template o -- | This function is called by a Generator to derive a class name for an -- optional character name. -- -- authorNormalize :: GenConf c o => c -> Maybe o -> o -- | Generate an output from a Space. printSpace :: GenConf c o => c -> Space -> o -- | The generation of the output from an Ast is carried out by the -- Generator Monad. module Text.Ogmarkup.Private.Generator -- | The Generator Monad is eventually used to generate an output -- from a given 'Ast.Document. Internally, it keeps track of the previous -- processed Atom in order to deal with atom separation. newtype Generator c a x Generator :: StateT (a, Maybe (Atom a)) (Reader c) x -> Generator c a x [getState] :: Generator c a x -> StateT (a, Maybe (Atom a)) (Reader c) x -- | Run a Generator monad and get the generated output. The output -- type has to implement the class Monoid because the -- Generator monad uses the mempty constant as the initial -- state of the output and then uses mappend to expand the result -- as it processes the generation. runGenerator :: Monoid a => Generator c a x -> c -> a -- | Retrieve a configuration parameter. Let the output untouched. askConf :: (c -> b) -> Generator c a b -- | Apply a template to the result of a given Generator 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 Atom 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 Atom and deal with the space to use to separate it -- from the paramter of the previous call (that is the last processed -- Atom). atom :: (Monoid a, GenConf c a) => Atom a -> Generator c a () -- | Call atom if the parameter is not Nothing. Otherwise, do -- nothing. maybeAtom :: (Monoid a, GenConf c a) => Maybe (Atom a) -> Generator c a () -- | Process a sequence of Atom. atoms :: (Monoid a, GenConf c a) => [Atom a] -> Generator c a () -- | Process a Format. format :: (Monoid a, GenConf c a) => Format a -> Generator c a () -- | Process a sequence of Format. formats :: (Monoid a, GenConf c a) => [Format a] -> Generator c a () -- | Process a Reply. reply :: (Monoid a, GenConf c a) => Maybe (Atom a) -> Maybe (Atom a) -> Reply a -> Generator c a () -- | Process a Component. component :: (Monoid a, GenConf c a) => Bool -> Bool -> Component a -> Generator c a () -- | Process a Paragraph and deal with sequence of Reply. paragraph :: (Monoid a, GenConf c a) => Paragraph a -> Generator c a () -- | Process a sequence of Paragraph. paragraphs :: (Monoid a, GenConf c a) => [Paragraph a] -> Generator c a () -- | Process a Section. section :: (Monoid a, GenConf c a) => Section a -> Generator c a () -- | Process a sequence of Section. sections :: (Monoid a, GenConf c a) => [Section a] -> Generator c a () -- | Process a Document, that is a complete Ogmarkup document. document :: (Monoid a, GenConf c a) => Document a -> Generator c a () instance Control.Monad.Reader.Class.MonadReader c (Text.Ogmarkup.Private.Generator.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 -- | With the best-effort compilation feature of ogmarkup, when the parser -- encounters an error, it can apply two different strategies with the -- remaining input to find a new synchronization point. It can search -- character by character or line by line. data Strategy ByLine :: Strategy ByChar :: Strategy -- | 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 -- IsString and Monoid classes. ogmarkup :: (IsString a, Monoid a, GenConf c a) => Strategy -> String -> c -> a -- | An instance of the GenConf typeclass can be given as a -- parameter to a Generator. 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 c. -- -- 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. -- -- Warning: GenConf is a multiparam typeclass (see -- MultiParamTypeClasses GHC extension). In order to make new -- instances, the following extensions need to be enabled: -- -- -- -- Otherwise, GHC will not accept your instance statement. class (IsString o, Monoid o) => GenConf c o | c -> o where typography _ = englishTypo documentTemplate _ = id errorTemplate _ = id storyTemplate _ = id asideTemplate _ _ = id paragraphTemplate _ = id tellerTemplate _ = id dialogueTemplate _ _ = id thoughtTemplate _ _ = id replyTemplate _ = id betweenDialogue _ = mempty emphTemplate _ = id strongEmphTemplate _ = id authorNormalize _ = maybe mempty id -- | Returns a Typography instance to be used by the -- Generator. -- -- typography :: GenConf c o => c -> Typography o -- | This template is used once the output has been completely generated. -- -- documentTemplate :: GenConf c o => c -> Template o -- | This template is used on the ill-formed portion of the ogmarkup -- document which have been ignored during the best-effort compilation. -- -- errorTemplate :: GenConf c o => c -> Template o -- | This template is used on regular sections which focus on telling the -- story. -- -- storyTemplate :: GenConf c o => c -> Template o -- | This template is used on aside sections which may comprised -- flashbacks, letters or songs, for instance. -- -- asideTemplate :: GenConf c o => c -> Maybe o -> Template o -- | This template is used on paragraphs within a section. -- -- paragraphTemplate :: GenConf c o => c -> Template o -- | This template is used on the narrative portion of an ogmarkup -- document. -- -- tellerTemplate :: GenConf c o => c -> 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 authorNormalize function is used by -- the generator to get a default value when no character names are -- provided. -- -- dialogueTemplate :: GenConf c o => c -> o -> Template o -- | This template is used on unaudible dialogue. See -- dialogueTemplate to get more information on why the class name -- is not optional. -- -- thoughtTemplate :: GenConf c o => c -> o -> Template o replyTemplate :: GenConf c o => c -> 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 -- -- betweenDialogue :: GenConf c o => c -> o -- | A template to apply emphasis to an piece of text. -- -- Default implementation: the identity function emphTemplate :: GenConf c o => c -> Template o -- | A template to apply stong emphasis (often bold) to a piece of text. -- -- strongEmphTemplate :: GenConf c o => c -> Template o -- | This function is called by a Generator to derive a class name for an -- optional character name. -- -- authorNormalize :: GenConf c o => c -> Maybe o -> o -- | Generate an output from a Space. printSpace :: GenConf c o => c -> Space -> o -- | A Template 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 IsString. 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 IsString. 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 Mark, 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 ; Semicolon :: Mark -- | The character , Colon :: Mark -- | The character ? Question :: Mark -- | The character ! Exclamation :: Mark -- | The character " OpenQuote :: Mark -- | The character " CloseQuote :: Mark -- | The character – or the sequence -- Dash :: Mark -- | The character — or the sequence --- LongDash :: Mark -- | The character , Comma :: Mark -- | The character . Point :: Mark -- | The character - Hyphen :: Mark -- | Two or more . or the character … SuspensionPoints :: Mark -- | The characters ' or ’ 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