Text.Ogmarkup

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.

Parse and Generate

data Strategy

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.

Constructors

ByLine

ByChar

ogmarkup

Arguments

:: (IsString a, Monoid a, GenConf c a)

=> Strategy

Best-effort compilation strategy

-> String

The input string

-> c

The generator configuration

-> a

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.

Generation Configuration

class (IsString o, Monoid o) => GenConf c o | c -> o where

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:

• FlexibleInstances

• MultiParamTypeClasses

Otherwise, GHC will not accept your instance statement.

Minimal complete definition

printSpace

Methods

typography :: c -> Typography o

Returns a Typography instance to be used by the Generator.

• Default implementation: returns englishTypo.

documentTemplate :: c -> Template o

This template is used once the output has been completely generated.

• Layout: block
• Default implementation: the identity function

errorTemplate :: 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.

• Layout: inline
• Default implementation: the identity function

storyTemplate :: c -> Template o

This template is used on regular sections which focus on telling the story.

• Layout: block
• Default implementation: the identity function

asideTemplate :: c -> Maybe o -> Template o

This template is used on aside sections which may comprised flashbacks, letters or songs, for instance.

• Layout: block
• Default implementation: the identity function (it ignores the class name)

paragraphTemplate :: c -> Template o

This template is used on paragraphs within a section.

• Layout: block
• Default implementation: the identity function

tellerTemplate :: c -> Template o

This template is used on the narrative portion of an ogmarkup document.

• Layout: inline
• Default implementation: the identity function

dialogueTemplate :: 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 authorNormalize function is used by the generator to get a default value when no character names are provided.

• Layout: inline
• Default implementation: the identity function

thoughtTemplate :: 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.

• Layout: inline
• Default implementation: the identity function

replyTemplate :: c -> Template o

betweenDialogue :: c -> 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

• Layout: inline
• Default implementation: mempty

emphTemplate :: c -> Template o

A template to apply emphasis to an piece of text.

Default implementation: the identity function

strongEmphTemplate :: c -> Template o

A template to apply stong emphasis (often bold) to a piece of text.

• Layout: inline
• Default implementation: mempty

authorNormalize :: c -> Maybe o -> o

This function is called by a Generator to derive a class name for an optional character name.

• Default implementation: simply unwrap the Maybe value, if Nothing return mempty.

printSpace :: c -> Space -> o

Generate an output from a Space.

type Template a = a -> a

A Template is just synonym for a template of one argument.

Typography

frenchTypo :: IsString a => Typography 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.

englishTypo :: 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.

data Typography a

A Typography is a data type that tells the caller what space should be privileged before and after a text.

Constructors

Typography

Fields

• decide :: Mark -> (Space, Space, a)

  For a given Mark, returns a tuple with the spaces to use before and after the punctuation mark and its output value.

• openDialogue :: Bool -> Maybe Mark

  Which mark to use to open a dialogue. If the parameter is True, there were another dialogue just before.

• closeDialogue :: Bool -> Maybe Mark

  Which mark to use to close a dialogue. If the parameter is True, there is another dialogue just after.

Instances

Functor Typography

Apply the function to each Mark output value

Methods

fmap :: (a -> b) -> Typography a -> Typography b

(<$) :: a -> Typography b -> Typography a

Punctuation marks and space

data Mark

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

Constructors

Semicolon

The character ;

Colon

The character ,

Question

The character ?

Exclamation

The character !

OpenQuote

The character "

CloseQuote

The character "

Dash

The character – or the sequence --

LongDash

The character — or the sequence ---

Comma

The character ,

Point

The character .

Hyphen

The character -

SuspensionPoints

Two or more . or the character …

Apostrophe

The characters ' or ’

Instances

Eq Mark

Methods

(==) :: Mark -> Mark -> Bool

(/=) :: Mark -> Mark -> Bool

Show Mark

Methods

showsPrec :: Int -> Mark -> ShowS

show :: Mark -> String

showList :: [Mark] -> ShowS

data Space

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.

Constructors

Normal

A normal space that can be turned into a newline for displaying.

Nbsp

A non breakable space, it cannot be turned into a newline.

None

No space at all.

Instances

Eq Space

Methods

(==) :: Space -> Space -> Bool

(/=) :: Space -> Space -> Bool

Ord Space

Methods

compare :: Space -> Space -> Ordering

(<) :: Space -> Space -> Bool

(<=) :: Space -> Space -> Bool

(>) :: Space -> Space -> Bool

(>=) :: Space -> Space -> Bool

max :: Space -> Space -> Space

min :: Space -> Space -> Space