Copyright | © 2017–2018 Mark Karpov |
---|---|
License | BSD 3 clause |
Maintainer | Mark Karpov <markkarpov92@gmail.com> |
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
This module provides building blocks for extension creation.
We suggest using a qualified import, like this:
import Text.MMark.Extension (Bni, Block (..), Inline (..)) import qualified Text.MMark.Extension as Ext
Details about extensions
There are four kinds of extension-producing functions. They correspond internally to four functions that are applied to the parsed document in turn:
blockTrans
is applied first, as it's quite general and can change block-level structure of document as well as inline-level structure.inlineTrans
is applied to every inline in the document obtained in the previous step.inlineRender
is applied to every inline; this function produces HTML rendition of the inlines and we also preserve the original inline soblockRender
can look at it (sometimes it is useful).blockRender
is applied to every block to obtain HTML rendition of the whole document.
When one combines different extensions, extensions of the same kind get fused together into a single function. This allows for faster processing in the end.
- data Extension
- type Bni = Block (NonEmpty Inline)
- data Block a
- data CellAlign
- blockTrans :: (Bni -> Bni) -> Extension
- blockRender :: ((Block (Ois, Html ()) -> Html ()) -> Block (Ois, Html ()) -> Html ()) -> Extension
- data Ois
- getOis :: Ois -> NonEmpty Inline
- data Inline
- inlineTrans :: (Inline -> Inline) -> Extension
- inlineRender :: ((Inline -> Html ()) -> Inline -> Html ()) -> Extension
- scanner :: a -> (a -> Bni -> a) -> Fold Bni a
- scannerM :: Monad m => m a -> (a -> Bni -> m a) -> FoldM m Bni a
- asPlainText :: NonEmpty Inline -> Text
- headerId :: NonEmpty Inline -> Text
- headerFragment :: Text -> URI
Extension construction
An extension. You can apply extensions with useExtension
and
useExtensions
functions. The Text.MMark.Extension module provides
tools for extension creation.
Note that Extension
is an instance of Semigroup
and Monoid
, i.e.
you can combine several extensions into one. Since the (
operator
is right-associative and <>
)mconcat
is a right fold under the hood, the
expression
l <> r
means that the extension r
will be applied before the extension l
,
similar to how Endo
works. This may seem counter-intuitive, but only
with this logic we get consistency of ordering with more complex
expressions:
e2 <> e1 <> e0 == e2 <> (e1 <> e0)
Here, e0
will be applied first, then e1
, then e2
. The same applies
to expressions involving mconcat
—extensions closer to beginning of the
list passed to mconcat
will be applied later.
Block-level manipulation
We can think of a markdown document as a collection of
blocks—structural elements like paragraphs, block quotations, lists,
headings, thematic breaks, and code blocks. Some blocks (like block
quotes and list items) contain other blocks; others (like headings and
paragraphs) contain inline content, see Inline
.
We can divide blocks into two types: container blocks, which can contain other blocks, and leaf blocks, which cannot.
ThematicBreak | Thematic break, leaf block |
Heading1 a | Heading (level 1), leaf block |
Heading2 a | Heading (level 2), leaf block |
Heading3 a | Heading (level 3), leaf block |
Heading4 a | Heading (level 4), leaf block |
Heading5 a | Heading (level 5), leaf block |
Heading6 a | Heading (level 6), leaf block |
CodeBlock (Maybe Text) Text | Code block, leaf block with info string and contents |
Naked a | Naked content, without an enclosing tag |
Paragraph a | Paragraph, leaf block |
Blockquote [Block a] | Blockquote container block |
OrderedList Word (NonEmpty [Block a]) | Ordered list ( |
UnorderedList (NonEmpty [Block a]) | Unordered list, container block |
Table (NonEmpty CellAlign) (NonEmpty (NonEmpty a)) | Table, first argument is the alignment options, then we have a
The first row is always the header row, because pipe-tables that we support cannot lack a header row. Since: 0.0.4.0 |
Options for cell alignment in tables.
Since: 0.0.4.0
CellAlignDefault | No specific alignment specified |
CellAlignLeft | Left-alignment |
CellAlignRight | Right-alignment |
CellAlignCenter | Center-alignment |
blockTrans :: (Bni -> Bni) -> Extension Source #
Create an extension that performs a transformation on Block
s of
markdown document.
blockRender :: ((Block (Ois, Html ()) -> Html ()) -> Block (Ois, Html ()) -> Html ()) -> Extension Source #
Create an extension that replaces or augments rendering of Block
s of
markdown document. The argument of blockRender
will be given the
rendering function constructed so far
as well as an actual block to render—Block
(Ois
, Html
()) ->
Html
()
. The user can then decide whether to replace/reuse that function to
get the final rendering of the type Block
(Ois
, Html
())
.Html
()
The argument of blockRender
can also be thought of as a function that
transforms the rendering function constructed so far:
(Block (Ois, Html ()) -> Html ()) -> (Block (Ois, Html ()) -> Html ())
A wrapper for “originial inlines”. Source inlines are wrapped in this
during rendering of inline components and then it's available to block
render, but only for inspection. Altering of Ois
is not possible
because the user cannot construct a value of the Ois
type, she can only
inspect it with getOis
.
Inline-level manipulation
Inline markdown content.
Plain Text | Plain text |
LineBreak | Line break (hard) |
Emphasis (NonEmpty Inline) | Emphasis |
Strong (NonEmpty Inline) | Strong emphasis |
Strikeout (NonEmpty Inline) | Strikeout |
Subscript (NonEmpty Inline) | Subscript |
Superscript (NonEmpty Inline) | Superscript |
CodeSpan Text | Code span |
Link (NonEmpty Inline) URI (Maybe Text) | Link with text, destination, and optionally title |
Image (NonEmpty Inline) URI (Maybe Text) | Image with description, URL, and optionally title |
inlineTrans :: (Inline -> Inline) -> Extension Source #
Create an extension that performs a transformation on Inline
components in entire markdown document.
inlineRender :: ((Inline -> Html ()) -> Inline -> Html ()) -> Extension Source #
Create an extension that replaces or augments rendering of Inline
s of
markdown document. This works like blockRender
.
Scanner construction
Create a Fold
from an initial state and a folding function.
Create a FoldM
from an initial state and a folding function
operating in monadic context.
Since: 0.0.2.0
Utils
asPlainText :: NonEmpty Inline -> Text Source #
Convert a non-empty collection of Inline
s into their plain text
representation. This is used e.g. to render image descriptions.