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