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


-- | Strict markdown processor for writers
--   
--   Strict markdown processor for writers.
@package mmark
@version 0.0.6.2


-- | MMark (read “em-mark”) is a strict markdown processor for writers.
--   “Strict” means that not every input is considered valid markdown
--   document and parse errors are possible and even desirable, because
--   they allow us to spot markup issues without searching for them in
--   rendered document. If a markdown document passes MMark parser, then
--   it'll likely produce HTML without quirks. This feature makes it a good
--   choice for writers and bloggers.
--   
--   <h3>MMark and Common Mark</h3>
--   
--   MMark mostly tries to follow the Common Mark specification as given
--   here:
--   
--   <a>https://spec.commonmark.org/0.28/</a>
--   
--   However, due to the fact that we do not allow inputs that do not make
--   sense, and also try to guard against common mistakes (like writing
--   <tt>##My header</tt> and having it rendered as a paragraph starting
--   with hashes) MMark obviously can't follow the specification precisely.
--   In particular, parsing of inlines differs considerably from Common
--   Mark.
--   
--   Another difference between Common Mark and MMark is that the latter
--   supports more (pun alert) common markdown extensions out-of-the-box.
--   In particular, MMark supports:
--   
--   <ul>
--   <li>parsing of an optional YAML block</li>
--   <li>strikeout using <tt>~~this~~</tt> syntax</li>
--   <li>superscript using <tt>^this^</tt> syntax</li>
--   <li>subscript using <tt>~this~</tt> syntax</li>
--   <li>automatic assignment of ids to headers</li>
--   <li>pipe tables (as on GitHub)</li>
--   </ul>
--   
--   One does not need to enable or tweak anything for these to work, they
--   are built-in features.
--   
--   The readme contains a more detailed description of differences between
--   Common Mark and MMark.
--   
--   <h3>How to use the library</h3>
--   
--   The module is intended to be imported qualified:
--   
--   <pre>
--   import Text.MMark (MMark)
--   import qualified Text.MMark as MMark
--   </pre>
--   
--   Working with MMark happens in three stages:
--   
--   <ol>
--   <li>Parsing of markdown document.</li>
--   <li>Applying extensions, which optionally may require scanning of
--   previously parsed document (for example to build a table of
--   contents).</li>
--   <li>Rendering of HTML document.</li>
--   </ol>
--   
--   The structure of the documentation below corresponds to these stages
--   and should clarify the details.
--   
--   <h3>“Getting started” example</h3>
--   
--   Here is a complete example of a program that reads a markdown file
--   named <tt>"input.md"</tt> and outputs an HTML file named
--   <tt>"output.html"</tt>:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   module Main (main) where
--   
--   import qualified Data.Text.IO      as T
--   import qualified Data.Text.Lazy.IO as TL
--   import qualified Lucid             as L
--   import qualified Text.MMark        as MMark
--   import qualified Text.Megaparsec   as M
--   
--   main :: IO ()
--   main = do
--     let input = "input.md"
--     txt &lt;- T.readFile input -- (1)
--     case MMark.parse input txt of -- (2)
--       Left bundle -&gt; putStrLn (M.errorBundlePretty bundle) -- (3)
--       Right r -&gt; TL.writeFile "output.html" -- (6)
--         . L.renderText -- (5)
--         . MMark.render -- (4)
--         $ r
--   </pre>
--   
--   Let's break it down:
--   
--   <ol>
--   <li>We read a source markdown file as strict <tt>Text</tt>.</li>
--   <li>The source is fed into the <a>parse</a> function which does the
--   parsing. It can either fail with a collection of parse errors or
--   succeed returning a value of the opaque <a>MMark</a> type.</li>
--   <li>If parsing fails, we pretty-print the parse errors with
--   <a>errorBundlePretty</a>.</li>
--   <li>Then we just render the document with <a>render</a> first to
--   Lucid's <tt><a>Html</a> ()</tt>.</li>
--   <li>…and then to lazy <a>Text</a> with <a>renderText</a>.</li>
--   <li>Finally we write the result as <tt>"output.html"</tt>.</li>
--   </ol>
--   
--   <h3>Other modules of interest</h3>
--   
--   The <a>Text.MMark</a> module contains all the “core” functionality one
--   may need. However, one of the main selling points of MMark is that
--   it's possible to write your own extensions which stay highly
--   composable (if done right), so proliferation of third-party extensions
--   is to be expected and encouraged. To write an extension of your own
--   import the <a>Text.MMark.Extension</a> module, which has some
--   documentation focusing on extension writing.
module Text.MMark

-- | Representation of complete markdown document. You can't look inside of
--   <a>MMark</a> on purpose. The only way to influence an <a>MMark</a>
--   document you obtain as a result of parsing is via the extension
--   mechanism.
data MMark

-- | MMark custom parse errors.
data MMarkErr

-- | YAML error that occurred during parsing of a YAML block
YamlParseError :: String -> MMarkErr

-- | This delimiter run should be in left- or right- flanking position
NonFlankingDelimiterRun :: NonEmpty Char -> MMarkErr

-- | Ordered list start numbers must be nine digits or less
ListStartIndexTooBig :: Word -> MMarkErr

-- | The index in an ordered list is out of order, first number is the
--   actual index we ran into, the second number is the expected index
ListIndexOutOfOrder :: Word -> Word -> MMarkErr

-- | Duplicate reference definitions are not allowed
DuplicateReferenceDefinition :: Text -> MMarkErr

-- | Could not find this reference definition, the second argument is the
--   collection of close names (typo corrections)
CouldNotFindReferenceDefinition :: Text -> [Text] -> MMarkErr

-- | This numeric character is invalid
InvalidNumericCharacter :: Int -> MMarkErr

-- | Unknown HTML5 entity name
UnknownHtmlEntityName :: Text -> MMarkErr

-- | Parse a markdown document in the form of a strict <a>Text</a> value
--   and either report parse errors or return an <a>MMark</a> document.
parse :: FilePath -> Text -> Either (ParseErrorBundle Text MMarkErr) MMark

-- | An extension. You can apply extensions with <a>useExtension</a> and
--   <a>useExtensions</a> functions. The <a>Text.MMark.Extension</a> module
--   provides tools for writing your own extensions.
--   
--   Note that <a>Extension</a> is an instance of <a>Semigroup</a> and
--   <a>Monoid</a>, i.e. you can combine several extensions into one. Since
--   the <tt>(<a>&lt;&gt;</a>)</tt> operator is right-associative and
--   <a>mconcat</a> is a right fold under the hood, the expression
--   
--   <pre>
--   l &lt;&gt; r
--   </pre>
--   
--   means that the extension <tt>r</tt> will be applied before the
--   extension <tt>l</tt>, similar to how <a>Endo</a> works. This may seem
--   counter-intuitive, but only with this logic we get consistency of
--   ordering with more complex expressions:
--   
--   <pre>
--   e2 &lt;&gt; e1 &lt;&gt; e0 == e2 &lt;&gt; (e1 &lt;&gt; e0)
--   </pre>
--   
--   Here, <tt>e0</tt> will be applied first, then <tt>e1</tt>, then
--   <tt>e2</tt>. The same applies to expressions involving
--   <a>mconcat</a>—extensions closer to beginning of the list passed to
--   <a>mconcat</a> will be applied later.
data Extension

-- | Apply an <a>Extension</a> to an <a>MMark</a> document. The order in
--   which you apply <a>Extension</a>s <i>does matter</i>. Extensions you
--   apply first take effect first. The extension system is designed in
--   such a way that in many cases the order doesn't matter, but sometimes
--   the difference is important.
useExtension :: Extension -> MMark -> MMark

-- | Apply several <a>Extension</a>s to an <a>MMark</a> document.
--   
--   This is a simple shortcut:
--   
--   <pre>
--   useExtensions exts = useExtension (mconcat exts)
--   </pre>
--   
--   As mentioned in the docs for <a>useExtension</a>, the order in which
--   you apply extensions matters. Extensions closer to beginning of the
--   list are applied later, i.e. the last extension in the list is applied
--   first.
useExtensions :: [Extension] -> MMark -> MMark

-- | Scan an <a>MMark</a> document efficiently in one pass. This uses the
--   excellent <a>Fold</a> type, which see.
--   
--   Take a look at the <a>Text.MMark.Extension</a> module if you want to
--   create scanners of your own.
runScanner :: MMark -> Fold Bni a -> a

-- | Like <a>runScanner</a>, but allows to run scanners with monadic
--   context.
--   
--   To bring <a>Fold</a> and <a>FoldM</a> types to the “least common
--   denominator” use <a>generalize</a> and <a>simplify</a>.
runScannerM :: Monad m => MMark -> FoldM m Bni a -> m a

-- | Extract contents of an optional YAML block that may have been parsed.
projectYaml :: MMark -> Maybe Value

-- | Render a <a>MMark</a> markdown document. You can then render
--   <tt><a>Html</a> ()</tt> to various things:
--   
--   <ul>
--   <li>to lazy <a>Text</a> with <a>renderText</a></li>
--   <li>to lazy <a>ByteString</a> with <a>renderBS</a></li>
--   <li>directly to file with <a>renderToFile</a></li>
--   </ul>
render :: MMark -> Html ()


-- | This module provides building blocks for extension creation.
--   
--   We suggest using a qualified import, like this:
--   
--   <pre>
--   import Text.MMark.Extension (Bni, Block (..), Inline (..))
--   import qualified Text.MMark.Extension as Ext
--   </pre>
--   
--   <h3>Philosophy of MMark extensions</h3>
--   
--   The extension system is guided by the following goals:
--   
--   <ol>
--   <li>Make it powerful, so users can write interesting extensions.</li>
--   <li>Make it efficient, so every type of transformation is only applied
--   once and the number of traversals of the syntax tree stays constant no
--   matter how many extensions the user chooses to use and how complex
--   they are.</li>
--   <li>Make it easy to write extensions that are very focused in what
--   they do and do not interfere with each other in weird and unexpected
--   ways.</li>
--   </ol>
--   
--   I ruled out allowing users to mess with AST directly pretty quickly
--   because it would be against the points 2 and 3. Instead, there are
--   four kinds of extension-producing functions. They correspond
--   internally to four functions that are applied to the parsed document
--   in turn:
--   
--   <ul>
--   <li><a>blockTrans</a> is applied first, as it's quite general and can
--   change block-level structure of document as well as inline-level
--   structure.</li>
--   <li><a>inlineTrans</a> is applied to every inline in the document
--   obtained in the previous step.</li>
--   <li><a>inlineRender</a> is applied to every inline; this function
--   produces HTML rendition of the inlines and we also preserve the
--   original inlines so <a>blockRender</a> can look at it (see
--   <a>Ois</a>).</li>
--   <li><a>blockRender</a> is applied to every block to obtain HTML
--   rendition of the whole document.</li>
--   </ul>
--   
--   When one combines different extensions, extensions of the same kind
--   get fused together into a single function. This allows for faster
--   processing and constant number of traversals over AST in the end.
--   
--   One could note that the current design does not allow prepending or
--   appending new elements to the AST. This is a limitation by design
--   because we try to make the order in which extensions are applied not
--   important (it's not always possible, though). Thus, if we want to e.g.
--   insert a table of contents into a document, we need to do so by
--   transforming an already existing element, such as code block with a
--   special info string (this is how the extension works in the
--   <tt>mmark-ext</tt> package).
--   
--   Another limitation by design is that extensions cannot change how the
--   parser works. I find endless syntax-changing (or syntax-augmenting, if
--   you will) extensions (as implemented by Pandoc for example) ugly,
--   because they erode the familiar markdown syntax and turn it into a
--   monstrosity. In MMark we choose a different path of re-purposing
--   existing markdown constructs, adding special meaning to them in
--   certain situations.
--   
--   <h3>Room for improvement</h3>
--   
--   One flaw of the current system is that it does not allow reporting
--   errors, so we have to silently fallback to some default behavior when
--   we can't apply an extension in a meaningful way. Such
--   extension-produced errors obviously should contain their positions in
--   the original markdown input, which would require us storing this
--   information in AST in some way. I'm not sure if the additional
--   complexity (and possible performance trade-offs) is really worth it,
--   so it hasn't been implemented so far.
module Text.MMark.Extension

-- | An extension. You can apply extensions with <a>useExtension</a> and
--   <a>useExtensions</a> functions. The <a>Text.MMark.Extension</a> module
--   provides tools for writing your own extensions.
--   
--   Note that <a>Extension</a> is an instance of <a>Semigroup</a> and
--   <a>Monoid</a>, i.e. you can combine several extensions into one. Since
--   the <tt>(<a>&lt;&gt;</a>)</tt> operator is right-associative and
--   <a>mconcat</a> is a right fold under the hood, the expression
--   
--   <pre>
--   l &lt;&gt; r
--   </pre>
--   
--   means that the extension <tt>r</tt> will be applied before the
--   extension <tt>l</tt>, similar to how <a>Endo</a> works. This may seem
--   counter-intuitive, but only with this logic we get consistency of
--   ordering with more complex expressions:
--   
--   <pre>
--   e2 &lt;&gt; e1 &lt;&gt; e0 == e2 &lt;&gt; (e1 &lt;&gt; e0)
--   </pre>
--   
--   Here, <tt>e0</tt> will be applied first, then <tt>e1</tt>, then
--   <tt>e2</tt>. The same applies to expressions involving
--   <a>mconcat</a>—extensions closer to beginning of the list passed to
--   <a>mconcat</a> will be applied later.
data Extension

-- | A shortcut for the frequently used type <tt><a>Block</a>
--   (<a>NonEmpty</a> <a>Inline</a>)</tt>.
type Bni = Block (NonEmpty Inline)

-- | 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 <a>Inline</a>.
--   
--   We can divide blocks into two types: container blocks, which can
--   contain other blocks, and leaf blocks, which cannot.
data Block a

-- | Thematic break, leaf block
ThematicBreak :: Block a

-- | Heading (level 1), leaf block
Heading1 :: a -> Block a

-- | Heading (level 2), leaf block
Heading2 :: a -> Block a

-- | Heading (level 3), leaf block
Heading3 :: a -> Block a

-- | Heading (level 4), leaf block
Heading4 :: a -> Block a

-- | Heading (level 5), leaf block
Heading5 :: a -> Block a

-- | Heading (level 6), leaf block
Heading6 :: a -> Block a

-- | Code block, leaf block with info string and contents
CodeBlock :: Maybe Text -> Text -> Block a

-- | Naked content, without an enclosing tag
Naked :: a -> Block a

-- | Paragraph, leaf block
Paragraph :: a -> Block a

-- | Blockquote container block
Blockquote :: [Block a] -> Block a

-- | Ordered list (<a>Word</a> is the start index), container block
OrderedList :: Word -> NonEmpty [Block a] -> Block a

-- | Unordered list, container block
UnorderedList :: NonEmpty [Block a] -> Block a

-- | Table, first argument is the alignment options, then we have a
--   <a>NonEmpty</a> list of rows, where every row is a <a>NonEmpty</a>
--   list of cells, where every cell is an <tt>a</tt> thing.
--   
--   The first row is always the header row, because pipe-tables that we
--   support cannot lack a header row.
Table :: NonEmpty CellAlign -> NonEmpty (NonEmpty a) -> Block a

-- | Options for cell alignment in tables.
data CellAlign

-- | No specific alignment specified
CellAlignDefault :: CellAlign

-- | Left-alignment
CellAlignLeft :: CellAlign

-- | Right-alignment
CellAlignRight :: CellAlign

-- | Center-alignment
CellAlignCenter :: CellAlign

-- | Create an extension that performs a transformation on <a>Block</a>s of
--   markdown document. Since a block may contain other blocks we choose to
--   perform transformations from the most deeply nested blocks moving
--   upwards. This has the benefit that the result of any transformation is
--   final in the sense that sub-elements of resulting block won't be
--   traversed again.
blockTrans :: (Bni -> Bni) -> Extension

-- | Create an extension that replaces or augments rendering of
--   <a>Block</a>s of markdown document. The argument of <a>blockRender</a>
--   will be given the rendering function constructed so far
--   <tt><a>Block</a> (<a>Ois</a>, <a>Html</a> ()) -&gt; <a>Html</a>
--   ()</tt> as well as an actual block to render—<tt><a>Block</a>
--   (<a>Ois</a>, <a>Html</a> ())</tt>. The user can then decide whether to
--   replace/reuse that function to get the final rendering of the type
--   <tt><a>Html</a> ()</tt>.
--   
--   The argument of <a>blockRender</a> can also be thought of as a
--   function that transforms the rendering function constructed so far:
--   
--   <pre>
--   (Block (Ois, Html ()) -&gt; Html ()) -&gt; (Block (Ois, Html ()) -&gt; Html ())
--   </pre>
--   
--   See also: <a>Ois</a> and <a>getOis</a>.
blockRender :: ((Block (Ois, Html ()) -> Html ()) -> Block (Ois, Html ()) -> Html ()) -> Extension

-- | A wrapper for “original 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 <a>Ois</a> is not
--   possible because the user cannot construct a value of the <a>Ois</a>
--   type, he/she can only inspect it with <a>getOis</a>.
data Ois

-- | Project <tt><a>NonEmpty</a> <a>Inline</a></tt> from <a>Ois</a>.
getOis :: Ois -> NonEmpty Inline

-- | Inline markdown content.
data Inline

-- | Plain text
Plain :: Text -> Inline

-- | Line break (hard)
LineBreak :: Inline

-- | Emphasis
Emphasis :: NonEmpty Inline -> Inline

-- | Strong emphasis
Strong :: NonEmpty Inline -> Inline

-- | Strikeout
Strikeout :: NonEmpty Inline -> Inline

-- | Subscript
Subscript :: NonEmpty Inline -> Inline

-- | Superscript
Superscript :: NonEmpty Inline -> Inline

-- | Code span
CodeSpan :: Text -> Inline

-- | Link with text, destination, and optionally title
Link :: NonEmpty Inline -> URI -> Maybe Text -> Inline

-- | Image with description, URL, and optionally title
Image :: NonEmpty Inline -> URI -> Maybe Text -> Inline

-- | Create an extension that performs a transformation on <a>Inline</a>
--   components in entire markdown document. Similarly to <a>blockTrans</a>
--   the transformation is applied from the most deeply nested elements
--   moving upwards.
inlineTrans :: (Inline -> Inline) -> Extension

-- | Create an extension that replaces or augments rendering of
--   <a>Inline</a>s of markdown document. This works like
--   <a>blockRender</a>.
inlineRender :: ((Inline -> Html ()) -> Inline -> Html ()) -> Extension

-- | Create a <a>Fold</a> from an initial state and a folding function.
scanner :: a -> (a -> Bni -> a) -> Fold Bni a

-- | Create a <a>FoldM</a> from an initial state and a folding function
--   operating in monadic context.
scannerM :: Monad m => m a -> (a -> Bni -> m a) -> FoldM m Bni a

-- | Convert a non-empty collection of <a>Inline</a>s into their plain text
--   representation. This is used e.g. to render image descriptions.
asPlainText :: NonEmpty Inline -> Text

-- | Generate value of id attribute for a given header. This is used during
--   rendering and also can be used to get id of a header for linking to it
--   in extensions.
--   
--   See also: <a>headerFragment</a>.
headerId :: NonEmpty Inline -> Text

-- | Generate a <a>URI</a> containing only a fragment from its textual
--   representation. Useful for getting URL from id of a header.
headerFragment :: Text -> URI
