7376e305ea6765299b159f4ceb320fc92e6daf0f
[ghc.git] / compiler / parser / ApiAnnotation.hs
1 {-# LANGUAGE DeriveDataTypeable #-}
2
3 module ApiAnnotation (
4 getAnnotation, getAndRemoveAnnotation,
5 getAnnotationComments,getAndRemoveAnnotationComments,
6 ApiAnns,
7 ApiAnnKey,
8 AnnKeywordId(..),
9 AnnotationComment(..),
10 LRdrName -- Exists for haddocks only
11 ) where
12
13 import RdrName
14 import Outputable
15 import SrcLoc
16 import qualified Data.Map as Map
17 import Data.Data
18
19
20 {-
21 Note [Api annotations]
22 ~~~~~~~~~~~~~~~~~~~~~~
23 In order to do source to source conversions using the GHC API, the
24 locations of all elements of the original source needs to be tracked.
25 This includes keywords such as 'let' / 'in' / 'do' etc as well as
26 punctuation such as commas and braces, and also comments.
27
28 These are captured in a structure separate from the parse tree, and
29 returned in the pm_annotations field of the ParsedModule type.
30
31 The non-comment annotations are stored indexed to the SrcSpan of the
32 AST element containing them, together with a AnnKeywordId value
33 identifying the specific keyword being captured.
34
35 > type ApiAnnKey = (SrcSpan,AnnKeywordId)
36 >
37 > Map.Map ApiAnnKey SrcSpan
38
39 So
40
41 > let x = 1 in 2 *x
42
43 would result in the AST element
44
45 L span (HsLet (binds for x = 1) (2 * x))
46
47 and the annotations
48
49 (span,AnnLet) having the location of the 'let' keyword
50 (span,AnnIn) having the location of the 'in' keyword
51
52
53 The comments are indexed to the SrcSpan of the lowest AST element
54 enclosing them
55
56 > Map.Map SrcSpan [Located AnnotationComment]
57
58 So the full ApiAnns type is
59
60 > type ApiAnns = ( Map.Map ApiAnnKey SrcSpan
61 > , Map.Map SrcSpan [Located AnnotationComment])
62
63
64 This is done in the lexer / parser as follows.
65
66
67 The PState variable in the lexer has the following variables added
68
69 > annotations :: [(ApiAnnKey,[SrcSpan])],
70 > comment_q :: [Located AnnotationComment],
71 > annotations_comments :: [(SrcSpan,[Located AnnotationComment])]
72
73 The first and last store the values that end up in the ApiAnns value
74 at the end via Map.fromList
75
76 The comment_q captures comments as they are seen in the token stream,
77 so that when they are ready to be allocated via the parser they are
78 available.
79
80 The parser interacts with the lexer using the function
81
82 > addAnnotation :: SrcSpan -> AnnKeywordId -> SrcSpan -> P ()
83
84 which takes the AST element SrcSpan, the annotation keyword and the
85 target SrcSpan.
86
87 This adds the annotation to the `annotations` field of `PState` and
88 transfers any comments in `comment_q` to the `annotations_comments`
89 field.
90
91 Parser
92 ------
93
94 The parser implements a number of helper types and methods for the
95 capture of annotations
96
97 > type AddAnn = (SrcSpan -> P ())
98 >
99 > mj :: AnnKeywordId -> Located e -> (SrcSpan -> P ())
100 > mj a l = (\s -> addAnnotation s a (gl l))
101
102 AddAnn represents the addition of an annotation a to a provided
103 SrcSpan, and `mj` constructs an AddAnn value.
104
105 > ams :: Located a -> [AddAnn] -> P (Located a)
106 > ams a@(L l _) bs = (mapM_ (\a -> a l) bs) >> return a
107
108 So the production in Parser.y for the HsLet AST element is
109
110 | 'let' binds 'in' exp {% ams (sLL $1 $> $ HsLet (snd $ unLoc $2) $4)
111 (mj AnnLet $1:mj AnnIn $3
112 :(fst $ unLoc $2)) }
113
114 This adds an AnnLet annotation for 'let', an AnnIn for 'in', as well
115 as any annotations that may arise in the binds. This will include open
116 and closing braces if they are used to delimit the let expressions.
117
118 The wiki page describing this feature is
119 https://ghc.haskell.org/trac/ghc/wiki/ApiAnnotations
120
121 -}
122 -- ---------------------------------------------------------------------
123
124 type ApiAnns = ( Map.Map ApiAnnKey [SrcSpan]
125 , Map.Map SrcSpan [Located AnnotationComment])
126
127 type ApiAnnKey = (SrcSpan,AnnKeywordId)
128
129
130 -- | Retrieve a list of annotation 'SrcSpan's based on the 'SrcSpan'
131 -- of the annotated AST element, and the known type of the annotation.
132 getAnnotation :: ApiAnns -> SrcSpan -> AnnKeywordId -> [SrcSpan]
133 getAnnotation (anns,_) span ann
134 = case Map.lookup (span,ann) anns of
135 Nothing -> []
136 Just ss -> ss
137
138 -- | Retrieve a list of annotation 'SrcSpan's based on the 'SrcSpan'
139 -- of the annotated AST element, and the known type of the annotation.
140 -- The list is removed from the annotations.
141 getAndRemoveAnnotation :: ApiAnns -> SrcSpan -> AnnKeywordId
142 -> ([SrcSpan],ApiAnns)
143 getAndRemoveAnnotation (anns,cs) span ann
144 = case Map.lookup (span,ann) anns of
145 Nothing -> ([],(anns,cs))
146 Just ss -> (ss,(Map.delete (span,ann) anns,cs))
147
148 -- |Retrieve the comments allocated to the current 'SrcSpan'
149 --
150 -- Note: A given 'SrcSpan' may appear in multiple AST elements,
151 -- beware of duplicates
152 getAnnotationComments :: ApiAnns -> SrcSpan -> [Located AnnotationComment]
153 getAnnotationComments (_,anns) span =
154 case Map.lookup span anns of
155 Just cs -> cs
156 Nothing -> []
157
158 -- |Retrieve the comments allocated to the current 'SrcSpan', and
159 -- remove them from the annotations
160 getAndRemoveAnnotationComments :: ApiAnns -> SrcSpan
161 -> ([Located AnnotationComment],ApiAnns)
162 getAndRemoveAnnotationComments (anns,canns) span =
163 case Map.lookup span canns of
164 Just cs -> (cs,(anns,Map.delete span canns))
165 Nothing -> ([],(anns,canns))
166
167 -- --------------------------------------------------------------------
168
169 -- | API Annotations exist so that tools can perform source to source
170 -- conversions of Haskell code. They are used to keep track of the
171 -- various syntactic keywords that are not captured in the existing
172 -- AST.
173 --
174 -- The annotations, together with original source comments are made
175 -- available in the @'pm_annotations'@ field of @'GHC.ParsedModule'@.
176 -- Comments are only retained if @'Opt_KeepRawTokenStream'@ is set in
177 -- @'DynFlags.DynFlags'@ before parsing.
178 --
179 -- The wiki page describing this feature is
180 -- https://ghc.haskell.org/trac/ghc/wiki/ApiAnnotations
181 --
182 -- Note: in general the names of these are taken from the
183 -- corresponding token, unless otherwise noted
184 -- See note [Api annotations] above for details of the usage
185 data AnnKeywordId
186 = AnnAs
187 | AnnAt
188 | AnnBang -- ^ '!'
189 | AnnBackquote -- ^ '`'
190 | AnnBy
191 | AnnCase -- ^ case or lambda case
192 | AnnClass
193 | AnnClose -- ^ '\#)' or '\#-}' etc
194 | AnnCloseC -- ^ '}'
195 | AnnCloseP -- ^ ')'
196 | AnnCloseS -- ^ ']'
197 | AnnColon
198 | AnnComma -- ^ as a list separator
199 | AnnCommaTuple -- ^ in a RdrName for a tuple
200 | AnnDarrow -- ^ '=>'
201 | AnnData
202 | AnnDcolon -- ^ '::'
203 | AnnDefault
204 | AnnDeriving
205 | AnnDo
206 | AnnDot -- ^ '.'
207 | AnnDotdot -- ^ '..'
208 | AnnElse
209 | AnnEqual
210 | AnnExport
211 | AnnFamily
212 | AnnForall
213 | AnnForeign
214 | AnnFunId -- ^ for function name in matches where there are
215 -- multiple equations for the function.
216 | AnnGroup
217 | AnnHeader -- ^ for CType
218 | AnnHiding
219 | AnnIf
220 | AnnImport
221 | AnnIn
222 | AnnInfix -- ^ 'infix' or 'infixl' or 'infixr'
223 | AnnInstance
224 | AnnLam
225 | AnnLarrow -- ^ '<-'
226 | AnnLet
227 | AnnMdo
228 | AnnMinus -- ^ '-'
229 | AnnModule
230 | AnnNewtype
231 | AnnName -- ^ where a name loses its location in the AST, this carries it
232 | AnnOf
233 | AnnOpen -- ^ '(\#' or '{-\# LANGUAGE' etc
234 | AnnOpenC -- ^ '{'
235 | AnnOpenP -- ^ '('
236 | AnnOpenPE -- ^ '$('
237 | AnnOpenPTE -- ^ '$$('
238 | AnnOpenS -- ^ '['
239 | AnnPackageName
240 | AnnPattern
241 | AnnProc
242 | AnnQualified
243 | AnnRarrow -- ^ '->'
244 | AnnRec
245 | AnnRole
246 | AnnSafe
247 | AnnSemi -- ^ ';'
248 | AnnSimpleQuote -- ^ '''
249 | AnnStatic -- ^ 'static'
250 | AnnThen
251 | AnnThIdSplice -- ^ '$'
252 | AnnThIdTySplice -- ^ '$$'
253 | AnnThTyQuote -- ^ double '''
254 | AnnTilde -- ^ '~'
255 | AnnTildehsh -- ^ '~#'
256 | AnnType
257 | AnnUnit -- ^ '()' for types
258 | AnnUsing
259 | AnnVal -- ^ e.g. INTEGER
260 | AnnValStr -- ^ String value, will need quotes when output
261 | AnnVbar -- ^ '|'
262 | AnnWhere
263 | Annlarrowtail -- ^ '-<'
264 | Annrarrowtail -- ^ '->'
265 | AnnLarrowtail -- ^ '-<<'
266 | AnnRarrowtail -- ^ '>>-'
267 | AnnEofPos
268 deriving (Eq,Ord,Data,Typeable,Show)
269
270 instance Outputable AnnKeywordId where
271 ppr x = text (show x)
272
273 -- ---------------------------------------------------------------------
274
275 data AnnotationComment =
276 -- Documentation annotations
277 AnnDocCommentNext String -- ^ something beginning '-- |'
278 | AnnDocCommentPrev String -- ^ something beginning '-- ^'
279 | AnnDocCommentNamed String -- ^ something beginning '-- $'
280 | AnnDocSection Int String -- ^ a section heading
281 | AnnDocOptions String -- ^ doc options (prune, ignore-exports, etc)
282 | AnnDocOptionsOld String -- ^ doc options declared "-- # ..."-style
283 | AnnLineComment String -- ^ comment starting by "--"
284 | AnnBlockComment String -- ^ comment in {- -}
285 deriving (Eq,Ord,Data,Typeable,Show)
286 -- Note: these are based on the Token versions, but the Token type is
287 -- defined in Lexer.x and bringing it in here would create a loop
288
289 instance Outputable AnnotationComment where
290 ppr x = text (show x)
291
292 -- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen',
293 -- 'ApiAnnotation.AnnClose','ApiAnnotation.AnnComma',
294 -- 'ApiAnnotation.AnnRarrow','ApiAnnotation.AnnTildehsh',
295 -- 'ApiAnnotation.AnnTilde'
296 -- - May have 'ApiAnnotation.AnnComma' when in a list
297 type LRdrName = Located RdrName