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


-- | Library exposing some functionality of Haddock.
--   
--   Haddock is a documentation-generation tool for Haskell libraries.
--   These modules expose some functionality of it without pulling in the
--   GHC dependency. Please note that the API is likely to change so
--   specify upper bounds in your project if you can't release often. For
--   interacting with Haddock itself, see the ‘haddock’ package.
@package haddock-library
@version 1.4.3


-- | Exposes documentation data types used for (some) of Haddock.
module Documentation.Haddock.Types

-- | With the advent of <a>Version</a>, we may want to start attaching more
--   meta-data to comments. We make a structure for this ahead of time so
--   we don't have to gut half the core each time we want to add such info.
newtype Meta
Meta :: Maybe Version -> Meta
[_version] :: Meta -> Maybe Version
data MetaDoc mod id
MetaDoc :: Meta -> DocH mod id -> MetaDoc mod id
[_meta] :: MetaDoc mod id -> Meta
[_doc] :: MetaDoc mod id -> DocH mod id
overDoc :: (DocH a b -> DocH c d) -> MetaDoc a b -> MetaDoc c d
type Version = [Int]
data Hyperlink
Hyperlink :: String -> Maybe String -> Hyperlink
[hyperlinkUrl] :: Hyperlink -> String
[hyperlinkLabel] :: Hyperlink -> Maybe String
data Picture
Picture :: String -> Maybe String -> Picture
[pictureUri] :: Picture -> String
[pictureTitle] :: Picture -> Maybe String
data Header id
Header :: Int -> id -> Header id
[headerLevel] :: Header id -> Int
[headerTitle] :: Header id -> id
data Example
Example :: String -> [String] -> Example
[exampleExpression] :: Example -> String
[exampleResult] :: Example -> [String]
data DocH mod id
DocEmpty :: DocH mod id
DocAppend :: (DocH mod id) -> (DocH mod id) -> DocH mod id
DocString :: String -> DocH mod id
DocParagraph :: (DocH mod id) -> DocH mod id
DocIdentifier :: id -> DocH mod id
DocIdentifierUnchecked :: mod -> DocH mod id
DocModule :: String -> DocH mod id
DocWarning :: (DocH mod id) -> DocH mod id
DocEmphasis :: (DocH mod id) -> DocH mod id
DocMonospaced :: (DocH mod id) -> DocH mod id
DocBold :: (DocH mod id) -> DocH mod id
DocUnorderedList :: [DocH mod id] -> DocH mod id
DocOrderedList :: [DocH mod id] -> DocH mod id
DocDefList :: [(DocH mod id, DocH mod id)] -> DocH mod id
DocCodeBlock :: (DocH mod id) -> DocH mod id
DocHyperlink :: Hyperlink -> DocH mod id
DocPic :: Picture -> DocH mod id
DocMathInline :: String -> DocH mod id
DocMathDisplay :: String -> DocH mod id
DocAName :: String -> DocH mod id
DocProperty :: String -> DocH mod id
DocExamples :: [Example] -> DocH mod id
DocHeader :: (Header (DocH mod id)) -> DocH mod id
instance Data.Traversable.Traversable (Documentation.Haddock.Types.MetaDoc mod)
instance Data.Foldable.Foldable (Documentation.Haddock.Types.MetaDoc mod)
instance GHC.Base.Functor (Documentation.Haddock.Types.MetaDoc mod)
instance (GHC.Show.Show id, GHC.Show.Show mod) => GHC.Show.Show (Documentation.Haddock.Types.MetaDoc mod id)
instance (GHC.Classes.Eq id, GHC.Classes.Eq mod) => GHC.Classes.Eq (Documentation.Haddock.Types.MetaDoc mod id)
instance Data.Traversable.Traversable (Documentation.Haddock.Types.DocH mod)
instance Data.Foldable.Foldable (Documentation.Haddock.Types.DocH mod)
instance GHC.Base.Functor (Documentation.Haddock.Types.DocH mod)
instance (GHC.Show.Show id, GHC.Show.Show mod) => GHC.Show.Show (Documentation.Haddock.Types.DocH mod id)
instance (GHC.Classes.Eq id, GHC.Classes.Eq mod) => GHC.Classes.Eq (Documentation.Haddock.Types.DocH mod id)
instance GHC.Show.Show Documentation.Haddock.Types.Example
instance GHC.Classes.Eq Documentation.Haddock.Types.Example
instance Data.Traversable.Traversable Documentation.Haddock.Types.Header
instance Data.Foldable.Foldable Documentation.Haddock.Types.Header
instance GHC.Base.Functor Documentation.Haddock.Types.Header
instance GHC.Show.Show id => GHC.Show.Show (Documentation.Haddock.Types.Header id)
instance GHC.Classes.Eq id => GHC.Classes.Eq (Documentation.Haddock.Types.Header id)
instance GHC.Show.Show Documentation.Haddock.Types.Picture
instance GHC.Classes.Eq Documentation.Haddock.Types.Picture
instance GHC.Show.Show Documentation.Haddock.Types.Hyperlink
instance GHC.Classes.Eq Documentation.Haddock.Types.Hyperlink
instance GHC.Show.Show Documentation.Haddock.Types.Meta
instance GHC.Classes.Eq Documentation.Haddock.Types.Meta

module Documentation.Haddock.Doc
docParagraph :: DocH mod id -> DocH mod id
docAppend :: DocH mod id -> DocH mod id -> DocH mod id
docConcat :: [DocH mod id] -> DocH mod id

-- | Like <a>docConcat</a> but also joins the <a>Meta</a> info.
metaDocConcat :: [MetaDoc mod id] -> MetaDoc mod id

-- | We do something perhaps unexpected here and join the meta info in
--   ‘reverse’: this results in the metadata from the ‘latest’ paragraphs
--   taking precedence.
metaDocAppend :: MetaDoc mod id -> MetaDoc mod id -> MetaDoc mod id
emptyMetaDoc :: MetaDoc mod id

-- | This is not a monoidal append, it uses <a>&lt;|&gt;</a> for the
--   <a>_version</a>.
metaAppend :: Meta -> Meta -> Meta

-- | Concat using <a>metaAppend</a>.
metaConcat :: [Meta] -> Meta

module Documentation.Haddock.Parser.Monad
newtype ParserState
ParserState :: Maybe Version -> ParserState
[parserStateSince] :: ParserState -> Maybe Version
initialParserState :: ParserState
newtype Parser a
Parser :: (StateT ParserState Parser a) -> Parser a
parseOnly :: Parser a -> ByteString -> Either String (ParserState, a)
lift :: Parser a -> Parser a
setParserState :: ParserState -> Parser ()
setSince :: Version -> Parser ()
char :: Char -> Parser Char
char8 :: Char -> Parser Word8
anyChar :: Parser Char
notChar :: Char -> Parser Char
satisfy :: (Char -> Bool) -> Parser Char
peekChar :: Parser (Maybe Char)
peekChar' :: Parser Char
digit :: Parser Char
letter_iso8859_15 :: Parser Char
letter_ascii :: Parser Char
space :: Parser Char
string :: ByteString -> Parser ByteString
stringCI :: ByteString -> Parser ByteString
skipSpace :: Parser ()
skipWhile :: (Char -> Bool) -> Parser ()
take :: Int -> Parser ByteString
scan :: s -> (s -> Char -> Maybe s) -> Parser ByteString
takeWhile :: (Char -> Bool) -> Parser ByteString
takeWhile1 :: (Char -> Bool) -> Parser ByteString
takeTill :: (Char -> Bool) -> Parser ByteString
takeByteString :: Parser ByteString
takeLazyByteString :: Parser ByteString
endOfLine :: Parser ()
decimal :: Integral a => Parser a
hexadecimal :: (Integral a, Bits a) => Parser a
endOfInput :: Parser ()
atEnd :: Parser Bool

-- | A fast digit predicate.
isDigit :: Char -> Bool

-- | A fast digit predicate.
isDigit_w8 :: Word8 -> Bool

-- | A fast alphabetic predicate for the ISO-8859-15 encoding
--   
--   <i>Note</i>: For all character encodings other than ISO-8859-15, and
--   almost all Unicode code points above U+00A3, this predicate gives
--   <i>wrong answers</i>.
isAlpha_iso8859_15 :: Char -> Bool

-- | A fast alphabetic predicate for the ASCII encoding
--   
--   <i>Note</i>: For all character encodings other than ASCII, and almost
--   all Unicode code points above U+007F, this predicate gives <i>wrong
--   answers</i>.
isAlpha_ascii :: Char -> Bool

-- | Fast predicate for matching ASCII space characters.
--   
--   <i>Note</i>: This predicate only gives correct answers for the ASCII
--   encoding. For instance, it does not recognise U+00A0 (non-breaking
--   space) as a space character, even though it is a valid ISO-8859-15
--   byte. For a Unicode-aware and only slightly slower predicate, use
--   <a>isSpace</a>
isSpace :: Char -> Bool

-- | Fast <a>Word8</a> predicate for matching ASCII space characters.
isSpace_w8 :: Word8 -> Bool

-- | Match any character in a set.
--   
--   <pre>
--   vowel = inClass "aeiou"
--   </pre>
--   
--   Range notation is supported.
--   
--   <pre>
--   halfAlphabet = inClass "a-nA-N"
--   </pre>
--   
--   To add a literal '-' to a set, place it at the beginning or end of the
--   string.
inClass :: String -> Char -> Bool

-- | Match any character not in a set.
notInClass :: String -> Char -> Bool

-- | A predicate that matches either a carriage return <tt>'\r'</tt> or
--   newline <tt>'\n'</tt> character.
isEndOfLine :: Word8 -> Bool

-- | A predicate that matches either a space <tt>' '</tt> or horizontal tab
--   <tt>'\t'</tt> character.
isHorizontalSpace :: Word8 -> Bool

-- | <tt>choice ps</tt> tries to apply the actions in the list <tt>ps</tt>
--   in order, until one of them succeeds. Returns the value of the
--   succeeding action.
choice :: Alternative f => [f a] -> f a

-- | Apply the given action repeatedly, returning every result.
count :: Monad m => Int -> m a -> m [a]

-- | <tt>option x p</tt> tries to apply action <tt>p</tt>. If <tt>p</tt>
--   fails without consuming input, it returns the value <tt>x</tt>,
--   otherwise the value returned by <tt>p</tt>.
--   
--   <pre>
--   priority  = option 0 (digitToInt &lt;$&gt; digit)
--   </pre>
option :: Alternative f => a -> f a -> f a

-- | <tt>many' p</tt> applies the action <tt>p</tt> <i>zero</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>. The value
--   returned by <tt>p</tt> is forced to WHNF.
--   
--   <pre>
--   word  = many' letter
--   </pre>
many' :: (MonadPlus m) => m a -> m [a]

-- | <tt>many1 p</tt> applies the action <tt>p</tt> <i>one</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>.
--   
--   <pre>
--   word  = many1 letter
--   </pre>
many1 :: Alternative f => f a -> f [a]

-- | <tt>many1' p</tt> applies the action <tt>p</tt> <i>one</i> or more
--   times. Returns a list of the returned values of <tt>p</tt>. The value
--   returned by <tt>p</tt> is forced to WHNF.
--   
--   <pre>
--   word  = many1' letter
--   </pre>
many1' :: (MonadPlus m) => m a -> m [a]

-- | <tt>manyTill p end</tt> applies action <tt>p</tt> <i>zero</i> or more
--   times until action <tt>end</tt> succeeds, and returns the list of
--   values returned by <tt>p</tt>. This can be used to scan comments:
--   
--   <pre>
--   simpleComment   = string "&lt;!--" *&gt; manyTill anyChar (string "--&gt;")
--   </pre>
--   
--   (Note the overlapping parsers <tt>anyChar</tt> and <tt>string
--   "--&gt;"</tt>. While this will work, it is not very efficient, as it
--   will cause a lot of backtracking.)
manyTill :: Alternative f => f a -> f b -> f [a]

-- | <tt>manyTill' p end</tt> applies action <tt>p</tt> <i>zero</i> or more
--   times until action <tt>end</tt> succeeds, and returns the list of
--   values returned by <tt>p</tt>. This can be used to scan comments:
--   
--   <pre>
--   simpleComment   = string "&lt;!--" *&gt; manyTill' anyChar (string "--&gt;")
--   </pre>
--   
--   (Note the overlapping parsers <tt>anyChar</tt> and <tt>string
--   "--&gt;"</tt>. While this will work, it is not very efficient, as it
--   will cause a lot of backtracking.)
--   
--   The value returned by <tt>p</tt> is forced to WHNF.
manyTill' :: (MonadPlus m) => m a -> m b -> m [a]

-- | <tt>sepBy p sep</tt> applies <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p  = p `sepBy` (symbol ",")
--   </pre>
sepBy :: Alternative f => f a -> f s -> f [a]

-- | <tt>sepBy' p sep</tt> applies <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>. The value returned by <tt>p</tt> is forced to
--   WHNF.
--   
--   <pre>
--   commaSep p  = p `sepBy'` (symbol ",")
--   </pre>
sepBy' :: (MonadPlus m) => m a -> m s -> m [a]

-- | <tt>sepBy1 p sep</tt> applies <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p  = p `sepBy1` (symbol ",")
--   </pre>
sepBy1 :: Alternative f => f a -> f s -> f [a]

-- | <tt>sepBy1' p sep</tt> applies <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of the values
--   returned by <tt>p</tt>. The value returned by <tt>p</tt> is forced to
--   WHNF.
--   
--   <pre>
--   commaSep p  = p `sepBy1'` (symbol ",")
--   </pre>
sepBy1' :: (MonadPlus m) => m a -> m s -> m [a]

-- | Skip zero or more instances of an action.
skipMany :: Alternative f => f a -> f ()

-- | Skip one or more instances of an action.
skipMany1 :: Alternative f => f a -> f ()

-- | Combine two alternatives.
eitherP :: (Alternative f) => f a -> f b -> f (Either a b)
instance GHC.Base.MonadPlus Documentation.Haddock.Parser.Monad.Parser
instance GHC.Base.Monad Documentation.Haddock.Parser.Monad.Parser
instance GHC.Base.Alternative Documentation.Haddock.Parser.Monad.Parser
instance GHC.Base.Applicative Documentation.Haddock.Parser.Monad.Parser
instance GHC.Base.Functor Documentation.Haddock.Parser.Monad.Parser
instance GHC.Show.Show Documentation.Haddock.Parser.Monad.ParserState
instance GHC.Classes.Eq Documentation.Haddock.Parser.Monad.ParserState
instance a ~ Data.ByteString.Internal.ByteString => Data.String.IsString (Documentation.Haddock.Parser.Monad.Parser a)


-- | Parser used for Haddock comments. For external users of this library,
--   the most commonly used combination of functions is going to be
--   
--   <pre>
--   <a>toRegular</a> . <a>parseParas</a>
--   </pre>
module Documentation.Haddock.Parser

-- | Parse a text paragraph. Actually just a wrapper over
--   <a>parseStringBS</a> which drops leading whitespace and encodes the
--   string to UTF8 first.
parseString :: String -> DocH mod Identifier

-- | Main entry point to the parser. Appends the newline character to the
--   input string.
parseParas :: String -> MetaDoc mod Identifier

-- | Maps over <a>DocIdentifier</a>s over <a>String</a> with potentially
--   failing conversion using user-supplied function. If the conversion
--   fails, the identifier is deemed to not be valid and is treated as a
--   regular string.
overIdentifier :: (String -> Maybe a) -> DocH mod Identifier -> DocH mod a

-- | Drops the quotes/backticks around all identifiers, as if they were
--   valid but still <a>String</a>s.
toRegular :: DocH mod Identifier -> DocH mod String

-- | Identifier string surrounded with opening and closing
--   quotes/backticks.
type Identifier = (Char, String, Char)
