ApiAnnotation.hs 6.89 KB
Newer Older
Alan Zimmerman's avatar
Alan Zimmerman committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
{-# LANGUAGE DeriveDataTypeable #-}

module ApiAnnotation (
  getAnnotation,
  getAnnotationComments,
  ApiAnns,
  ApiAnnKey,
  AnnKeywordId(..),
  AnnotationComment(..),
  LRdrName -- Exists for haddocks only
  ) where

import RdrName
import Outputable
import SrcLoc
import qualified Data.Map as Map
import Data.Data


{- Note [Api annotations]
   ~~~~~~~~~~~~~~~~~~~~~~

In order to do source to source conversions using the GHC API, the
locations of all elements of the original source needs to be tracked.
The includes keywords such as 'let' / 'in' / 'do' etc as well as
punctuation such as commas and braces, and also comments.

These are captured in a structure separate from the parse tree, and
returned in the pm_annotations field of the ParsedModule type.

The non-comment annotations are stored indexed to the SrcSpan of the
AST element containing them, together with a AnnKeywordId value
identifying the specific keyword being captured.

> type ApiAnnKey = (SrcSpan,AnnKeywordId)
>
> Map.Map ApiAnnKey SrcSpan

So

> let X = 1 in 2 *x

would result in the AST element

  L span (HsLet (binds for x = 1) (2 * x))

and the annotations

  (span,AnnLet) having the location of the 'let' keyword
  (span,AnnIn)  having the location of the 'in' keyword


The comments are indexed to the SrcSpan of the lowest AST element
enclosing them

> Map.Map SrcSpan [Located AnnotationComment]

So the full ApiAnns type is

> type ApiAnns = ( Map.Map ApiAnnKey SrcSpan
>                , Map.Map SrcSpan [Located AnnotationComment])


This is done in the lexer / parser as follows.


The PState variable in the lexer has the following variables added

>  annotations :: [(ApiAnnKey,SrcSpan)],
>  comment_q :: [Located Token],
>  annotations_comments :: [(SrcSpan,[Located AnnotationComment])]

The first and last store the values that end up in the ApiAnns value
at the end via Map.fromList

The comment_q captures comments as they are seen in the token stream,
so that when they are ready to be allocated via the parser they are
available.

The parser interacts with the lexer using the function

> addAnnotation :: SrcSpan -> AnnKeywordId -> SrcSpan -> P ()

which takes the AST element SrcSpan, the annotation keyword and the
target SrcSpan.

This adds the annotation to the `annotations` field of `PState` and
transfers any comments in `comment_q` to the `annotations_comments`
field.

Parser
------

The parser implements a number of helper types and methods for the
capture of annotations

> type AddAnn = (SrcSpan -> P ())
>
> mj :: AnnKeywordId -> Located e -> (SrcSpan -> P ())
> mj a l = (\s -> addAnnotation s a (gl l))

AddAnn represents the addition of an annotation a to a provided
SrcSpan, and `mj` constructs an AddAnn value.

> ams :: Located a -> [AddAnn] -> P (Located a)
> ams a@(L l _) bs = (mapM_ (\a -> a l) bs) >> return a

So the production in Parser.y for the HsLet AST element is

        | 'let' binds 'in' exp    {% ams (sLL $1 $> $ HsLet (snd $ unLoc $2) $4)
                                         (mj AnnLet $1:mj AnnIn $3
                                           :(fst $ unLoc $2)) }

This adds an AnnLet annotation for 'let', an AnnIn for 'in', as well
as any annotations that may arise in the binds. This will include open
and closing braces if they are used to delimit the let expressions.

-}
-- ---------------------------------------------------------------------

type ApiAnns = ( Map.Map ApiAnnKey [SrcSpan]
               , Map.Map SrcSpan [Located AnnotationComment])

type ApiAnnKey = (SrcSpan,AnnKeywordId)


-- | Retrieve a list of annotation 'SrcSpan's based on the 'SrcSpan'
-- of the annotated AST element, and the known type of the annotation.
getAnnotation :: ApiAnns -> SrcSpan -> AnnKeywordId -> [SrcSpan]
getAnnotation (anns,_) span ann
   = case Map.lookup (span,ann) anns of
       Nothing -> []
       Just ss -> ss

-- |Retrieve the comments allocated to the current 'SrcSpan'
getAnnotationComments :: ApiAnns -> SrcSpan -> [Located AnnotationComment]
getAnnotationComments (_,anns) span =
  case Map.lookup span anns of
    Just cs -> cs
    Nothing -> []

-- --------------------------------------------------------------------

-- | Note: in general the names of these are taken from the
-- corresponding token, unless otherwise noted
-- See note [Api annotations] above for details of the usage
data AnnKeywordId
    = AnnAs
    | AnnAt
    | AnnBang  -- ^ '!'
    | AnnBy
    | AnnCase -- ^ case or lambda case
    | AnnClass
    | AnnClose -- ^  '}' or ']' or ')' or '#)' etc
    | AnnColon
    | AnnComma
    | AnnDarrow -- ^ '=>'
    | AnnData
    | AnnDcolon -- ^ '::'
    | AnnDefault
    | AnnDeriving
    | AnnDo
    | AnnDot    -- ^ '.'
    | AnnDotdot -- ^ '..'
    | AnnElse
    | AnnEqual
    | AnnExport
    | AnnFamily
    | AnnForall
    | AnnForeign
    | AnnFunId -- ^ for function name in matches where there are
               -- multiple equations for the function.
    | AnnGroup
    | AnnHeader -- ^ for CType
    | AnnHiding
    | AnnIf
    | AnnImport
    | AnnIn
    | AnnInstance
    | AnnLam
    | AnnLarrow     -- ^ '<-'
    | AnnLet
    | AnnMdo
    | AnnMinus -- ^ '-'
    | AnnModule
    | AnnNewtype
    | AnnOf
    | AnnOpen   -- ^ '{' or '[' or '(' or '(#' etc
    | AnnPackageName
    | AnnPattern
    | AnnProc
    | AnnQualified
    | AnnRarrow -- ^ '->'
    | AnnRec
    | AnnRole
    | AnnSafe
    | AnnSemi -- ^ ';'
    | AnnThen
    | AnnTilde -- ^ '~'
    | AnnTildehsh -- ^ '~#'
    | AnnType
    | AnnUsing
    | AnnVal  -- ^ e.g. INTEGER
    | AnnVbar -- ^ '|'
    | AnnWhere
    | Annlarrowtail -- ^ '-<'
    | Annrarrowtail -- ^ '->'
    | AnnLarrowtail -- ^ '-<<'
    | AnnRarrowtail -- ^ '>>-'
    | AnnEofPos
    deriving (Eq,Ord,Data,Typeable,Show)

instance Outputable AnnKeywordId where
  ppr x = text (show x)

-- ---------------------------------------------------------------------

data AnnotationComment =
  -- Documentation annotations
    AnnDocCommentNext  String     -- ^ something beginning '-- |'
  | AnnDocCommentPrev  String     -- ^ something beginning '-- ^'
  | AnnDocCommentNamed String     -- ^ something beginning '-- $'
  | AnnDocSection      Int String -- ^ a section heading
  | AnnDocOptions      String     -- ^ doc options (prune, ignore-exports, etc)
  | AnnDocOptionsOld   String     -- ^ doc options declared "-- # ..."-style
  | AnnLineComment     String     -- ^ comment starting by "--"
  | AnnBlockComment    String     -- ^ comment in {- -}
    deriving (Eq,Ord,Data,Typeable,Show)
-- Note: these are based on the Token versions, but the Token type is
-- defined in Lexer.x and bringing it in here would create a loop

232 233
instance Outputable AnnotationComment where
  ppr x = text (show x)
Alan Zimmerman's avatar
Alan Zimmerman committed
234 235 236 237 238 239 240

-- | - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnOpen',
--             'ApiAnnotation.AnnClose','ApiAnnotation.AnnComma',
--             'ApiAnnotation.AnnRarrow','ApiAnnotation.AnnTildehsh',
--             'ApiAnnotation.AnnTilde'
--   - May have 'ApiAnnotation.AnnComma' when in a list
type LRdrName = Located RdrName