-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A markup parser.
--
-- A markup parser and printer, from and to strict bytestrings, optimised
-- for speed.
@package markup-parse
@version 0.0.0.2
-- | Various flatparse helpers and combinators.
module MarkupParse.FlatParse
-- | Warnings covering leftovers, Errs and Fail
--
--
-- >>> runParserWarn ws " x"
-- These (ParserLeftover "x") ' '
--
--
--
-- >>> runParserWarn ws "x"
-- This ParserUncaught
--
--
--
-- >>> runParserWarn (ws `cut` "no whitespace") "x"
-- This (ParserError "no whitespace")
--
data ParserWarning
ParserLeftover :: ByteString -> ParserWarning
ParserError :: String -> ParserWarning
ParserUncaught :: ParserWarning
-- | run a Parser, throwing away leftovers. Nothing on Fail or
-- Err.
--
--
-- >>> runParserMaybe ws "x"
-- Nothing
--
--
--
-- >>> runParserMaybe ws " x"
-- Just ' '
--
runParserMaybe :: Parser e a -> ByteString -> Maybe a
-- | run a Parser, throwing away leftovers. Returns Left on Fail or
-- Err.
--
--
-- >>> runParserEither ws " x"
-- Right ' '
--
runParserEither :: Parser String a -> ByteString -> Either String a
-- | Run parser, returning leftovers and errors as ParserWarnings.
--
--
-- >>> runParserWarn ws " "
-- That ' '
--
--
--
-- >>> runParserWarn ws "x"
-- This ParserUncaught
--
--
--
-- >>> runParserWarn ws " x"
-- These (ParserLeftover "x") ' '
--
runParserWarn :: Parser String a -> ByteString -> These ParserWarning a
-- | Run parser, discards leftovers & throws an error on failure.
--
--
-- >>> runParser_ ws " "
-- ' '
--
--
--
-- >>> runParser_ ws "x"
-- *** Exception: uncaught parse error
-- ...
--
runParser_ :: Parser String a -> ByteString -> a
-- | \n \t \f \r and space
isWhitespace :: Char -> Bool
-- | Consume whitespace.
--
--
-- >>> runParser ws_ " \nx"
-- OK () "x"
--
--
--
-- >>> runParser ws_ "x"
-- OK () "x"
--
ws_ :: Parser e ()
-- | single whitespace
--
--
-- >>> runParser ws " \nx"
-- OK ' ' "\nx"
--
ws :: Parser e Char
-- | multiple whitespace
--
--
-- >>> runParser wss " \nx"
-- OK " \n" "x"
--
--
--
-- >>> runParser wss "x"
-- Fail
--
wss :: Parser e ByteString
-- | Parse whilst not a specific character
--
--
-- >>> runParser (nota 'x') "abcxyz"
-- OK "abc" "xyz"
--
nota :: Char -> Parser e ByteString
-- | Parse whilst satisfying a predicate.
--
--
-- >>> runParser (isa (=='x')) "xxxabc"
-- OK "xxx" "abc"
--
isa :: (Char -> Bool) -> Parser e ByteString
-- | single quote
--
--
-- >>> runParserMaybe sq "'"
-- Just ()
--
sq :: ParserT st e ()
-- | double quote
--
--
-- >>> runParserMaybe dq "\""
-- Just ()
--
dq :: ParserT st e ()
-- | A double-quoted string.
wrappedDq :: Parser b ByteString
-- | A single-quoted string.
wrappedSq :: Parser b ByteString
-- | A single-quoted or double-quoted string.
--
--
-- >>> runParserMaybe wrappedQ "\"quoted\""
-- Just "quoted"
--
--
--
-- >>> runParserMaybe wrappedQ "'quoted'"
-- Just "quoted"
--
wrappedQ :: Parser e ByteString
-- | A single-quoted or double-quoted wrapped parser.
--
--
-- >>> runParser (wrappedQNoGuard (many $ satisfy (/= '"'))) "\"name\""
-- OK "name" ""
--
--
-- Will consume quotes if the underlying parser does.
--
--
-- >>> runParser (wrappedQNoGuard (many anyChar)) "\"name\""
-- Fail
--
wrappedQNoGuard :: Parser e a -> Parser e a
-- | xml production [25]
--
--
-- >>> runParserMaybe eq " = "
-- Just ()
--
--
--
-- >>> runParserMaybe eq "="
-- Just ()
--
eq :: Parser e ()
-- | some with a separator
--
--
-- >>> runParser (sep ws (many (satisfy (/= ' ')))) "a b c"
-- OK ["a","b","c"] ""
--
sep :: Parser e s -> Parser e a -> Parser e [a]
-- | parser bracketed by two other parsers
--
--
-- >>> runParser (bracketed ($(char '[')) ($(char ']')) (many (satisfy (/= ']')))) "[bracketed]"
-- OK "bracketed" ""
--
bracketed :: Parser e b -> Parser e b -> Parser e a -> Parser e a
-- | Bracketed by square brackets.
--
--
-- >>> runParser bracketedSB "[bracketed]"
-- OK "bracketed" ""
--
bracketedSB :: Parser e [Char]
-- | parser wrapped by another parser
--
--
-- >>> runParser (wrapped ($(char '"')) (many (satisfy (/= '"')))) "\"wrapped\""
-- OK "wrapped" ""
--
wrapped :: Parser e () -> Parser e a -> Parser e a
-- | A single digit
--
-- runParserMaybe digit "5" Just 5
digit :: Parser e Int
-- | (unsigned) Int parser
--
--
-- >>> runParserMaybe int "567"
-- Just 567
--
int :: Parser e Int
-- |
-- >>> runParser double "1.234x"
-- OK 1.234 "x"
--
--
--
-- >>> runParser double "."
-- Fail
--
--
--
-- >>> runParser double "123"
-- OK 123.0 ""
--
--
--
-- >>> runParser double ".123"
-- OK 0.123 ""
--
--
--
-- >>> runParser double "123."
-- OK 123.0 ""
--
double :: Parser e Double
-- |
-- >>> runParser (signed double) "-1.234x"
-- OK (-1.234) "x"
--
signed :: Num b => Parser e b -> Parser e b
-- | byteStringOf but using withSpan internally. Doesn't seems
-- faster...
byteStringOf' :: Parser e a -> Parser e ByteString
instance Control.DeepSeq.NFData MarkupParse.FlatParse.ParserWarning
instance GHC.Generics.Generic MarkupParse.FlatParse.ParserWarning
instance GHC.Classes.Ord MarkupParse.FlatParse.ParserWarning
instance GHC.Show.Show MarkupParse.FlatParse.ParserWarning
instance GHC.Classes.Eq MarkupParse.FlatParse.ParserWarning
-- | A Markup parser and printer of strict bytestrings.
-- Markup is a representation of data such as HTML, SVG or XML but
-- the parsing is sub-standard.
module MarkupParse
-- | A Tree list of markup Tokens
--
--
-- >>> markup Html "<foo class=\"bar\">baz</foo>"
-- That (Markup {standard = Html, markupTree = [Node {rootLabel = StartTag "foo" [Attr "class" "bar"], subForest = [Node {rootLabel = Content "baz", subForest = []}]}]})
--
data Markup
Markup :: Standard -> [Tree Token] -> Markup
[standard] :: Markup -> Standard
[markupTree] :: Markup -> [Tree Token]
-- | From a parsing pov, Html & Xml (& Svg) are close enough that
-- they share a lot of parsing logic, so that parsing and printing just
-- need some tweaking.
--
-- The xml parsing logic is based on the XML productions found in
-- https://www.w3.org/TR/xml/
--
-- The html parsing was based on a reading of html-parse, but
-- ignores the various 'x00' to 'xfffd' & eof directives that form
-- part of the html standards.
data Standard
Html :: Standard
Xml :: Standard
-- | Convert bytestrings to Markup
--
--
-- >>> markup Html "<foo><br></foo><baz"
-- These [MarkupParser (ParserLeftover "<baz")] (Markup {standard = Html, markupTree = [Node {rootLabel = StartTag "foo" [], subForest = [Node {rootLabel = StartTag "br" [], subForest = []}]}]})
--
markup :: Standard -> ByteString -> These [MarkupWarning] Markup
-- | markup but errors on warnings.
markup_ :: Standard -> ByteString -> Markup
-- | Indented 0 puts newlines in between the tags.
data RenderStyle
Compact :: RenderStyle
Indented :: Int -> RenderStyle
-- | Convert Markup to bytestrings
--
--
-- >>> B.putStr $ markdown (Indented 4) (markup_ Html [i|<foo><br></foo>|])
-- <foo>
-- <br>
-- </foo>
--
markdown :: RenderStyle -> Markup -> ByteString
-- | concatenate sequential content, and normalize attributes; unwording
-- class values and removing duplicate attributes (taking last).
--
--
-- >>> B.putStr $ markdown Compact $ normalize (markup_ Xml [i|<foo class="a" class="b" bar="first" bar="last"/>|])
-- <foo bar="last" class="a b"/>
--
normalize :: Markup -> Markup
-- | Check for well-formedness and rerturn warnings encountered.
--
--
-- >>> wellFormed $ Markup Html [Node (Comment "") [], Node (EndTag "foo") [], Node (EmptyElemTag "foo" []) [Node (Content "bar") []], Node (EmptyElemTag "foo" []) []]
-- [EmptyContent,EndTagInTree,LeafWithChildren,BadEmptyElemTag]
--
wellFormed :: Markup -> [MarkupWarning]
-- | Are the trees in the markup well-formed?
isWellFormed :: Markup -> Bool
-- | markup-parse generally tries to continue on parse errors, and return
-- what has/can still be parsed, together with any warnings.
data MarkupWarning
-- | A tag ending with "/>" that is not an element of selfClosers
-- (Html only).
BadEmptyElemTag :: MarkupWarning
-- | A tag ending with "/>" that has children. Cannot happen in the
-- parsing phase.
SelfCloserWithChildren :: MarkupWarning
-- | Only a StartTag can have child tokens.
LeafWithChildren :: MarkupWarning
-- | A CloseTag with a different name to the currently open StartTag.
TagMismatch :: TagName -> TagName -> MarkupWarning
-- | An EndTag with no corresponding StartTag.
UnmatchedEndTag :: MarkupWarning
-- | An EndTag with corresponding StartTag.
UnclosedTag :: MarkupWarning
-- | An EndTag should never appear in Markup
EndTagInTree :: MarkupWarning
-- | Empty Content, Comment, Decl or Doctype
EmptyContent :: MarkupWarning
MarkupParser :: ParserWarning -> MarkupWarning
-- | The structure of many returning functions.
--
-- A common computation pipeline is to take advantage of the These
-- Monad instance eg
--
--
-- markup s bs = bs & (tokenize s >=> gather s) & second (Markup s)
--
type Result a = These [MarkupWarning] a
-- | Convert any warnings to an error
--
--
-- >>> resultError $ (tokenize Html) "<foo"
-- *** Exception: MarkupParser (ParserLeftover "<foo")
-- ...
--
resultError :: Result a -> a
-- | Returns Left on any warnings
--
--
-- >>> resultEither $ (tokenize Html) "<foo><baz"
-- Left [MarkupParser (ParserLeftover "<baz")]
--
resultEither :: Result a -> Either [MarkupWarning] a
-- | Returns results if any, ignoring warnings.
--
--
-- >>> resultMaybe $ (tokenize Html) "<foo><baz"
-- Just [StartTag "foo" []]
--
resultMaybe :: Result a -> Maybe a
-- | Name of token
type TagName = ByteString
-- | Parse a tag name. Each standard is slightly different.
name :: Standard -> Parser e ByteString
-- | Html tags that self-close
selfClosers :: [TagName]
-- | Name of an attribute.
type AttrName = ByteString
-- | Value of an attribute. "" is equivalent to true with respect to
-- boolean attributes.
type AttrValue = ByteString
-- | An attribute of a tag
--
-- In parsing, boolean attributes, which are not required to have a value
-- in HTML, will be set a value of "", which is ok. But this will then be
-- rendered.
--
--
-- >>> detokenize Html <$> tokenize_ Html [i|<input checked>|]
-- ["<input checked=\"\">"]
--
data Attr
Attr :: !AttrName -> !AttrValue -> Attr
-- | Parse attributions
attrs :: Standard -> Parser a [Attr]
-- | A Markup token
--
--
-- >>> runParser_ (many (token Html)) [i|<foo>content</foo>|]
-- [StartTag "foo" [],Content "content",EndTag "foo"]
--
--
--
-- >>> runParser_ (token Xml) [i|<foo/>|]
-- EmptyElemTag "foo" []
--
--
--
-- >>> runParser_ (token Html) "<!-- Comment -->"
-- Comment " Comment "
--
--
--
-- >>> runParser_ (token Xml) [i|<?xml version="1.0" encoding="UTF-8"?>|]
-- Decl "xml version=\"1.0\" encoding=\"UTF-8\""
--
--
--
-- >>> runParser_ (token Html) "<!DOCTYPE html>"
-- Doctype "DOCTYPE html"
--
--
--
-- >>> runParser_ (token Xml) "<!DOCTYPE foo [ declarations ]>"
-- Doctype "DOCTYPE foo [ declarations ]"
--
--
--
-- >>> runParser (token Html) [i|<foo a="a" b="b" c=c check>|]
-- OK (StartTag "foo" [Attr "a" "a",Attr "b" "b",Attr "c" "c",Attr "check" ""]) ""
--
--
--
-- >>> runParser (token Xml) [i|<foo a="a" b="b" c=c check>|]
-- Fail
--
data Token
-- | A start tag.
-- https://developer.mozilla.org/en-US/docs/Glossary/Tag
StartTag :: !TagName -> ![Attr] -> Token
-- | An empty element tag. Optional for XML and kind of not allowed in
-- HTML.
EmptyElemTag :: !TagName -> ![Attr] -> Token
-- | A closing tag.
EndTag :: !TagName -> Token
-- | The content between tags.
Content :: !ByteString -> Token
-- | Contents of a comment.
Comment :: !ByteString -> Token
-- | Contents of a declaration
Decl :: !ByteString -> Token
-- | Contents of a doctype declaration.
Doctype :: !ByteString -> Token
-- | Parse a bytestring into tokens
--
--
-- >>> tokenize Html [i|<foo>content</foo>|]
-- That [StartTag "foo" [],Content "content",EndTag "foo"]
--
tokenize :: Standard -> ByteString -> These [MarkupWarning] [Token]
-- | tokenize but errors on warnings.
tokenize_ :: Standard -> ByteString -> [Token]
-- | A flatparse Token parser.
--
--
-- >>> runParser (token Html) "<foo>content</foo>"
-- OK (StartTag "foo" []) "content</foo>"
--
token :: Standard -> Parser String Token
-- | bytestring representation of Token.
--
--
-- >>> detokenize Html (StartTag "foo" [])
-- "<foo>"
--
detokenize :: Standard -> Token -> ByteString
-- | Gather together token trees from a token list, placing child elements
-- in nodes and removing EndTags.
--
--
-- >>> gather Html =<< tokenize Html "<foo class=\"bar\">baz</foo>"
-- That [Node {rootLabel = StartTag "foo" [Attr "class" "bar"], subForest = [Node {rootLabel = Content "baz", subForest = []}]}]
--
gather :: Standard -> [Token] -> These [MarkupWarning] [Tree Token]
-- | gather but errors on warnings.
gather_ :: Standard -> [Token] -> [Tree Token]
-- | Convert a markup into a token list, adding end tags.
--
--
-- >>> degather =<< markup Html "<foo class=\"bar\">baz</foo>"
-- That [StartTag "foo" [Attr "class" "bar"],Content "baz",EndTag "foo"]
--
degather :: Markup -> These [MarkupWarning] [Token]
-- | degather but errors on warning
degather_ :: Markup -> [Token]
-- | xml production [24]
xmlVersionInfo :: Parser e ByteString
-- | xml production [80]
xmlEncodingDecl :: Parser e ByteString
-- | Xml production [32]
xmlStandalone :: Parser e ByteString
-- | xml production [26]
xmlVersionNum :: Parser e ByteString
-- | xml production [81]
xmlEncName :: Parser e ByteString
-- | Xml yes/no
xmlYesNo :: Parser e ByteString
instance Control.DeepSeq.NFData MarkupParse.Standard
instance GHC.Generics.Generic MarkupParse.Standard
instance GHC.Classes.Ord MarkupParse.Standard
instance GHC.Show.Show MarkupParse.Standard
instance GHC.Classes.Eq MarkupParse.Standard
instance Control.DeepSeq.NFData MarkupParse.MarkupWarning
instance GHC.Generics.Generic MarkupParse.MarkupWarning
instance GHC.Classes.Ord MarkupParse.MarkupWarning
instance GHC.Show.Show MarkupParse.MarkupWarning
instance GHC.Classes.Eq MarkupParse.MarkupWarning
instance GHC.Classes.Ord MarkupParse.Attr
instance GHC.Classes.Eq MarkupParse.Attr
instance GHC.Show.Show MarkupParse.Attr
instance GHC.Generics.Generic MarkupParse.Attr
instance GHC.Generics.Generic MarkupParse.Token
instance GHC.Classes.Eq MarkupParse.Token
instance GHC.Classes.Ord MarkupParse.Token
instance GHC.Show.Show MarkupParse.Token
instance Control.DeepSeq.NFData MarkupParse.Markup
instance GHC.Generics.Generic MarkupParse.Markup
instance GHC.Classes.Ord MarkupParse.Markup
instance GHC.Classes.Eq MarkupParse.Markup
instance GHC.Show.Show MarkupParse.Markup
instance GHC.Generics.Generic MarkupParse.RenderStyle
instance GHC.Show.Show MarkupParse.RenderStyle
instance GHC.Classes.Eq MarkupParse.RenderStyle
instance Data.TreeDiff.Class.ToExpr MarkupParse.Markup
instance Control.DeepSeq.NFData MarkupParse.Token
instance Data.TreeDiff.Class.ToExpr MarkupParse.Token
instance Control.DeepSeq.NFData MarkupParse.Attr
instance Data.TreeDiff.Class.ToExpr MarkupParse.Attr
instance Data.TreeDiff.Class.ToExpr MarkupParse.Standard
-- | A patch function for tree-diff.
module MarkupParse.Patch
-- | ediff with unchanged sections filtered out
--
--
-- >>> show $ ansiWlEditExpr <$> patch [1, 2, 3, 5] [0, 1, 2, 4, 6]
-- "Just [+0, -3, +4, -5, +6]"
--
patch :: ToExpr a => a -> a -> Maybe (Edit EditExpr)
-- | compare a markup file with a round-trip transformation.
goldenPatch :: ToExpr a => (FilePath -> IO a) -> (a -> a) -> FilePath -> TestTree