1{-# LANGUAGE CPP, DeriveFunctor, DeriveFoldable, DeriveTraversable #-} 2 3-- | 4-- Module : Documentation.Haddock.Types 5-- Copyright : (c) Simon Marlow 2003-2006, 6-- David Waern 2006-2009, 7-- Mateusz Kowalczyk 2013 8-- License : BSD-like 9-- 10-- Maintainer : haddock@projects.haskellorg 11-- Stability : experimental 12-- Portability : portable 13-- 14-- Exposes documentation data types used for (some) of Haddock. 15module Documentation.Haddock.Types where 16 17#if !MIN_VERSION_base(4,8,0) 18import Control.Applicative 19import Data.Foldable 20import Data.Traversable 21#endif 22 23#if MIN_VERSION_base(4,8,0) 24import Control.Arrow ((***)) 25import Data.Bifunctor 26#endif 27 28#if MIN_VERSION_base(4,10,0) 29import Data.Bifoldable 30import Data.Bitraversable 31#endif 32 33-- | With the advent of 'Version', we may want to start attaching more 34-- meta-data to comments. We make a structure for this ahead of time 35-- so we don't have to gut half the core each time we want to add such 36-- info. 37data Meta = Meta { _version :: Maybe Version 38 , _package :: Maybe Package 39 } deriving (Eq, Show) 40 41data MetaDoc mod id = 42 MetaDoc { _meta :: Meta 43 , _doc :: DocH mod id 44 } deriving (Eq, Show, Functor, Foldable, Traversable) 45 46#if MIN_VERSION_base(4,8,0) 47-- | __NOTE__: Only defined for @base >= 4.8.0@ 48instance Bifunctor MetaDoc where 49 bimap f g (MetaDoc m d) = MetaDoc m (bimap f g d) 50#endif 51 52#if MIN_VERSION_base(4,10,0) 53-- | __NOTE__: Only defined for @base >= 4.10.0@ 54instance Bifoldable MetaDoc where 55 bifoldr f g z d = bifoldr f g z (_doc d) 56 57-- | __NOTE__: Only defined for @base >= 4.10.0@ 58instance Bitraversable MetaDoc where 59 bitraverse f g (MetaDoc m d) = MetaDoc m <$> bitraverse f g d 60#endif 61 62overDoc :: (DocH a b -> DocH c d) -> MetaDoc a b -> MetaDoc c d 63overDoc f d = d { _doc = f $ _doc d } 64 65overDocF :: Functor f => (DocH a b -> f (DocH c d)) -> MetaDoc a b -> f (MetaDoc c d) 66overDocF f d = (\x -> d { _doc = x }) <$> f (_doc d) 67 68type Version = [Int] 69type Package = String 70 71data Hyperlink id = Hyperlink 72 { hyperlinkUrl :: String 73 , hyperlinkLabel :: Maybe id 74 } deriving (Eq, Show, Functor, Foldable, Traversable) 75 76data ModLink id = ModLink 77 { modLinkName :: String 78 , modLinkLabel :: Maybe id 79 } deriving (Eq, Show, Functor, Foldable, Traversable) 80 81data Picture = Picture 82 { pictureUri :: String 83 , pictureTitle :: Maybe String 84 } deriving (Eq, Show) 85 86data Header id = Header 87 { headerLevel :: Int -- ^ between 1 and 6 inclusive 88 , headerTitle :: id 89 } deriving (Eq, Show, Functor, Foldable, Traversable) 90 91data Example = Example 92 { exampleExpression :: String 93 , exampleResult :: [String] 94 } deriving (Eq, Show) 95 96data TableCell id = TableCell 97 { tableCellColspan :: Int 98 , tableCellRowspan :: Int 99 , tableCellContents :: id 100 } deriving (Eq, Show, Functor, Foldable, Traversable) 101 102newtype TableRow id = TableRow 103 { tableRowCells :: [TableCell id] 104 } deriving (Eq, Show, Functor, Foldable, Traversable) 105 106data Table id = Table 107 { tableHeaderRows :: [TableRow id] 108 , tableBodyRows :: [TableRow id] 109 } deriving (Eq, Show, Functor, Foldable, Traversable) 110 111data DocH mod id 112 = DocEmpty 113 | DocAppend (DocH mod id) (DocH mod id) 114 | DocString String 115 | DocParagraph (DocH mod id) 116 | DocIdentifier id 117 | DocIdentifierUnchecked mod 118 -- ^ A qualified identifier that couldn't be resolved. 119 | DocModule (ModLink (DocH mod id)) 120 -- ^ A link to a module, with an optional label. 121 | DocWarning (DocH mod id) 122 -- ^ This constructor has no counterpart in Haddock markup. 123 | DocEmphasis (DocH mod id) 124 | DocMonospaced (DocH mod id) 125 | DocBold (DocH mod id) 126 | DocUnorderedList [DocH mod id] 127 | DocOrderedList [DocH mod id] 128 | DocDefList [(DocH mod id, DocH mod id)] 129 | DocCodeBlock (DocH mod id) 130 | DocHyperlink (Hyperlink (DocH mod id)) 131 | DocPic Picture 132 | DocMathInline String 133 | DocMathDisplay String 134 | DocAName String 135 -- ^ A (HTML) anchor. It must not contain any spaces. 136 | DocProperty String 137 | DocExamples [Example] 138 | DocHeader (Header (DocH mod id)) 139 | DocTable (Table (DocH mod id)) 140 deriving (Eq, Show, Functor, Foldable, Traversable) 141 142#if MIN_VERSION_base(4,8,0) 143-- | __NOTE__: Only defined for @base >= 4.8.0@ 144instance Bifunctor DocH where 145 bimap _ _ DocEmpty = DocEmpty 146 bimap f g (DocAppend docA docB) = DocAppend (bimap f g docA) (bimap f g docB) 147 bimap _ _ (DocString s) = DocString s 148 bimap f g (DocParagraph doc) = DocParagraph (bimap f g doc) 149 bimap _ g (DocIdentifier i) = DocIdentifier (g i) 150 bimap f _ (DocIdentifierUnchecked m) = DocIdentifierUnchecked (f m) 151 bimap f g (DocModule (ModLink m lbl)) = DocModule (ModLink m (fmap (bimap f g) lbl)) 152 bimap f g (DocWarning doc) = DocWarning (bimap f g doc) 153 bimap f g (DocEmphasis doc) = DocEmphasis (bimap f g doc) 154 bimap f g (DocMonospaced doc) = DocMonospaced (bimap f g doc) 155 bimap f g (DocBold doc) = DocBold (bimap f g doc) 156 bimap f g (DocUnorderedList docs) = DocUnorderedList (map (bimap f g) docs) 157 bimap f g (DocOrderedList docs) = DocOrderedList (map (bimap f g) docs) 158 bimap f g (DocDefList docs) = DocDefList (map (bimap f g *** bimap f g) docs) 159 bimap f g (DocCodeBlock doc) = DocCodeBlock (bimap f g doc) 160 bimap f g (DocHyperlink (Hyperlink url lbl)) = DocHyperlink (Hyperlink url (fmap (bimap f g) lbl)) 161 bimap _ _ (DocPic picture) = DocPic picture 162 bimap _ _ (DocMathInline s) = DocMathInline s 163 bimap _ _ (DocMathDisplay s) = DocMathDisplay s 164 bimap _ _ (DocAName s) = DocAName s 165 bimap _ _ (DocProperty s) = DocProperty s 166 bimap _ _ (DocExamples examples) = DocExamples examples 167 bimap f g (DocHeader (Header level title)) = DocHeader (Header level (bimap f g title)) 168 bimap f g (DocTable (Table header body)) = DocTable (Table (map (fmap (bimap f g)) header) (map (fmap (bimap f g)) body)) 169#endif 170 171#if MIN_VERSION_base(4,10,0) 172-- | __NOTE__: Only defined for @base >= 4.10.0@ 173instance Bifoldable DocH where 174 bifoldr f g z (DocAppend docA docB) = bifoldr f g (bifoldr f g z docA) docB 175 bifoldr f g z (DocParagraph doc) = bifoldr f g z doc 176 bifoldr _ g z (DocIdentifier i) = g i z 177 bifoldr f _ z (DocIdentifierUnchecked m) = f m z 178 bifoldr f g z (DocWarning doc) = bifoldr f g z doc 179 bifoldr f g z (DocEmphasis doc) = bifoldr f g z doc 180 bifoldr f g z (DocMonospaced doc) = bifoldr f g z doc 181 bifoldr f g z (DocBold doc) = bifoldr f g z doc 182 bifoldr f g z (DocUnorderedList docs) = foldr (flip (bifoldr f g)) z docs 183 bifoldr f g z (DocOrderedList docs) = foldr (flip (bifoldr f g)) z docs 184 bifoldr f g z (DocDefList docs) = foldr (\(l, r) acc -> bifoldr f g (bifoldr f g acc l) r) z docs 185 bifoldr f g z (DocCodeBlock doc) = bifoldr f g z doc 186 bifoldr f g z (DocHeader (Header _ title)) = bifoldr f g z title 187 bifoldr f g z (DocTable (Table header body)) = foldr (\r acc -> foldr (flip (bifoldr f g)) acc r) (foldr (\r acc -> foldr (flip (bifoldr f g)) acc r) z body) header 188 bifoldr _ _ z _ = z 189 190-- | __NOTE__: Only defined for @base >= 4.10.0@ 191instance Bitraversable DocH where 192 bitraverse _ _ DocEmpty = pure DocEmpty 193 bitraverse f g (DocAppend docA docB) = DocAppend <$> bitraverse f g docA <*> bitraverse f g docB 194 bitraverse _ _ (DocString s) = pure (DocString s) 195 bitraverse f g (DocParagraph doc) = DocParagraph <$> bitraverse f g doc 196 bitraverse _ g (DocIdentifier i) = DocIdentifier <$> g i 197 bitraverse f _ (DocIdentifierUnchecked m) = DocIdentifierUnchecked <$> f m 198 bitraverse f g (DocModule (ModLink m lbl)) = DocModule <$> (ModLink m <$> traverse (bitraverse f g) lbl) 199 bitraverse f g (DocWarning doc) = DocWarning <$> bitraverse f g doc 200 bitraverse f g (DocEmphasis doc) = DocEmphasis <$> bitraverse f g doc 201 bitraverse f g (DocMonospaced doc) = DocMonospaced <$> bitraverse f g doc 202 bitraverse f g (DocBold doc) = DocBold <$> bitraverse f g doc 203 bitraverse f g (DocUnorderedList docs) = DocUnorderedList <$> traverse (bitraverse f g) docs 204 bitraverse f g (DocOrderedList docs) = DocOrderedList <$> traverse (bitraverse f g) docs 205 bitraverse f g (DocDefList docs) = DocDefList <$> traverse (bitraverse (bitraverse f g) (bitraverse f g)) docs 206 bitraverse f g (DocCodeBlock doc) = DocCodeBlock <$> bitraverse f g doc 207 bitraverse f g (DocHyperlink (Hyperlink url lbl)) = DocHyperlink <$> (Hyperlink url <$> traverse (bitraverse f g) lbl) 208 bitraverse _ _ (DocPic picture) = pure (DocPic picture) 209 bitraverse _ _ (DocMathInline s) = pure (DocMathInline s) 210 bitraverse _ _ (DocMathDisplay s) = pure (DocMathDisplay s) 211 bitraverse _ _ (DocAName s) = pure (DocAName s) 212 bitraverse _ _ (DocProperty s) = pure (DocProperty s) 213 bitraverse _ _ (DocExamples examples) = pure (DocExamples examples) 214 bitraverse f g (DocHeader (Header level title)) = (DocHeader . Header level) <$> bitraverse f g title 215 bitraverse f g (DocTable (Table header body)) = (\h b -> DocTable (Table h b)) <$> traverse (traverse (bitraverse f g)) header <*> traverse (traverse (bitraverse f g)) body 216#endif 217 218-- | The namespace qualification for an identifier. 219data Namespace = Value | Type | None deriving (Eq, Ord, Enum, Show) 220 221-- | Render the a namespace into the same format it was initially parsed. 222renderNs :: Namespace -> String 223renderNs Value = "v" 224renderNs Type = "t" 225renderNs None = "" 226 227 228-- | 'DocMarkupH' is a set of instructions for marking up documentation. 229-- In fact, it's really just a mapping from 'Doc' to some other 230-- type [a], where [a] is usually the type of the output (HTML, say). 231-- Use 'Documentation.Haddock.Markup.markup' to apply a 'DocMarkupH' to 232-- a 'DocH'. 233-- 234-- @since 1.4.5 235-- 236data DocMarkupH mod id a = Markup 237 { markupEmpty :: a 238 , markupString :: String -> a 239 , markupParagraph :: a -> a 240 , markupAppend :: a -> a -> a 241 , markupIdentifier :: id -> a 242 , markupIdentifierUnchecked :: mod -> a 243 , markupModule :: ModLink a -> a 244 , markupWarning :: a -> a 245 , markupEmphasis :: a -> a 246 , markupBold :: a -> a 247 , markupMonospaced :: a -> a 248 , markupUnorderedList :: [a] -> a 249 , markupOrderedList :: [a] -> a 250 , markupDefList :: [(a,a)] -> a 251 , markupCodeBlock :: a -> a 252 , markupHyperlink :: Hyperlink a -> a 253 , markupAName :: String -> a 254 , markupPic :: Picture -> a 255 , markupMathInline :: String -> a 256 , markupMathDisplay :: String -> a 257 , markupProperty :: String -> a 258 , markupExample :: [Example] -> a 259 , markupHeader :: Header a -> a 260 , markupTable :: Table a -> a 261 } 262