Syntax.hs 54.4 KB
Newer Older
1
{-# LANGUAGE CPP, DeriveDataTypeable, PolymorphicComponents,
2 3
             DeriveGeneric, FlexibleInstances, DefaultSignatures,
             ScopedTypeVariables, Rank2Types #-}
4 5 6

{-# LANGUAGE RoleAnnotations #-}
{-# OPTIONS_GHC -fno-warn-inline-rule-shadowing #-}
7

8 9 10 11
#if MIN_VERSION_base(4,8,0)
#define HAS_NATURAL
#endif

12 13 14 15 16
-----------------------------------------------------------------------------
-- |
-- Module      :  Language.Haskell.Syntax
-- Copyright   :  (c) The University of Glasgow 2003
-- License     :  BSD-style (see the file libraries/base/LICENSE)
Jan Stolarek's avatar
Jan Stolarek committed
17
--
18 19 20 21 22 23 24 25
-- Maintainer  :  libraries@haskell.org
-- Stability   :  experimental
-- Portability :  portable
--
-- Abstract syntax definitions for Template Haskell.
--
-----------------------------------------------------------------------------

26
module Language.Haskell.TH.Syntax where
27

28
import Data.Data hiding (Fixity(..))
29
#if __GLASGOW_HASKELL__ < 709
30
import Control.Applicative( Applicative(..) )
31
#endif
32
import Data.IORef
33
import System.IO.Unsafe ( unsafePerformIO )
34
import Control.Monad (liftM)
35
import System.IO        ( hPutStrLn, stderr )
36
import Data.Char        ( isAlpha, isAlphaNum, isUpper )
37 38 39
import Data.Int
import Data.Word
import Data.Ratio
40
import GHC.Generics     ( Generic )
41

42 43 44 45
#ifdef HAS_NATURAL
import Numeric.Natural
#endif

46 47
-----------------------------------------------------
--
48
--              The Quasi class
49 50 51
--
-----------------------------------------------------

52
class (Applicative m, Monad m) => Quasi m where
53
  qNewName :: String -> m Name
54
        -- ^ Fresh names
55

56 57 58
        -- Error reporting and recovery
  qReport  :: Bool -> String -> m ()    -- ^ Report an error (True) or warning (False)
                                        -- ...but carry on; use 'fail' to stop
aavogt's avatar
aavogt committed
59 60
  qRecover :: m a -- ^ the error handler
           -> m a -- ^ action which may fail
61
           -> m a               -- ^ Recover from the monadic 'fail'
Jan Stolarek's avatar
Jan Stolarek committed
62

63
        -- Inspect the type-checker's environment
64 65 66
  qLookupName :: Bool -> String -> m (Maybe Name)
       -- True <=> type namespace, False <=> value namespace
  qReify          :: Name -> m Info
Ryan Scott's avatar
Ryan Scott committed
67
  qReifyFixity    :: Name -> m Fixity
68 69
  qReifyInstances :: Name -> [Type] -> m [Dec]
       -- Is (n tys) an instance?
Jan Stolarek's avatar
Jan Stolarek committed
70
       -- Returns list of matching instance Decs
71 72
       --    (with empty sub-Decs)
       -- Works for classes and type functions
Austin Seipp's avatar
Austin Seipp committed
73 74
  qReifyRoles       :: Name -> m [Role]
  qReifyAnnotations :: Data a => AnnLookup -> m [a]
75
  qReifyModule      :: Module -> m ModuleInfo
76

77
  qLocation :: m Loc
78 79

  qRunIO :: IO a -> m a
aavogt's avatar
aavogt committed
80
  -- ^ Input/output (dangerous)
81

GregWeber's avatar
GregWeber committed
82
  qAddDependentFile :: FilePath -> m ()
83

84 85
  qAddTopDecls :: [Dec] -> m ()

86 87
  qAddModFinalizer :: Q () -> m ()

gmainland's avatar
gmainland committed
88 89 90 91
  qGetQ :: Typeable a => m (Maybe a)

  qPutQ :: Typeable a => a -> m ()

92
-----------------------------------------------------
93
--      The IO instance of Quasi
Jan Stolarek's avatar
Jan Stolarek committed
94
--
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
--  This instance is used only when running a Q
--  computation in the IO monad, usually just to
--  print the result.  There is no interesting
--  type environment, so reification isn't going to
--  work.
--
-----------------------------------------------------

instance Quasi IO where
  qNewName s = do { n <- readIORef counter
                 ; writeIORef counter (n+1)
                 ; return (mkNameU s n) }

  qReport True  msg = hPutStrLn stderr ("Template Haskell error: " ++ msg)
  qReport False msg = hPutStrLn stderr ("Template Haskell error: " ++ msg)

111
  qLookupName _ _     = badIO "lookupName"
112
  qReify _            = badIO "reify"
Ryan Scott's avatar
Ryan Scott committed
113
  qReifyFixity _      = badIO "reifyFixity"
114
  qReifyInstances _ _ = badIO "reifyInstances"
115
  qReifyRoles _       = badIO "reifyRoles"
Austin Seipp's avatar
Austin Seipp committed
116
  qReifyAnnotations _ = badIO "reifyAnnotations"
117
  qReifyModule _      = badIO "reifyModule"
118 119
  qLocation           = badIO "currentLocation"
  qRecover _ _        = badIO "recover" -- Maybe we could fix this?
GregWeber's avatar
GregWeber committed
120
  qAddDependentFile _ = badIO "addDependentFile"
121
  qAddTopDecls _      = badIO "addTopDecls"
122
  qAddModFinalizer _  = badIO "addModFinalizer"
gmainland's avatar
gmainland committed
123 124
  qGetQ               = badIO "getQ"
  qPutQ _             = badIO "putQ"
125 126

  qRunIO m = m
Jan Stolarek's avatar
Jan Stolarek committed
127

128
badIO :: String -> IO a
129 130
badIO op = do   { qReport True ("Can't do `" ++ op ++ "' in the IO monad")
                ; fail "Template Haskell failure" }
131 132 133 134 135 136 137 138 139

-- Global variable to generate unique symbols
counter :: IORef Int
{-# NOINLINE counter #-}
counter = unsafePerformIO (newIORef 0)


-----------------------------------------------------
--
140
--              The Q monad
141 142 143 144 145
--
-----------------------------------------------------

newtype Q a = Q { unQ :: forall m. Quasi m => m a }

146 147 148 149 150
-- \"Runs\" the 'Q' monad. Normal users of Template Haskell
-- should not need this function, as the splice brackets @$( ... )@
-- are the usual way of running a 'Q' computation.
--
-- This function is primarily used in GHC internals, and for debugging
Jan Stolarek's avatar
Jan Stolarek committed
151
-- splices by running them in 'IO'.
152 153 154 155 156
--
-- Note that many functions in 'Q', such as 'reify' and other compiler
-- queries, are not supported when running 'Q' in 'IO'; these operations
-- simply fail at runtime. Indeed, the only operations guaranteed to succeed
-- are 'newName', 'runIO', 'reportError' and 'reportWarning'.
157 158 159 160 161 162 163
runQ :: Quasi m => Q a -> m a
runQ (Q m) = m

instance Monad Q where
  return x   = Q (return x)
  Q m >>= k  = Q (m >>= \x -> unQ (k x))
  Q m >> Q n = Q (m >> n)
164
  fail s     = report True s >> Q (fail "Q monad failure")
165

166 167 168
instance Functor Q where
  fmap f (Q x) = Q (fmap f x)

Jan Stolarek's avatar
Jan Stolarek committed
169 170 171
instance Applicative Q where
  pure x = Q (pure x)
  Q f <*> Q x = Q (f <*> x)
172

gmainland's avatar
gmainland committed
173 174
-----------------------------------------------------
--
175
--              The TExp type
gmainland's avatar
gmainland committed
176 177 178
--
-----------------------------------------------------

179
type role TExp nominal   -- See Note [Role of TExp]
180 181 182 183 184 185 186 187 188
newtype TExp a = TExp { unType :: Exp }

unTypeQ :: Q (TExp a) -> Q Exp
unTypeQ m = do { TExp e <- m
               ; return e }

unsafeTExpCoerce :: Q Exp -> Q (TExp a)
unsafeTExpCoerce m = do { e <- m
                        ; return (TExp e) }
gmainland's avatar
gmainland committed
189

190 191 192 193 194 195 196 197 198 199 200 201 202
{- Note [Role of TExp]
~~~~~~~~~~~~~~~~~~~~~~
TExp's argument must have a nominal role, not phantom as would
be inferred (Trac #8459).  Consider

  e :: TExp Age
  e = MkAge 3

  foo = $(coerce e) + 4::Int

The splice will evaluate to (MkAge 3) and you can't add that to
4::Int. So you can't coerce a (TExp Age) to a (TExp Int). -}

203 204
----------------------------------------------------
-- Packaged versions for the programmer, hiding the Quasi-ness
205

Jan Stolarek's avatar
Jan Stolarek committed
206 207
{- |
Generate a fresh name, which cannot be captured.
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239

For example, this:

@f = $(do
  nm1 <- newName \"x\"
  let nm2 = 'mkName' \"x\"
  return ('LamE' ['VarP' nm1] (LamE [VarP nm2] ('VarE' nm1)))
 )@

will produce the splice

>f = \x0 -> \x -> x0

In particular, the occurrence @VarE nm1@ refers to the binding @VarP nm1@,
and is not captured by the binding @VarP nm2@.

Although names generated by @newName@ cannot /be captured/, they can
/capture/ other names. For example, this:

>g = $(do
>  nm1 <- newName "x"
>  let nm2 = mkName "x"
>  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2)))
> )

will produce the splice

>g = \x -> \x0 -> x0

since the occurrence @VarE nm2@ is captured by the innermost binding
of @x@, namely @VarP nm1@.
-}
240 241 242
newName :: String -> Q Name
newName s = Q (qNewName s)

Jan Stolarek's avatar
Jan Stolarek committed
243
-- | Report an error (True) or warning (False),
244
-- but carry on; use 'fail' to stop.
245 246
report  :: Bool -> String -> Q ()
report b s = Q (qReport b s)
247
{-# DEPRECATED report "Use reportError or reportWarning instead" #-} -- deprecated in 7.6
248 249 250 251 252 253 254 255

-- | Report an error to the user, but allow the current splice's computation to carry on. To abort the computation, use 'fail'.
reportError :: String -> Q ()
reportError = report True

-- | Report a warning to the user, and carry on.
reportWarning :: String -> Q ()
reportWarning = report False
256

257 258 259
-- | Recover from errors raised by 'reportError' or 'fail'.
recover :: Q a -- ^ handler to invoke on failure
        -> Q a -- ^ computation to run
aavogt's avatar
aavogt committed
260
        -> Q a
261 262
recover (Q r) (Q m) = Q (qRecover r m)

263 264 265 266 267
-- We don't export lookupName; the Bool isn't a great API
-- Instead we export lookupTypeName, lookupValueName
lookupName :: Bool -> String -> Q (Maybe Name)
lookupName ns s = Q (qLookupName ns s)

268 269
-- | Look up the given name in the (type namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details.
lookupTypeName :: String -> Q (Maybe Name)
270
lookupTypeName  s = Q (qLookupName True s)
271 272 273

-- | Look up the given name in the (value namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details.
lookupValueName :: String -> Q (Maybe Name)
274 275
lookupValueName s = Q (qLookupName False s)

276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
{-
Note [Name lookup]
~~~~~~~~~~~~~~~~~~
-}
{- $namelookup #namelookup#
The functions 'lookupTypeName' and 'lookupValueName' provide
a way to query the current splice's context for what names
are in scope. The function 'lookupTypeName' queries the type
namespace, whereas 'lookupValueName' queries the value namespace,
but the functions are otherwise identical.

A call @lookupValueName s@ will check if there is a value
with name @s@ in scope at the current splice's location. If
there is, the @Name@ of this value is returned;
if not, then @Nothing@ is returned.

Jan Stolarek's avatar
Jan Stolarek committed
292
The returned name cannot be \"captured\".
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
For example:

> f = "global"
> g = $( do
>          Just nm <- lookupValueName "f"
>          [| let f = "local" in $( varE nm ) |]

In this case, @g = \"global\"@; the call to @lookupValueName@
returned the global @f@, and this name was /not/ captured by
the local definition of @f@.

The lookup is performed in the context of the /top-level/ splice
being run. For example:

> f = "global"
Jan Stolarek's avatar
Jan Stolarek committed
308
> g = $( [| let f = "local" in
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344
>            $(do
>                Just nm <- lookupValueName "f"
>                varE nm
>             ) |] )

Again in this example, @g = \"global\"@, because the call to
@lookupValueName@ queries the context of the outer-most @$(...)@.

Operators should be queried without any surrounding parentheses, like so:

> lookupValueName "+"

Qualified names are also supported, like so:

> lookupValueName "Prelude.+"
> lookupValueName "Prelude.map"

-}


{- | 'reify' looks up information about the 'Name'.

It is sometimes useful to construct the argument name using 'lookupTypeName' or 'lookupValueName'
to ensure that we are reifying from the right namespace. For instance, in this context:

> data D = D

which @D@ does @reify (mkName \"D\")@ return information about? (Answer: @D@-the-type, but don't rely on it.)
To ensure we get information about @D@-the-value, use 'lookupValueName':

> do
>   Just nm <- lookupValueName "D"
>   reify nm

and to get information about @D@-the-type, use 'lookupTypeName'.
-}
345 346 347
reify :: Name -> Q Info
reify v = Q (qReify v)

Ryan Scott's avatar
Ryan Scott committed
348 349 350 351 352 353
{- | @reifyFixity nm@ returns the fixity of @nm@. If a fixity value cannot be
found, 'defaultFixity' is returned.
-}
reifyFixity :: Name -> Q Fixity
reifyFixity nm = Q (qReifyFixity nm)

Jan Stolarek's avatar
Jan Stolarek committed
354
{- | @reifyInstances nm tys@ returns a list of visible instances of @nm tys@. That is,
355 356 357 358 359
if @nm@ is the name of a type class, then all instances of this class at the types @tys@
are returned. Alternatively, if @nm@ is the name of a data family or type family,
all instances of this family at the types @tys@ are returned.
-}
reifyInstances :: Name -> [Type] -> Q [InstanceDec]
360
reifyInstances cls tys = Q (qReifyInstances cls tys)
361

362 363 364 365 366 367 368
{- | @reifyRoles nm@ returns the list of roles associated with the parameters of
the tycon @nm@. Fails if @nm@ cannot be found or is not a tycon.
The returned list should never contain 'InferR'.
-}
reifyRoles :: Name -> Q [Role]
reifyRoles nm = Q (qReifyRoles nm)

Austin Seipp's avatar
Austin Seipp committed
369 370 371 372 373 374 375
-- | @reifyAnnotations target@ returns the list of annotations
-- associated with @target@.  Only the annotations that are
-- appropriately typed is returned.  So if you have @Int@ and @String@
-- annotations for the same target, you have to call this function twice.
reifyAnnotations :: Data a => AnnLookup -> Q [a]
reifyAnnotations an = Q (qReifyAnnotations an)

376 377 378 379 380 381
-- | @reifyModule mod@ looks up information about module @mod@.  To
-- look up the current module, call this function with the return
-- value of @thisModule@.
reifyModule :: Module -> Q ModuleInfo
reifyModule m = Q (qReifyModule m)

382
-- | Is the list of instances returned by 'reifyInstances' nonempty?
383 384 385
isInstance :: Name -> [Type] -> Q Bool
isInstance nm tys = do { decs <- reifyInstances nm tys
                       ; return (not (null decs)) }
386

387
-- | The location at which this computation is spliced.
388 389
location :: Q Loc
location = Q qLocation
390

dons's avatar
dons committed
391
-- |The 'runIO' function lets you run an I\/O computation in the 'Q' monad.
Jan Stolarek's avatar
Jan Stolarek committed
392 393
-- Take care: you are guaranteed the ordering of calls to 'runIO' within
-- a single 'Q' computation, but not about the order in which splices are run.
394
--
Jan Stolarek's avatar
Jan Stolarek committed
395
-- Note: for various murky reasons, stdout and stderr handles are not
Gabor Greif's avatar
Gabor Greif committed
396
-- necessarily flushed when the compiler finishes running, so you should
397
-- flush them yourself.
398 399 400
runIO :: IO a -> Q a
runIO m = Q (qRunIO m)

GregWeber's avatar
GregWeber committed
401
-- | Record external files that runIO is using (dependent upon).
402 403 404
-- The compiler can then recognize that it should re-compile the Haskell file
-- when an external file changes.
--
GregWeber's avatar
GregWeber committed
405
-- Expects an absolute file path.
406 407 408 409 410 411
--
-- Notes:
--
--   * ghc -M does not know about these dependencies - it does not execute TH.
--
--   * The dependency is based on file content, not a modification time
GregWeber's avatar
GregWeber committed
412 413 414
addDependentFile :: FilePath -> Q ()
addDependentFile fp = Q (qAddDependentFile fp)

415 416 417 418 419
-- | Add additional top-level declarations. The added declarations will be type
-- checked along with the current declaration group.
addTopDecls :: [Dec] -> Q ()
addTopDecls ds = Q (qAddTopDecls ds)

420 421 422 423 424
-- | Add a finalizer that will run in the Q monad after the current module has
-- been type checked. This only makes sense when run within a top-level splice.
addModFinalizer :: Q () -> Q ()
addModFinalizer act = Q (qAddModFinalizer (unQ act))

gmainland's avatar
gmainland committed
425 426 427 428 429 430 431 432
-- | Get state from the Q monad.
getQ :: Typeable a => Q (Maybe a)
getQ = Q qGetQ

-- | Replace the state in the Q monad.
putQ :: Typeable a => a -> Q ()
putQ x = Q (qPutQ x)

433
instance Quasi Q where
434 435 436 437
  qNewName          = newName
  qReport           = report
  qRecover          = recover
  qReify            = reify
Ryan Scott's avatar
Ryan Scott committed
438
  qReifyFixity      = reifyFixity
GregWeber's avatar
GregWeber committed
439
  qReifyInstances   = reifyInstances
440
  qReifyRoles       = reifyRoles
Austin Seipp's avatar
Austin Seipp committed
441
  qReifyAnnotations = reifyAnnotations
442
  qReifyModule      = reifyModule
GregWeber's avatar
GregWeber committed
443
  qLookupName       = lookupName
444 445
  qLocation         = location
  qRunIO            = runIO
GregWeber's avatar
GregWeber committed
446
  qAddDependentFile = addDependentFile
447
  qAddTopDecls      = addTopDecls
448
  qAddModFinalizer  = addModFinalizer
gmainland's avatar
gmainland committed
449 450
  qGetQ             = getQ
  qPutQ             = putQ
451 452 453 454


----------------------------------------------------
-- The following operations are used solely in DsMeta when desugaring brackets
455
-- They are not necessary for the user, who can use ordinary return and (>>=) etc
456 457 458 459 460 461 462 463 464 465 466 467 468

returnQ :: a -> Q a
returnQ = return

bindQ :: Q a -> (a -> Q b) -> Q b
bindQ = (>>=)

sequenceQ :: [Q a] -> Q [a]
sequenceQ = sequence


-----------------------------------------------------
--
469
--              The Lift class
470 471 472 473 474
--
-----------------------------------------------------

class Lift t where
  lift :: t -> Q Exp
475 476
  default lift :: Data t => t -> Q Exp
  lift = liftData
Jan Stolarek's avatar
Jan Stolarek committed
477

eir@cis.upenn.edu's avatar
eir@cis.upenn.edu committed
478
-- If you add any instances here, consider updating test th/TH_Lift
479 480 481 482
instance Lift Integer where
  lift x = return (LitE (IntegerL x))

instance Lift Int where
483 484
  lift x = return (LitE (IntegerL (fromIntegral x)))

485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
instance Lift Int8 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Int16 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Int32 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Int64 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Word where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Word8 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Word16 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Word32 where
  lift x = return (LitE (IntegerL (fromIntegral x)))

instance Lift Word64 where
  lift x = return (LitE (IntegerL (fromIntegral x)))
eir@cis.upenn.edu's avatar
eir@cis.upenn.edu committed
511

512
#ifdef HAS_NATURAL
eir@cis.upenn.edu's avatar
eir@cis.upenn.edu committed
513 514
instance Lift Natural where
  lift x = return (LitE (IntegerL (fromIntegral x)))
515
#endif
516 517 518 519 520 521 522 523 524

instance Integral a => Lift (Ratio a) where
  lift x = return (LitE (RationalL (toRational x)))

instance Lift Float where
  lift x = return (LitE (RationalL (toRational x)))

instance Lift Double where
  lift x = return (LitE (RationalL (toRational x)))
525 526 527 528 529 530 531 532

instance Lift Char where
  lift x = return (LitE (CharL x))

instance Lift Bool where
  lift True  = return (ConE trueName)
  lift False = return (ConE falseName)

533 534 535 536 537 538 539 540
instance Lift a => Lift (Maybe a) where
  lift Nothing  = return (ConE nothingName)
  lift (Just x) = liftM (ConE justName `AppE`) (lift x)

instance (Lift a, Lift b) => Lift (Either a b) where
  lift (Left x)  = liftM (ConE leftName  `AppE`) (lift x)
  lift (Right y) = liftM (ConE rightName `AppE`) (lift y)

541 542 543
instance Lift a => Lift [a] where
  lift xs = do { xs' <- mapM lift xs; return (ListE xs') }

544 545 546 547
liftString :: String -> Q Exp
-- Used in TcExpr to short-circuit the lifting for strings
liftString s = return (LitE (StringL s))

548 549 550
instance Lift () where
  lift () = return (ConE (tupleDataName 0))

551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577
instance (Lift a, Lift b) => Lift (a, b) where
  lift (a, b)
    = liftM TupE $ sequence [lift a, lift b]

instance (Lift a, Lift b, Lift c) => Lift (a, b, c) where
  lift (a, b, c)
    = liftM TupE $ sequence [lift a, lift b, lift c]

instance (Lift a, Lift b, Lift c, Lift d) => Lift (a, b, c, d) where
  lift (a, b, c, d)
    = liftM TupE $ sequence [lift a, lift b, lift c, lift d]

instance (Lift a, Lift b, Lift c, Lift d, Lift e)
      => Lift (a, b, c, d, e) where
  lift (a, b, c, d, e)
    = liftM TupE $ sequence [lift a, lift b, lift c, lift d, lift e]

instance (Lift a, Lift b, Lift c, Lift d, Lift e, Lift f)
      => Lift (a, b, c, d, e, f) where
  lift (a, b, c, d, e, f)
    = liftM TupE $ sequence [lift a, lift b, lift c, lift d, lift e, lift f]

instance (Lift a, Lift b, Lift c, Lift d, Lift e, Lift f, Lift g)
      => Lift (a, b, c, d, e, f, g) where
  lift (a, b, c, d, e, f, g)
    = liftM TupE $ sequence [lift a, lift b, lift c, lift d, lift e, lift f, lift g]

578 579 580 581
-- TH has a special form for literal strings,
-- which we should take advantage of.
-- NB: the lhs of the rule has no args, so that
--     the rule will apply to a 'lift' all on its own
Jan Stolarek's avatar
Jan Stolarek committed
582
--     which happens to be the way the type checker
583 584 585 586 587
--     creates it.
{-# RULES "TH:liftString" lift = \s -> return (LitE (StringL s)) #-}


trueName, falseName :: Name
Ian Lynagh's avatar
Ian Lynagh committed
588 589
trueName  = mkNameG DataName "ghc-prim" "GHC.Types" "True"
falseName = mkNameG DataName "ghc-prim" "GHC.Types" "False"
590

591
nothingName, justName :: Name
592 593
nothingName = mkNameG DataName "base" "GHC.Base" "Nothing"
justName    = mkNameG DataName "base" "GHC.Base" "Just"
594 595 596 597 598

leftName, rightName :: Name
leftName  = mkNameG DataName "base" "Data.Either" "Left"
rightName = mkNameG DataName "base" "Data.Either" "Right"

599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
-----------------------------------------------------
--
--              Generic Lift implementations
--
-----------------------------------------------------

-- | 'dataToQa' is an internal utility function for constructing generic
-- conversion functions from types with 'Data' instances to various
-- quasi-quoting representations.  See the source of 'dataToExpQ' and
-- 'dataToPatQ' for two example usages: @mkCon@, @mkLit@
-- and @appQ@ are overloadable to account for different syntax for
-- expressions and patterns; @antiQ@ allows you to override type-specific
-- cases, a common usage is just @const Nothing@, which results in
-- no overloading.
dataToQa  ::  forall a k q. Data a
          =>  (Name -> k)
          ->  (Lit -> Q q)
          ->  (k -> [Q q] -> Q q)
          ->  (forall b . Data b => b -> Maybe (Q q))
          ->  a
          ->  Q q
dataToQa mkCon mkLit appCon antiQ t =
    case antiQ t of
      Nothing ->
          case constrRep constr of
            AlgConstr _ ->
                appCon (mkCon conName) conArgs
              where
                conName :: Name
                conName =
                    case showConstr constr of
                      "(:)"       -> Name (mkOccName ":")
                                          (NameG DataName
                                                (mkPkgName "ghc-prim")
                                                (mkModName "GHC.Types"))
                      con@"[]"    -> Name (mkOccName con)
                                          (NameG DataName
                                                (mkPkgName "ghc-prim")
                                                (mkModName "GHC.Types"))
                      con@('(':_) -> Name (mkOccName con)
                                          (NameG DataName
                                                (mkPkgName "ghc-prim")
                                                (mkModName "GHC.Tuple"))
                      con         -> mkNameG_d (tyConPackage tycon)
                                               (tyConModule tycon)
                                               con
                  where
                    tycon :: TyCon
                    tycon = (typeRepTyCon . typeOf) t

                conArgs :: [Q q]
                conArgs = gmapQ (dataToQa mkCon mkLit appCon antiQ) t
            IntConstr n ->
                mkLit $ IntegerL n
            FloatConstr n ->
                mkLit $ RationalL n
            CharConstr c ->
                mkLit $ CharL c
        where
          constr :: Constr
          constr = toConstr t

      Just y -> y

-- | 'dataToExpQ' converts a value to a 'Q Exp' representation of the
-- same value, in the SYB style. It is generalized to take a function
-- override type-specific cases; see 'liftData' for a more commonly
-- used variant.
dataToExpQ  ::  Data a
            =>  (forall b . Data b => b -> Maybe (Q Exp))
            ->  a
            ->  Q Exp
dataToExpQ = dataToQa conE litE (foldl appE)
    where conE s =  return (ConE s)
          appE x y = do { a <- x; b <- y; return (AppE a b)}
          litE c = return (LitE c)

-- | 'liftData' is a variant of 'lift' in the 'Lift' type class which
-- works for any type with a 'Data' instance.
liftData :: Data a => a -> Q Exp
liftData = dataToExpQ (const Nothing)

-- | 'dataToPatQ' converts a value to a 'Q Pat' representation of the same
-- value, in the SYB style. It takes a function to handle type-specific cases,
-- alternatively, pass @const Nothing@ to get default behavior.
dataToPatQ  ::  Data a
            =>  (forall b . Data b => b -> Maybe (Q Pat))
            ->  a
            ->  Q Pat
dataToPatQ = dataToQa id litP conP
    where litP l = return (LitP l)
          conP n ps = do ps' <- sequence ps
                         return (ConP n ps')
692 693

-----------------------------------------------------
694
--              Names and uniques
695 696
-----------------------------------------------------

697
newtype ModName = ModName String        -- Module name
698
 deriving (Show,Eq,Ord,Typeable,Data,Generic)
699

700
newtype PkgName = PkgName String        -- package name
701
 deriving (Show,Eq,Ord,Typeable,Data,Generic)
702

703 704
-- | Obtained from 'reifyModule' and 'thisModule'.
data Module = Module PkgName ModName -- package qualified module name
705
 deriving (Show,Eq,Ord,Typeable,Data,Generic)
706

707
newtype OccName = OccName String
708
 deriving (Show,Eq,Ord,Typeable,Data,Generic)
709

710
mkModName :: String -> ModName
711
mkModName s = ModName s
712 713

modString :: ModName -> String
714
modString (ModName m) = m
715

716 717

mkPkgName :: String -> PkgName
718
mkPkgName s = PkgName s
719 720

pkgString :: PkgName -> String
721
pkgString (PkgName m) = m
722 723


724
-----------------------------------------------------
725
--              OccName
726 727 728
-----------------------------------------------------

mkOccName :: String -> OccName
729
mkOccName s = OccName s
730 731

occString :: OccName -> String
732
occString (OccName occ) = occ
733 734 735


-----------------------------------------------------
736
--               Names
737
-----------------------------------------------------
Jan Stolarek's avatar
Jan Stolarek committed
738
--
aavogt's avatar
aavogt committed
739
-- For "global" names ('NameG') we need a totally unique name,
740 741
-- so we must include the name-space of the thing
--
aavogt's avatar
aavogt committed
742
-- For unique-numbered things ('NameU'), we've got a unique reference
743 744
-- anyway, so no need for name space
--
aavogt's avatar
aavogt committed
745
-- For dynamically bound thing ('NameS') we probably want them to
746 747
-- in a context-dependent way, so again we don't want the name
-- space.  For example:
aavogt's avatar
aavogt committed
748 749 750
--
-- > let v = mkName "T" in [| data $v = $v |]
--
751
-- Here we use the same Name for both type constructor and data constructor
aavogt's avatar
aavogt committed
752 753 754 755 756 757 758 759 760 761
--
--
-- NameL and NameG are bound *outside* the TH syntax tree
-- either globally (NameG) or locally (NameL). Ex:
--
-- > f x = $(h [| (map, x) |])
--
-- The 'map' will be a NameG, and 'x' wil be a NameL
--
-- These Names should never appear in a binding position in a TH syntax tree
762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786

{- $namecapture #namecapture#
Much of 'Name' API is concerned with the problem of /name capture/, which
can be seen in the following example.

> f expr = [| let x = 0 in $expr |]
> ...
> g x = $( f [| x |] )
> h y = $( f [| y |] )

A naive desugaring of this would yield:

> g x = let x = 0 in x
> h y = let x = 0 in y

All of a sudden, @g@ and @h@ have different meanings! In this case,
we say that the @x@ in the RHS of @g@ has been /captured/
by the binding of @x@ in @f@.

What we actually want is for the @x@ in @f@ to be distinct from the
@x@ in @g@, so we get the following desugaring:

> g x = let x' = 0 in x
> h y = let x' = 0 in y

Jan Stolarek's avatar
Jan Stolarek committed
787
which avoids name capture as desired.
788 789 790 791 792 793 794 795 796 797 798 799

In the general case, we say that a @Name@ can be captured if
the thing it refers to can be changed by adding new declarations.
-}

{- |
An abstract type representing names in the syntax tree.

'Name's can be constructed in several ways, which come with different
name-capture guarantees (see "Language.Haskell.TH.Syntax#namecapture" for
an explanation of name capture):

Jan Stolarek's avatar
Jan Stolarek committed
800 801
  * the built-in syntax @'f@ and @''T@ can be used to construct names,
    The expression @'f@ gives a @Name@ which refers to the value @f@
802 803
    currently in scope, and @''T@ gives a @Name@ which refers to the
    type @T@ currently in scope. These names can never be captured.
Jan Stolarek's avatar
Jan Stolarek committed
804 805

  * 'lookupValueName' and 'lookupTypeName' are similar to @'f@ and
806 807 808 809 810 811
     @''T@ respectively, but the @Name@s are looked up at the point
     where the current splice is being run. These names can never be
     captured.

  * 'newName' monadically generates a new name, which can never
     be captured.
Jan Stolarek's avatar
Jan Stolarek committed
812

813 814 815 816 817 818
  * 'mkName' generates a capturable name.

Names constructed using @newName@ and @mkName@ may be used in bindings
(such as @let x = ...@ or @\x -> ...@), but names constructed using
@lookupValueName@, @lookupTypeName@, @'f@, @''T@ may not.
-}
819
data Name = Name OccName NameFlavour deriving (Typeable, Data, Eq, Generic)
820 821 822 823 824

instance Ord Name where
    -- check if unique is different before looking at strings
  (Name o1 f1) `compare` (Name o2 f2) = (f1 `compare` f2)   `thenCmp`
                                        (o1 `compare` o2)
825 826

data NameFlavour
aavogt's avatar
aavogt committed
827 828
  = NameS           -- ^ An unqualified name; dynamically bound
  | NameQ ModName   -- ^ A qualified name; dynamically bound
829 830
  | NameU !Int      -- ^ A unique local name
  | NameL !Int      -- ^ Local name bound outside of the TH AST
aavogt's avatar
aavogt committed
831 832
  | NameG NameSpace PkgName ModName -- ^ Global name bound outside of the TH AST:
                -- An original name (occurrences only, not binders)
833 834
                -- Need the namespace too to be sure which
                -- thing we are naming
835
  deriving ( Typeable, Data, Eq, Ord, Generic )
836

837 838 839 840
data NameSpace = VarName        -- ^ Variables
               | DataName       -- ^ Data constructors
               | TcClsName      -- ^ Type constructors and classes; Haskell has them
                                -- in the same name space for now.
841
               deriving( Eq, Ord, Data, Typeable, Generic )
842 843 844

type Uniq = Int

845 846 847 848 849 850 851 852 853 854
-- | The name without its module prefix.
--
-- ==== __Examples__
--
-- >>> nameBase ''Data.Either.Either
-- "Either"
-- >>> nameBase (mkName "foo")
-- "foo"
-- >>> nameBase (mkName "Module.foo")
-- "foo"
855 856 857
nameBase :: Name -> String
nameBase (Name occ _) = occString occ

858 859 860 861 862 863 864 865 866 867
-- | Module prefix of a name, if it exists.
--
-- ==== __Examples__
--
-- >>> nameModule ''Data.Either.Either"
-- Just "Data.Either"
-- >>> nameModule (mkName "foo")
-- Nothing
-- >>> nameModule (mkName "Module.foo")
-- Just "Module"
868
nameModule :: Name -> Maybe String
Ian Lynagh's avatar
Ian Lynagh committed
869
nameModule (Name _ (NameQ m))     = Just (modString m)
870
nameModule (Name _ (NameG _ _ m)) = Just (modString m)
Ian Lynagh's avatar
Ian Lynagh committed
871
nameModule _                      = Nothing
872

873 874 875 876 877 878 879 880 881 882 883 884 885 886
-- | A name's package, if it exists.
--
-- ==== __Examples__
--
-- >>> namePackage ''Data.Either.Either"
-- Just "base"
-- >>> namePackage (mkName "foo")
-- Nothing
-- >>> namePackage (mkName "Module.foo")
-- Nothing
namePackage :: Name -> Maybe String
namePackage (Name _ (NameG _ p _)) = Just (pkgString p)
namePackage _                      = Nothing

Jan Stolarek's avatar
Jan Stolarek committed
887
{- |
888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910
Generate a capturable name. Occurrences of such names will be
resolved according to the Haskell scoping rules at the occurrence
site.

For example:

> f = [| pi + $(varE (mkName "pi")) |]
> ...
> g = let pi = 3 in $f

In this case, @g@ is desugared to

> g = Prelude.pi + 3

Note that @mkName@ may be used with qualified names:

> mkName "Prelude.pi"

See also 'Language.Haskell.TH.Lib.dyn' for a useful combinator. The above example could
be rewritten using 'dyn' as

> f = [| pi + $(dyn "pi") |]
-}
911
mkName :: String -> Name
912
-- The string can have a '.', thus "Foo.baz",
913 914 915 916 917
-- giving a dynamically-bound qualified name,
-- in which case we want to generate a NameQ
--
-- Parse the string to see if it has a "." in it
-- so we know whether to generate a qualified or unqualified name
Jan Stolarek's avatar
Jan Stolarek committed
918
-- It's a bit tricky because we need to parse
aavogt's avatar
aavogt committed
919 920 921
--
-- > Foo.Baz.x   as    Qual Foo.Baz x
--
922 923 924 925 926
-- So we parse it from back to front
mkName str
  = split [] (reverse str)
  where
    split occ []        = Name (mkOccName occ) NameS
927 928 929 930 931 932 933 934 935 936
    split occ ('.':rev) | not (null occ)
                        , is_rev_mod_name rev
                        = Name (mkOccName occ) (NameQ (mkModName (reverse rev)))
        -- The 'not (null occ)' guard ensures that
        --      mkName "&." = Name "&." NameS
        -- The 'is_rev_mod' guards ensure that
        --      mkName ".&" = Name ".&" NameS
        --      mkName "^.." = Name "^.." NameS      -- Trac #8633
        --      mkName "Data.Bits..&" = Name ".&" (NameQ "Data.Bits")
        -- This rather bizarre case actually happened; (.&.) is in Data.Bits
937
    split occ (c:rev)   = split (c:occ) rev
938

939 940
    -- Recognises a reversed module name xA.yB.C,
    -- with at least one component,
941 942 943 944 945 946 947 948 949 950 951 952 953
    -- and each component looks like a module name
    --   (i.e. non-empty, starts with capital, all alpha)
    is_rev_mod_name rev_mod_str
      | (compt, rest) <- break (== '.') rev_mod_str
      , not (null compt), isUpper (last compt), all is_mod_char compt
      = case rest of
          []             -> True
          (_dot : rest') -> is_rev_mod_name rest'
      | otherwise
      = False

    is_mod_char c = isAlphaNum c || c == '_' || c == '\''

aavogt's avatar
aavogt committed
954 955
-- | Only used internally
mkNameU :: String -> Uniq -> Name
956
mkNameU s u = Name (mkOccName s) (NameU u)
957

aavogt's avatar
aavogt committed
958 959
-- | Only used internally
mkNameL :: String -> Uniq -> Name
960
mkNameL s u = Name (mkOccName s) (NameL u)
961

aavogt's avatar
aavogt committed
962 963 964
-- | Used for 'x etc, but not available to the programmer
mkNameG :: NameSpace -> String -> String -> String -> Name
mkNameG ns pkg modu occ
Ian Lynagh's avatar
Ian Lynagh committed
965
  = Name (mkOccName occ) (NameG ns (mkPkgName pkg) (mkModName modu))
966

967
mkNameG_v, mkNameG_tc, mkNameG_d :: String -> String -> String -> Name
968 969 970 971
mkNameG_v  = mkNameG VarName
mkNameG_tc = mkNameG TcClsName
mkNameG_d  = mkNameG DataName

Ian Lynagh's avatar
Ian Lynagh committed
972 973 974 975 976 977 978 979 980 981 982 983 984 985 986
data NameIs = Alone | Applied | Infix

showName :: Name -> String
showName = showName' Alone

showName' :: NameIs -> Name -> String
showName' ni nm
 = case ni of
       Alone        -> nms
       Applied
        | pnam      -> nms
        | otherwise -> "(" ++ nms ++ ")"
       Infix
        | pnam      -> "`" ++ nms ++ "`"
        | otherwise -> nms
987
    where
988 989 990 991 992 993
        -- For now, we make the NameQ and NameG print the same, even though
        -- NameQ is a qualified name (so what it means depends on what the
        -- current scope is), and NameG is an original name (so its meaning
        -- should be independent of what's in scope.
        -- We may well want to distinguish them in the end.
        -- Ditto NameU and NameL
994
        nms = case nm of
Ian Lynagh's avatar
Ian Lynagh committed
995 996 997
                    Name occ NameS         -> occString occ
                    Name occ (NameQ m)     -> modString m ++ "." ++ occString occ
                    Name occ (NameG _ _ m) -> modString m ++ "." ++ occString occ
998 999
                    Name occ (NameU u)     -> occString occ ++ "_" ++ show u
                    Name occ (NameL u)     -> occString occ ++ "_" ++ show u
1000 1001 1002

        pnam = classify nms

Ian Lynagh's avatar
Ian Lynagh committed
1003 1004
        -- True if we are function style, e.g. f, [], (,)
        -- False if we are operator style, e.g. +, :+
1005
        classify "" = False -- shouldn't happen; . operator is handled below
Ian Lynagh's avatar
Ian Lynagh committed
1006
        classify (x:xs) | isAlpha x || (x `elem` "_[]()") =
1007 1008 1009 1010
                            case dropWhile (/='.') xs of
                                  (_:xs') -> classify xs'
                                  []      -> True
                        | otherwise = False
1011

1012
instance Show Name where
Ian Lynagh's avatar
Ian Lynagh committed
1013
  show = showName
1014

1015
-- Tuple data and type constructors
1016 1017 1018 1019
-- | Tuple data constructor
tupleDataName :: Int -> Name
-- | Tuple type constructor
tupleTypeName :: Int -> Name
1020

1021
tupleDataName 0 = mk_tup_name 0 DataName
1022
tupleDataName 1 = error "tupleDataName 1"
1023
tupleDataName n = mk_tup_name (n-1) DataName
1024

1025
tupleTypeName 0 = mk_tup_name 0 TcClsName
1026
tupleTypeName 1 = error "tupleTypeName 1"
1027
tupleTypeName n = mk_tup_name (n-1) TcClsName
1028

Ian Lynagh's avatar
Ian Lynagh committed
1029
mk_tup_name :: Int -> NameSpace -> Name
1030
mk_tup_name n_commas space
Ian Lynagh's avatar
Ian Lynagh committed
1031
  = Name occ (NameG space (mkPkgName "ghc-prim") tup_mod)
1032 1033
  where
    occ = mkOccName ('(' : replicate n_commas ',' ++ ")")
Ian Lynagh's avatar
Ian Lynagh committed
1034
    tup_mod = mkModName "GHC.Tuple"
1035

1036
-- Unboxed tuple data and type constructors
1037 1038 1039 1040
-- | Unboxed tuple data constructor
unboxedTupleDataName :: Int -> Name
-- | Unboxed tuple type constructor
unboxedTupleTypeName :: Int -> Name
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056

unboxedTupleDataName 0 = error "unboxedTupleDataName 0"
unboxedTupleDataName 1 = error "unboxedTupleDataName 1"
unboxedTupleDataName n = mk_unboxed_tup_name (n-1) DataName

unboxedTupleTypeName 0 = error "unboxedTupleTypeName 0"
unboxedTupleTypeName 1 = error "unboxedTupleTypeName 1"
unboxedTupleTypeName n = mk_unboxed_tup_name (n-1) TcClsName

mk_unboxed_tup_name :: Int -> NameSpace -> Name
mk_unboxed_tup_name n_commas space
  = Name occ (NameG space (mkPkgName "ghc-prim") tup_mod)
  where
    occ = mkOccName ("(#" ++ replicate n_commas ',' ++ "#)")
    tup_mod = mkModName "GHC.Tuple"

1057

1058

1059
-----------------------------------------------------
1060
--              Locations
1061 1062 1063 1064
-----------------------------------------------------

data Loc
  = Loc { loc_filename :: String
1065 1066 1067 1068
        , loc_package  :: String
        , loc_module   :: String
        , loc_start    :: CharPos
        , loc_end      :: CharPos }
eir@cis.upenn.edu's avatar
eir@cis.upenn.edu committed
1069
   deriving( Show, Eq, Ord, Data, Typeable, Generic )
1070

1071
type CharPos = (Int, Int)       -- ^ Line and character position
1072

1073

1074 1075
-----------------------------------------------------
--
1076
--      The Info returned by reification
1077 1078 1079
--
-----------------------------------------------------

aavogt's avatar
aavogt committed
1080 1081
-- | Obtained from 'reify' in the 'Q' Monad.
data Info
Jan Stolarek's avatar
Jan Stolarek committed
1082
  =
1083
  -- | A class, with a list of its visible instances
Jan Stolarek's avatar
Jan Stolarek committed
1084
  ClassI
1085 1086
      Dec
      [InstanceDec]
Jan Stolarek's avatar
Jan Stolarek committed
1087

1088
  -- | A class method