    {-
    (c) The University of Glasgow 2006
    (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
    -}

    {-# LANGUAGE CPP, DeriveDataTypeable #-}

    -- |
    -- #name_types#
    -- GHC uses several kinds of name internally:
    --
    -- * 'OccName.OccName': see "OccName#name_types"
    --
    -- * 'RdrName.RdrName' is the type of names that come directly from the parser. They
    --   have not yet had their scoping and binding resolved by the renamer and can be
    --   thought of to a first approximation as an 'OccName.OccName' with an optional module
    --   qualifier
    --
    -- * 'Name.Name': see "Name#name_types"
    --
    -- * 'Id.Id': see "Id#name_types"
    --
    -- * 'Var.Var': see "Var#name_types"

    module RdrName (
            -- * The main type
            RdrName(..),    -- Constructors exported only to BinIface

            -- ** Construction
            mkRdrUnqual, mkRdrQual,
            mkUnqual, mkVarUnqual, mkQual, mkOrig,
            nameRdrName, getRdrName,

            -- ** Destruction
            rdrNameOcc, rdrNameSpace, demoteRdrName,
            isRdrDataCon, isRdrTyVar, isRdrTc, isQual, isQual_maybe, isUnqual,
            isOrig, isOrig_maybe, isExact, isExact_maybe, isSrcRdrName,

            -- * Local mapping of 'RdrName' to 'Name.Name'
            LocalRdrEnv, emptyLocalRdrEnv, extendLocalRdrEnv, extendLocalRdrEnvList,
            lookupLocalRdrEnv, lookupLocalRdrOcc,
            elemLocalRdrEnv, inLocalRdrEnvScope,
            localRdrEnvElts, delLocalRdrEnvList,

            -- * Global mapping of 'RdrName' to 'GlobalRdrElt's
            GlobalRdrEnv, emptyGlobalRdrEnv, mkGlobalRdrEnv, plusGlobalRdrEnv,
            lookupGlobalRdrEnv, extendGlobalRdrEnv, greOccName, shadowNames,
            pprGlobalRdrEnv, globalRdrEnvElts,
            lookupGRE_RdrName, lookupGRE_Name, lookupGRE_Field_Name, getGRE_NameQualifier_maybes,
            transformGREs, pickGREs, pickGREsModExp,

            -- * GlobalRdrElts
            gresFromAvails, gresFromAvail, localGREsFromAvail, availFromGRE,
            greUsedRdrName, greRdrNames, greSrcSpan, greQualModName,

            -- ** Global 'RdrName' mapping elements: 'GlobalRdrElt', 'Provenance', 'ImportSpec'
            GlobalRdrElt(..), isLocalGRE, isRecFldGRE, greLabel,
            unQualOK, qualSpecOK, unQualSpecOK,
            pprNameProvenance,
            Parent(..),
            ImportSpec(..), ImpDeclSpec(..), ImpItemSpec(..),
            importSpecLoc, importSpecModule, isExplicitItem, bestImport
      ) where

    #include "HsVersions.h"

    import Module
    import Name
    import Avail
    import NameSet
    import Maybes
    import SrcLoc
    import FastString
    import FieldLabel
    import Outputable
    import Unique
    import Util
    import StaticFlags( opt_PprStyle_Debug )

    import Data.Data
    import Data.List( sortBy )

    {-
    ************************************************************************
    *                                                                      *
    \subsection{The main data type}
    *                                                                      *
    ************************************************************************
    -}

    -- | Do not use the data constructors of RdrName directly: prefer the family
    -- of functions that creates them, such as 'mkRdrUnqual'
    --
    -- - Note: A Located RdrName will only have API Annotations if it is a
    --         compound one,
    --   e.g.
    --
    -- > `bar`
    -- > ( ~ )
    --
    -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnType',
    --           'ApiAnnotation.AnnOpen'  @'('@ or @'['@ or @'[:'@,
    --           'ApiAnnotation.AnnClose' @')'@ or @']'@ or @':]'@,,
    --           'ApiAnnotation.AnnBackquote' @'`'@,
    --           'ApiAnnotation.AnnVal','ApiAnnotation.AnnTildehsh',
    --           'ApiAnnotation.AnnTilde',

    -- For details on above see note [Api annotations] in ApiAnnotation
    data RdrName
      = Unqual OccName
            -- ^ Used for ordinary, unqualified occurrences, e.g. @x@, @y@ or @Foo@.
            -- Create such a 'RdrName' with 'mkRdrUnqual'

      | Qual ModuleName OccName
            -- ^ A qualified name written by the user in
            -- /source/ code.  The module isn't necessarily
            -- the module where the thing is defined;
            -- just the one from which it is imported.
            -- Examples are @Bar.x@, @Bar.y@ or @Bar.Foo@.
            -- Create such a 'RdrName' with 'mkRdrQual'

      | Orig Module OccName
            -- ^ An original name; the module is the /defining/ module.
            -- This is used when GHC generates code that will be fed
            -- into the renamer (e.g. from deriving clauses), but where
            -- we want to say \"Use Prelude.map dammit\". One of these
            -- can be created with 'mkOrig'

      | Exact Name
            -- ^ We know exactly the 'Name'. This is used:
            --
            --  (1) When the parser parses built-in syntax like @[]@
            --      and @(,)@, but wants a 'RdrName' from it
            --
            --  (2) By Template Haskell, when TH has generated a unique name
            --
            -- Such a 'RdrName' can be created by using 'getRdrName' on a 'Name'
      deriving (Data, Typeable)

    {-
    ************************************************************************
    *                                                                      *
    \subsection{Simple functions}
    *                                                                      *
    ************************************************************************
    -}

    instance HasOccName RdrName where
      occName = rdrNameOcc

    rdrNameOcc :: RdrName -> OccName
    rdrNameOcc (Qual _ occ) = occ
    rdrNameOcc (Unqual occ) = occ
    rdrNameOcc (Orig _ occ) = occ
    rdrNameOcc (Exact name) = nameOccName name

    rdrNameSpace :: RdrName -> NameSpace
    rdrNameSpace = occNameSpace . rdrNameOcc

    -- demoteRdrName lowers the NameSpace of RdrName.
    -- see Note [Demotion] in OccName
    demoteRdrName :: RdrName -> Maybe RdrName
    demoteRdrName (Unqual occ) = fmap Unqual (demoteOccName occ)
    demoteRdrName (Qual m occ) = fmap (Qual m) (demoteOccName occ)
    demoteRdrName (Orig _ _) = panic "demoteRdrName"
    demoteRdrName (Exact _) = panic "demoteRdrName"

            -- These two are the basic constructors
    mkRdrUnqual :: OccName -> RdrName
    mkRdrUnqual occ = Unqual occ

    mkRdrQual :: ModuleName -> OccName -> RdrName
    mkRdrQual mod occ = Qual mod occ

    mkOrig :: Module -> OccName -> RdrName
    mkOrig mod occ = Orig mod occ

    ---------------
            -- These two are used when parsing source files
            -- They do encode the module and occurrence names
    mkUnqual :: NameSpace -> FastString -> RdrName
    mkUnqual sp n = Unqual (mkOccNameFS sp n)

    mkVarUnqual :: FastString -> RdrName
    mkVarUnqual n = Unqual (mkVarOccFS n)

    -- | Make a qualified 'RdrName' in the given namespace and where the 'ModuleName' and
    -- the 'OccName' are taken from the first and second elements of the tuple respectively
    mkQual :: NameSpace -> (FastString, FastString) -> RdrName
    mkQual sp (m, n) = Qual (mkModuleNameFS m) (mkOccNameFS sp n)

    getRdrName :: NamedThing thing => thing -> RdrName
    getRdrName name = nameRdrName (getName name)

    nameRdrName :: Name -> RdrName
    nameRdrName name = Exact name
    -- Keep the Name even for Internal names, so that the
    -- unique is still there for debug printing, particularly
    -- of Types (which are converted to IfaceTypes before printing)

    nukeExact :: Name -> RdrName
    nukeExact n
      | isExternalName n = Orig (nameModule n) (nameOccName n)
      | otherwise        = Unqual (nameOccName n)

    isRdrDataCon :: RdrName -> Bool
    isRdrTyVar   :: RdrName -> Bool
    isRdrTc      :: RdrName -> Bool

    isRdrDataCon rn = isDataOcc (rdrNameOcc rn)
    isRdrTyVar   rn = isTvOcc   (rdrNameOcc rn)
    isRdrTc      rn = isTcOcc   (rdrNameOcc rn)

    isSrcRdrName :: RdrName -> Bool
    isSrcRdrName (Unqual _) = True
    isSrcRdrName (Qual _ _) = True
    isSrcRdrName _          = False

    isUnqual :: RdrName -> Bool
    isUnqual (Unqual _) = True
    isUnqual _          = False

    isQual :: RdrName -> Bool
    isQual (Qual _ _) = True
    isQual _          = False

    isQual_maybe :: RdrName -> Maybe (ModuleName, OccName)
    isQual_maybe (Qual m n) = Just (m,n)
    isQual_maybe _          = Nothing

    isOrig :: RdrName -> Bool
    isOrig (Orig _ _) = True
    isOrig _          = False

    isOrig_maybe :: RdrName -> Maybe (Module, OccName)
    isOrig_maybe (Orig m n) = Just (m,n)
    isOrig_maybe _          = Nothing

    isExact :: RdrName -> Bool
    isExact (Exact _) = True
    isExact _         = False

    isExact_maybe :: RdrName -> Maybe Name
    isExact_maybe (Exact n) = Just n
    isExact_maybe _         = Nothing

    {-
    ************************************************************************
    *                                                                      *
    \subsection{Instances}
    *                                                                      *
    ************************************************************************
    -}

    instance Outputable RdrName where
        ppr (Exact name)   = ppr name
        ppr (Unqual occ)   = ppr occ
        ppr (Qual mod occ) = ppr mod <> dot <> ppr occ
        ppr (Orig mod occ) = getPprStyle (\sty -> pprModulePrefix sty mod occ <> ppr occ)

    instance OutputableBndr RdrName where
        pprBndr _ n
            | isTvOcc (rdrNameOcc n) = char '@' <+> ppr n
            | otherwise              = ppr n

        pprInfixOcc  rdr = pprInfixVar  (isSymOcc (rdrNameOcc rdr)) (ppr rdr)
        pprPrefixOcc rdr
          | Just name <- isExact_maybe rdr = pprPrefixName name
                 -- pprPrefixName has some special cases, so
                 -- we delegate to them rather than reproduce them
          | otherwise = pprPrefixVar (isSymOcc (rdrNameOcc rdr)) (ppr rdr)

    instance Eq RdrName where
        (Exact n1)    == (Exact n2)    = n1==n2
            -- Convert exact to orig
        (Exact n1)    == r2@(Orig _ _) = nukeExact n1 == r2
        r1@(Orig _ _) == (Exact n2)    = r1 == nukeExact n2

        (Orig m1 o1)  == (Orig m2 o2)  = m1==m2 && o1==o2
        (Qual m1 o1)  == (Qual m2 o2)  = m1==m2 && o1==o2
        (Unqual o1)   == (Unqual o2)   = o1==o2
        _             == _             = False

    instance Ord RdrName where
        a <= b = case (a `compare` b) of { LT -> True;  EQ -> True;  GT -> False }
        a <  b = case (a `compare` b) of { LT -> True;  EQ -> False; GT -> False }
        a >= b = case (a `compare` b) of { LT -> False; EQ -> True;  GT -> True  }
        a >  b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True  }

            -- Exact < Unqual < Qual < Orig
            -- [Note: Apr 2004] We used to use nukeExact to convert Exact to Orig
            --      before comparing so that Prelude.map == the exact Prelude.map, but
            --      that meant that we reported duplicates when renaming bindings
            --      generated by Template Haskell; e.g
            --      do { n1 <- newName "foo"; n2 <- newName "foo";
            --           <decl involving n1,n2> }
            --      I think we can do without this conversion
        compare (Exact n1) (Exact n2) = n1 `compare` n2
        compare (Exact _)  _          = LT

        compare (Unqual _)   (Exact _)    = GT
        compare (Unqual o1)  (Unqual  o2) = o1 `compare` o2
        compare (Unqual _)   _            = LT

        compare (Qual _ _)   (Exact _)    = GT
        compare (Qual _ _)   (Unqual _)   = GT
        compare (Qual m1 o1) (Qual m2 o2) = (o1 `compare` o2) `thenCmp` (m1 `compare` m2)
        compare (Qual _ _)   (Orig _ _)   = LT

        compare (Orig m1 o1) (Orig m2 o2) = (o1 `compare` o2) `thenCmp` (m1 `compare` m2)
        compare (Orig _ _)   _            = GT

    {-
    ************************************************************************
    *                                                                      *
                            LocalRdrEnv
    *                                                                      *
    ************************************************************************
    -}

    -- | This environment is used to store local bindings (@let@, @where@, lambda, @case@).
    -- It is keyed by OccName, because we never use it for qualified names
    -- We keep the current mapping, *and* the set of all Names in scope
    -- Reason: see Note [Splicing Exact names] in RnEnv
    -- The field lre_nwcs is used to keep names of type variables that should
    -- be replaced with named wildcards.
    -- See Note [Renaming named wild cards] in RnTypes
    data LocalRdrEnv = LRE { lre_env      :: OccEnv Name
                           , lre_in_scope :: NameSet }

    instance Outputable LocalRdrEnv where
      ppr (LRE {lre_env = env, lre_in_scope = ns})
        = hang (text "LocalRdrEnv {")
             2 (vcat [ text "env =" <+> pprOccEnv ppr_elt env
                     , text "in_scope ="
                        <+> braces (pprWithCommas ppr (nameSetElems ns))
                     ] <+> char '}')
        where
          ppr_elt name = parens (ppr (getUnique (nameOccName name))) <+> ppr name
                         -- So we can see if the keys line up correctly

    emptyLocalRdrEnv :: LocalRdrEnv
    emptyLocalRdrEnv = LRE { lre_env = emptyOccEnv
                           , lre_in_scope = emptyNameSet }

    extendLocalRdrEnv :: LocalRdrEnv -> Name -> LocalRdrEnv
    -- The Name should be a non-top-level thing
    extendLocalRdrEnv lre@(LRE { lre_env = env, lre_in_scope = ns }) name
      = WARN( isExternalName name, ppr name )
        lre { lre_env      = extendOccEnv env (nameOccName name) name
            , lre_in_scope = extendNameSet ns name }

    extendLocalRdrEnvList :: LocalRdrEnv -> [Name] -> LocalRdrEnv
    extendLocalRdrEnvList lre@(LRE { lre_env = env, lre_in_scope = ns }) names
      = WARN( any isExternalName names, ppr names )
        lre { lre_env = extendOccEnvList env [(nameOccName n, n) | n <- names]
            , lre_in_scope = extendNameSetList ns names }

    lookupLocalRdrEnv :: LocalRdrEnv -> RdrName -> Maybe Name
    lookupLocalRdrEnv (LRE { lre_env = env, lre_in_scope = ns }) rdr
      | Unqual occ <- rdr
      = lookupOccEnv env occ

      -- See Note [Local bindings with Exact Names]
      | Exact name <- rdr
      , name `elemNameSet` ns
      = Just name

      | otherwise
      = Nothing

    lookupLocalRdrOcc :: LocalRdrEnv -> OccName -> Maybe Name
    lookupLocalRdrOcc (LRE { lre_env = env }) occ = lookupOccEnv env occ

    elemLocalRdrEnv :: RdrName -> LocalRdrEnv -> Bool
    elemLocalRdrEnv rdr_name (LRE { lre_env = env, lre_in_scope = ns })
      = case rdr_name of
          Unqual occ -> occ  `elemOccEnv` env
          Exact name -> name `elemNameSet` ns  -- See Note [Local bindings with Exact Names]
          Qual {} -> False
          Orig {} -> False

    localRdrEnvElts :: LocalRdrEnv -> [Name]
    localRdrEnvElts (LRE { lre_env = env }) = occEnvElts env

    inLocalRdrEnvScope :: Name -> LocalRdrEnv -> Bool
    -- This is the point of the NameSet
    inLocalRdrEnvScope name (LRE { lre_in_scope = ns }) = name `elemNameSet` ns

    delLocalRdrEnvList :: LocalRdrEnv -> [OccName] -> LocalRdrEnv
    delLocalRdrEnvList lre@(LRE { lre_env = env }) occs
      = lre { lre_env = delListFromOccEnv env occs }

    {-
    Note [Local bindings with Exact Names]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    With Template Haskell we can make local bindings that have Exact Names.
    Computing shadowing etc may use elemLocalRdrEnv (at least it certainly
    does so in RnTpes.bindHsQTyVars), so for an Exact Name we must consult
    the in-scope-name-set.

    ************************************************************************
    *                                                                      *
                            GlobalRdrEnv
    *                                                                      *
    ************************************************************************
    -}

    type GlobalRdrEnv = OccEnv [GlobalRdrElt]
    -- ^ Keyed by 'OccName'; when looking up a qualified name
    -- we look up the 'OccName' part, and then check the 'Provenance'
    -- to see if the appropriate qualification is valid.  This
    -- saves routinely doubling the size of the env by adding both
    -- qualified and unqualified names to the domain.
    --
    -- The list in the codomain is required because there may be name clashes
    -- These only get reported on lookup, not on construction
    --
    -- INVARIANT 1: All the members of the list have distinct
    --              'gre_name' fields; that is, no duplicate Names
    --
    -- INVARIANT 2: Imported provenance => Name is an ExternalName
    --              However LocalDefs can have an InternalName.  This
    --              happens only when type-checking a [d| ... |] Template
    --              Haskell quotation; see this note in RnNames
    --              Note [Top-level Names in Template Haskell decl quotes]

    -- | An element of the 'GlobalRdrEnv'
    data GlobalRdrElt
      = GRE { gre_name :: Name
            , gre_par  :: Parent
            , gre_lcl :: Bool          -- ^ True <=> the thing was defined locally
            , gre_imp :: [ImportSpec]  -- ^ In scope through these imports
        } deriving (Data, Typeable)
             -- INVARIANT: either gre_lcl = True or gre_imp is non-empty
             -- See Note [GlobalRdrElt provenance]

    -- | The children of a Name are the things that are abbreviated by the ".."
    --   notation in export lists.  See Note [Parents]
    data Parent = NoParent
                | ParentIs  { par_is :: Name }
                | FldParent { par_is :: Name, par_lbl :: Maybe FieldLabelString }
                  -- ^ See Note [Parents for record fields]
                | PatternSynonym
                deriving (Eq, Data, Typeable)

    instance Outputable Parent where
       ppr NoParent        = empty
       ppr (ParentIs n)    = text "parent:" <> ppr n
       ppr (FldParent n f) = text "fldparent:"
                                 <> ppr n <> colon <> ppr f
       ppr (PatternSynonym) = text "pattern synonym"

    plusParent :: Parent -> Parent -> Parent
    -- See Note [Combining parents]
    plusParent p1@(ParentIs _)    p2 = hasParent p1 p2
    plusParent p1@(FldParent _ _) p2 = hasParent p1 p2
    plusParent p1 p2@(ParentIs _)    = hasParent p2 p1
    plusParent p1 p2@(FldParent _ _) = hasParent p2 p1
    plusParent PatternSynonym PatternSynonym = PatternSynonym
    plusParent _ _                   = NoParent

    hasParent :: Parent -> Parent -> Parent
    #ifdef DEBUG
    hasParent p NoParent = p
    hasParent p p'
      | p /= p' = pprPanic "hasParent" (ppr p <+> ppr p')  -- Parents should agree
    #endif
    hasParent p _  = p

    {- Note [GlobalRdrElt provenance]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The gre_lcl and gre_imp fields of a GlobalRdrElt describe its "provenance",
    i.e. how the Name came to be in scope.  It can be in scope two ways:
      - gre_lcl = True: it is bound in this module
      - gre_imp: a list of all the imports that brought it into scope

    It's an INVARIANT that you have one or the other; that is, either
    gre_lcl is True, or gre_imp is non-empty.

    It is just possible to have *both* if there is a module loop: a Name
    is defined locally in A, and also brought into scope by importing a
    module that SOURCE-imported A.  Exapmle (Trac #7672):

     A.hs-boot   module A where
                   data T

     B.hs        module B(Decl.T) where
                   import {-# SOURCE #-} qualified A as Decl

     A.hs        module A where
                   import qualified B
                   data T = Z | S B.T

    In A.hs, 'T' is locally bound, *and* imported as B.T.

    Note [Parents]
    ~~~~~~~~~~~~~~~~~
      Parent           Children
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      data T           Data constructors
                       Record-field ids

      data family T    Data constructors and record-field ids
                       of all visible data instances of T

      class C          Class operations
                       Associated type constructors

    The `PatternSynonym` constructor is so called as pattern synonyms can be
    bundled with any type constructor (during renaming). In other words, they can
    have any parent.

    ~~~~~~~~~~~~~~~~~~~~~~~~~
     Constructor      Meaning
     ~~~~~~~~~~~~~~~~~~~~~~~~
      NoParent        Can not be bundled with a type constructor.
      ParentIs n      Can be bundled with the type constructor corresponding to
                      n.
      PatternSynonym  Can be bundled with any type constructor. It is so called
                      because only pattern synonyms can be bundled with any type
                      constructor.
      FldParent       See Note [Parents for record fields]

    Note [Parents for record fields]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    For record fields, in addition to the Name of the type constructor
    (stored in par_is), we use FldParent to store the field label.  This
    extra information is used for identifying overloaded record fields
    during renaming.

    In a definition arising from a normal module (without
    -XDuplicateRecordFields), par_lbl will be Nothing, meaning that the
    field's label is the same as the OccName of the selector's Name.  The
    GlobalRdrEnv will contain an entry like this:

        "x" |->  GRE x (FldParent T Nothing) LocalDef

    When -XDuplicateRecordFields is enabled for the module that contains
    T, the selector's Name will be mangled (see comments in FieldLabel).
    Thus we store the actual field label in par_lbl, and the GlobalRdrEnv
    entry looks like this:

        "x" |->  GRE $sel:x:MkT (FldParent T (Just "x")) LocalDef

    Note that the OccName used when adding a GRE to the environment
    (greOccName) now depends on the parent field: for FldParent it is the
    field label, if present, rather than the selector name.

    Note [Combining parents]
    ~~~~~~~~~~~~~~~~~~~~~~~~
    With an associated type we might have
       module M where
         class C a where
           data T a
           op :: T a -> a
         instance C Int where
           data T Int = TInt
         instance C Bool where
           data T Bool = TBool

    Then:   C is the parent of T
            T is the parent of TInt and TBool
    So: in an export list
        C(..) is short for C( op, T )
        T(..) is short for T( TInt, TBool )

    Module M exports everything, so its exports will be
       AvailTC C [C,T,op]
       AvailTC T [T,TInt,TBool]
    On import we convert to GlobalRdrElt and then combine
    those.  For T that will mean we have
      one GRE with Parent C
      one GRE with NoParent
    That's why plusParent picks the "best" case.
    -}

    -- | make a 'GlobalRdrEnv' where all the elements point to the same
    -- Provenance (useful for "hiding" imports, or imports with no details).
    gresFromAvails :: Maybe ImportSpec -> [AvailInfo] -> [GlobalRdrElt]
    -- prov = Nothing   => locally bound
    --        Just spec => imported as described by spec
    gresFromAvails prov avails
      = concatMap (gresFromAvail (const prov)) avails

    localGREsFromAvail :: AvailInfo -> [GlobalRdrElt]
    -- Turn an Avail into a list of LocalDef GlobalRdrElts
    localGREsFromAvail = gresFromAvail (const Nothing)

    gresFromAvail :: (Name -> Maybe ImportSpec) -> AvailInfo -> [GlobalRdrElt]
    gresFromAvail prov_fn avail
      = map mk_gre (availNonFldNames avail) ++ map mk_fld_gre (availFlds avail)
      where
        mk_gre n
          = case prov_fn n of  -- Nothing => bound locally
                               -- Just is => imported from 'is'
              Nothing -> GRE { gre_name = n, gre_par = mkParent n avail
                             , gre_lcl = True, gre_imp = [] }
              Just is -> GRE { gre_name = n, gre_par = mkParent n avail
                             , gre_lcl = False, gre_imp = [is] }

        mk_fld_gre (FieldLabel lbl is_overloaded n)
          = case prov_fn n of  -- Nothing => bound locally
                               -- Just is => imported from 'is'
              Nothing -> GRE { gre_name = n, gre_par = FldParent (availName avail) mb_lbl
                             , gre_lcl = True, gre_imp = [] }
              Just is -> GRE { gre_name = n, gre_par = FldParent (availName avail) mb_lbl
                             , gre_lcl = False, gre_imp = [is] }
          where
            mb_lbl | is_overloaded = Just lbl
                   | otherwise     = Nothing

    greQualModName :: GlobalRdrElt -> ModuleName
    -- Get a suitable module qualifier for the GRE
    -- (used in mkPrintUnqualified)
    -- Prerecondition: the gre_name is always External
    greQualModName gre@(GRE { gre_name = name, gre_lcl = lcl, gre_imp = iss })
     | lcl, Just mod <- nameModule_maybe name = moduleName mod
     | (is:_) <- iss                          = is_as (is_decl is)
     | otherwise                              = pprPanic "greQualModName" (ppr gre)

    greUsedRdrName :: GlobalRdrElt -> RdrName
    -- For imported things, return a RdrName to add to the used-RdrName
    -- set, which is used to generate unused-import-decl warnings.
    -- Return a Qual RdrName if poss, so that identifies the most
    -- specific ImportSpec.  See Trac #10890 for some good examples.
    greUsedRdrName gre@GRE{ gre_name = name, gre_lcl = lcl, gre_imp = iss }
      | lcl, Just mod <- nameModule_maybe name = Qual (moduleName mod)     occ
      | not (null iss), is <- bestImport iss   = Qual (is_as (is_decl is)) occ
      | otherwise                              = pprTrace "greUsedRdrName" (ppr gre) (Unqual occ)
      where
        occ = greOccName gre

    greRdrNames :: GlobalRdrElt -> [RdrName]
    greRdrNames gre@GRE{ gre_lcl = lcl, gre_imp = iss }
      = (if lcl then [unqual] else []) ++ concatMap do_spec (map is_decl iss)
      where
        occ    = greOccName gre
        unqual = Unqual occ
        do_spec decl_spec
            | is_qual decl_spec = [qual]
            | otherwise         = [unqual,qual]
            where qual = Qual (is_as decl_spec) occ

    -- the SrcSpan that pprNameProvenance prints out depends on whether
    -- the Name is defined locally or not: for a local definition the
    -- definition site is used, otherwise the location of the import
    -- declaration.  We want to sort the export locations in
    -- exportClashErr by this SrcSpan, we need to extract it:
    greSrcSpan :: GlobalRdrElt -> SrcSpan
    greSrcSpan gre@(GRE { gre_name = name, gre_lcl = lcl, gre_imp = iss } )
      | lcl           = nameSrcSpan name
      | (is:_) <- iss = is_dloc (is_decl is)
      | otherwise     = pprPanic "greSrcSpan" (ppr gre)

    mkParent :: Name -> AvailInfo -> Parent
    mkParent _ (Avail NotPatSyn _)           = NoParent
    mkParent _ (Avail IsPatSyn  _)           = PatternSynonym
    mkParent n (AvailTC m _ _) | n == m    = NoParent
                             | otherwise = ParentIs m

    availFromGRE :: GlobalRdrElt -> AvailInfo
    availFromGRE (GRE { gre_name = me, gre_par = parent })
      = case parent of
          ParentIs p                  -> AvailTC p [me] []
          NoParent   | isTyConName me -> AvailTC me [me] []
                     | otherwise      -> avail   me
          FldParent p Nothing         -> AvailTC p [] [FieldLabel (occNameFS $ nameOccName me) False me]
          FldParent p (Just lbl)      -> AvailTC p [] [FieldLabel lbl True me]
          PatternSynonym              -> patSynAvail me

    emptyGlobalRdrEnv :: GlobalRdrEnv
    emptyGlobalRdrEnv = emptyOccEnv

    globalRdrEnvElts :: GlobalRdrEnv -> [GlobalRdrElt]
    globalRdrEnvElts env = foldOccEnv (++) [] env

    instance Outputable GlobalRdrElt where
      ppr gre = hang (ppr (gre_name gre) <+> ppr (gre_par gre))
                   2 (pprNameProvenance gre)

    pprGlobalRdrEnv :: Bool -> GlobalRdrEnv -> SDoc
    pprGlobalRdrEnv locals_only env
      = vcat [ text "GlobalRdrEnv" <+> ppWhen locals_only (ptext (sLit "(locals only)"))
                 <+> lbrace
             , nest 2 (vcat [ pp (remove_locals gre_list) | gre_list <- occEnvElts env ]
                 <+> rbrace) ]
      where
        remove_locals gres | locals_only = filter isLocalGRE gres
                           | otherwise   = gres
        pp []   = empty
        pp gres = hang (ppr occ
                         <+> parens (text "unique" <+> ppr (getUnique occ))
                         <> colon)
                     2 (vcat (map ppr gres))
          where
            occ = nameOccName (gre_name (head gres))

    lookupGlobalRdrEnv :: GlobalRdrEnv -> OccName -> [GlobalRdrElt]
    lookupGlobalRdrEnv env occ_name = case lookupOccEnv env occ_name of
                                      Nothing   -> []
                                      Just gres -> gres

    greOccName :: GlobalRdrElt -> OccName
    greOccName (GRE{gre_par = FldParent{par_lbl = Just lbl}}) = mkVarOccFS lbl
    greOccName gre                                            = nameOccName (gre_name gre)

    lookupGRE_RdrName :: RdrName -> GlobalRdrEnv -> [GlobalRdrElt]
    lookupGRE_RdrName rdr_name env
      = case lookupOccEnv env (rdrNameOcc rdr_name) of
        Nothing   -> []
        Just gres -> pickGREs rdr_name gres

    lookupGRE_Name :: GlobalRdrEnv -> Name -> [GlobalRdrElt]
    lookupGRE_Name env name
      = [ gre | gre <- lookupGlobalRdrEnv env (nameOccName name),
                gre_name gre == name ]

    lookupGRE_Field_Name :: GlobalRdrEnv -> Name -> FastString -> [GlobalRdrElt]
    -- Used when looking up record fields, where the selector name and
    -- field label are different: the GlobalRdrEnv is keyed on the label
    lookupGRE_Field_Name env sel_name lbl
      = [ gre | gre <- lookupGlobalRdrEnv env (mkVarOccFS lbl),
                gre_name gre == sel_name ]

    getGRE_NameQualifier_maybes :: GlobalRdrEnv -> Name -> [Maybe [ModuleName]]
    -- Returns all the qualifiers by which 'x' is in scope
    -- Nothing means "the unqualified version is in scope"
    -- [] means the thing is not in scope at all
    getGRE_NameQualifier_maybes env
      = map (qualifier_maybe) . lookupGRE_Name env
      where
        qualifier_maybe (GRE { gre_lcl = lcl, gre_imp = iss })
          | lcl       = Nothing
          | otherwise = Just $ map (is_as . is_decl) iss

    isLocalGRE :: GlobalRdrElt -> Bool
    isLocalGRE (GRE {gre_lcl = lcl }) = lcl

    isRecFldGRE :: GlobalRdrElt -> Bool
    isRecFldGRE (GRE {gre_par = FldParent{}}) = True
    isRecFldGRE _                             = False

    -- Returns the field label of this GRE, if it has one
    greLabel :: GlobalRdrElt -> Maybe FieldLabelString
    greLabel (GRE{gre_par = FldParent{par_lbl = Just lbl}}) = Just lbl
    greLabel (GRE{gre_name = n, gre_par = FldParent{}})     = Just (occNameFS (nameOccName n))
    greLabel _                                              = Nothing

    unQualOK :: GlobalRdrElt -> Bool
    -- ^ Test if an unqualifed version of this thing would be in scope
    unQualOK (GRE {gre_lcl = lcl, gre_imp = iss })
      | lcl = True
      | otherwise = any unQualSpecOK iss

    {- Note [GRE filtering]
    ~~~~~~~~~~~~~~~~~~~~~~~
    (pickGREs rdr gres) takes a list of GREs which have the same OccName
    as 'rdr', say "x".  It does two things:

    (a) filters the GREs to a subset that are in scope
        * Qualified,   as 'M.x'  if want_qual    is Qual M _
        * Unqualified, as 'x'    if want_unqual  is Unqual _

    (b) for that subset, filter the provenance field (gre_lcl and gre_imp)
        to ones that brought it into scope qualifed or unqualified resp.

    Example:
          module A ( f ) where
          import qualified Foo( f )
          import Baz( f )
          f = undefined

    Let's suppose that Foo.f and Baz.f are the same entity really, but the local
    'f' is different, so there will be two GREs matching "f":
       gre1:  gre_lcl = True,  gre_imp = []
       gre2:  gre_lcl = False, gre_imp = [ imported from Foo, imported from Bar ]

    The use of "f" in the export list is ambiguous because it's in scope
    from the local def and the import Baz(f); but *not* the import qualified Foo.
    pickGREs returns two GRE
       gre1:   gre_lcl = True,  gre_imp = []
       gre2:   gre_lcl = False, gre_imp = [ imported from Bar ]

    Now the the "ambiguous occurrence" message can correctly report how the
    ambiguity arises.
    -}

    pickGREs :: RdrName -> [GlobalRdrElt] -> [GlobalRdrElt]
    -- ^ Takes a list of GREs which have the right OccName 'x'
    -- Pick those GREs that are are in scope
    --    * Qualified,   as 'M.x'  if want_qual    is Qual M _
    --    * Unqualified, as 'x'    if want_unqual  is Unqual _
    --
    -- Return each such GRE, with its ImportSpecs filtered, to reflect
    -- how it is in scope qualifed or unqualified respectively.
    -- See Note [GRE filtering]
    pickGREs (Unqual {})  gres = mapMaybe pickUnqualGRE     gres
    pickGREs (Qual mod _) gres = mapMaybe (pickQualGRE mod) gres
    pickGREs _            _    = []  -- I don't think this actually happens

    pickUnqualGRE :: GlobalRdrElt -> Maybe GlobalRdrElt
    pickUnqualGRE gre@(GRE { gre_lcl = lcl, gre_imp = iss })
      | not lcl, null iss' = Nothing
      | otherwise          = Just (gre { gre_imp = iss' })
      where
        iss' = filter unQualSpecOK iss

    pickQualGRE :: ModuleName -> GlobalRdrElt -> Maybe GlobalRdrElt
    pickQualGRE mod gre@(GRE { gre_name = n, gre_lcl = lcl, gre_imp = iss })
      | not lcl', null iss' = Nothing
      | otherwise           = Just (gre { gre_lcl = lcl', gre_imp = iss' })
      where
        iss' = filter (qualSpecOK mod) iss
        lcl' = lcl && name_is_from mod n

        name_is_from :: ModuleName -> Name -> Bool
        name_is_from mod name = case nameModule_maybe name of
                                  Just n_mod -> moduleName n_mod == mod
                                  Nothing    -> False

    pickGREsModExp :: ModuleName -> [GlobalRdrElt] -> [(GlobalRdrElt,GlobalRdrElt)]
    -- ^ Pick GREs that are in scope *both* qualified *and* unqualified
    -- Return each GRE that is, as a pair
    --    (qual_gre, unqual_gre)
    -- These two GREs are the original GRE with imports filtered to express how
    -- it is in scope qualified an unqualified respectively
    --
    -- Used only for the 'module M' item in export list;
    --   see RnNames.exports_from_avail
    pickGREsModExp mod gres = mapMaybe (pickBothGRE mod) gres

    pickBothGRE :: ModuleName -> GlobalRdrElt -> Maybe (GlobalRdrElt, GlobalRdrElt)
    pickBothGRE mod gre@(GRE { gre_name = n })
      | isBuiltInSyntax n                = Nothing
      | Just gre1 <- pickQualGRE mod gre
      , Just gre2 <- pickUnqualGRE   gre = Just (gre1, gre2)
      | otherwise                        = Nothing
      where
            -- isBuiltInSyntax filter out names for built-in syntax They
            -- just clutter up the environment (esp tuples), and the
            -- parser will generate Exact RdrNames for them, so the
            -- cluttered envt is no use.  Really, it's only useful for
            -- GHC.Base and GHC.Tuple.

    -- Building GlobalRdrEnvs

    plusGlobalRdrEnv :: GlobalRdrEnv -> GlobalRdrEnv -> GlobalRdrEnv
    plusGlobalRdrEnv env1 env2 = plusOccEnv_C (foldr insertGRE) env1 env2

    mkGlobalRdrEnv :: [GlobalRdrElt] -> GlobalRdrEnv
    mkGlobalRdrEnv gres
      = foldr add emptyGlobalRdrEnv gres
      where
        add gre env = extendOccEnv_Acc insertGRE singleton env
                                       (greOccName gre)
                                       gre

    insertGRE :: GlobalRdrElt -> [GlobalRdrElt] -> [GlobalRdrElt]
    insertGRE new_g [] = [new_g]
    insertGRE new_g (old_g : old_gs)
            | gre_name new_g == gre_name old_g
            = new_g `plusGRE` old_g : old_gs
            | otherwise
            = old_g : insertGRE new_g old_gs

    plusGRE :: GlobalRdrElt -> GlobalRdrElt -> GlobalRdrElt
    -- Used when the gre_name fields match
    plusGRE g1 g2
      = GRE { gre_name = gre_name g1
            , gre_lcl  = gre_lcl g1 || gre_lcl g2
            , gre_imp  = gre_imp g1 ++ gre_imp g2
            , gre_par  = gre_par  g1 `plusParent` gre_par  g2 }

    transformGREs :: (GlobalRdrElt -> GlobalRdrElt)
                  -> [OccName]
                  -> GlobalRdrEnv -> GlobalRdrEnv
    -- ^ Apply a transformation function to the GREs for these OccNames
    transformGREs trans_gre occs rdr_env
      = foldr trans rdr_env occs
      where
        trans occ env
          = case lookupOccEnv env occ of
               Just gres -> extendOccEnv env occ (map trans_gre gres)
               Nothing   -> env

    extendGlobalRdrEnv :: GlobalRdrEnv -> GlobalRdrElt -> GlobalRdrEnv
    extendGlobalRdrEnv env gre
      = extendOccEnv_Acc insertGRE singleton env
                         (greOccName gre) gre

    shadowNames :: GlobalRdrEnv -> [Name] -> GlobalRdrEnv
    shadowNames = foldl shadowName

    {- Note [GlobalRdrEnv shadowing]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Before adding new names to the GlobalRdrEnv we nuke some existing entries;
    this is "shadowing".  The actual work is done by RdrEnv.shadowNames.
    There are two reasons for shadowing:

    * The GHCi REPL

      - Ids bought into scope on the command line (eg let x = True) have
        External Names, like Ghci4.x.  We want a new binding for 'x' (say)
        to override the existing binding for 'x'.
        See Note [Interactively-bound Ids in GHCi] in HscTypes

      - Data types also have Extenal Names, like Ghci4.T; but we still want
        'T' to mean the newly-declared 'T', not an old one.

    * Nested Template Haskell declaration brackets
      See Note [Top-level Names in Template Haskell decl quotes] in RnNames

      Consider a TH decl quote:
          module M where
            f x = h [d| f = 3 |]
      We must shadow the outer declaration of 'f', else we'll get a
      complaint when extending the GlobalRdrEnv, saying that there are two
      bindings for 'f'.  There are several tricky points:

        - This shadowing applies even if the binding for 'f' is in a
          where-clause, and hence is in the *local* RdrEnv not the *global*
          RdrEnv.  This is done in lcl_env_TH in extendGlobalRdrEnvRn.

        - The External Name M.f from the enclosing module must certainly
          still be available.  So we don't nuke it entirely; we just make
          it seem like qualified import.

        - We only shadow *External* names (which come from the main module),
          or from earlier GHCi commands. Do not shadow *Internal* names
          because in the bracket
              [d| class C a where f :: a
                  f = 4 |]
          rnSrcDecls will first call extendGlobalRdrEnvRn with C[f] from the
          class decl, and *separately* extend the envt with the value binding.
          At that stage, the class op 'f' will have an Internal name.
    -}

    shadowName :: GlobalRdrEnv -> Name -> GlobalRdrEnv
    -- Remove certain old GREs that share the same OccName as this new Name.
    -- See Note [GlobalRdrEnv shadowing] for details
    shadowName env name
      = alterOccEnv (fmap alter_fn) env (nameOccName name)
      where
        alter_fn :: [GlobalRdrElt] -> [GlobalRdrElt]
        alter_fn gres = mapMaybe (shadow_with name) gres

        shadow_with :: Name -> GlobalRdrElt -> Maybe GlobalRdrElt
        shadow_with new_name
           old_gre@(GRE { gre_name = old_name, gre_lcl = lcl, gre_imp = iss })
           = case nameModule_maybe old_name of
               Nothing -> Just old_gre   -- Old name is Internal; do not shadow
               Just old_mod
                  | Just new_mod <- nameModule_maybe new_name
                  , new_mod == old_mod   -- Old name same as new name; shadow completely
                  -> Nothing

                  | null iss'            -- Nothing remains
                  -> Nothing

                  | otherwise
                  -> Just (old_gre { gre_lcl = False, gre_imp = iss' })

                  where
                    iss' = lcl_imp ++ mapMaybe (shadow_is new_name) iss
                    lcl_imp | lcl       = [mk_fake_imp_spec old_name old_mod]
                            | otherwise = []

        mk_fake_imp_spec old_name old_mod    -- Urgh!
          = ImpSpec id_spec ImpAll
          where
            old_mod_name = moduleName old_mod
            id_spec      = ImpDeclSpec { is_mod = old_mod_name
                                       , is_as = old_mod_name
                                       , is_qual = True
                                       , is_dloc = nameSrcSpan old_name }

        shadow_is :: Name -> ImportSpec -> Maybe ImportSpec
        shadow_is new_name is@(ImpSpec { is_decl = id_spec })
           | Just new_mod <- nameModule_maybe new_name
           , is_as id_spec == moduleName new_mod
           = Nothing   -- Shadow both qualified and unqualified
           | otherwise -- Shadow unqualified only
           = Just (is { is_decl = id_spec { is_qual = True } })

    {-
    ************************************************************************
    *                                                                      *
                            ImportSpec
    *                                                                      *
    ************************************************************************
    -}

    -- | The 'ImportSpec' of something says how it came to be imported
    -- It's quite elaborate so that we can give accurate unused-name warnings.
    data ImportSpec = ImpSpec { is_decl :: ImpDeclSpec,
                                is_item :: ImpItemSpec }
                    deriving( Eq, Ord, Data, Typeable )

    -- | Describes a particular import declaration and is
    -- shared among all the 'Provenance's for that decl
    data ImpDeclSpec
      = ImpDeclSpec {
            is_mod      :: ModuleName, -- ^ Module imported, e.g. @import Muggle@
                                       -- Note the @Muggle@ may well not be
                                       -- the defining module for this thing!

                                       -- TODO: either should be Module, or there
                                       -- should be a Maybe UnitId here too.
            is_as       :: ModuleName, -- ^ Import alias, e.g. from @as M@ (or @Muggle@ if there is no @as@ clause)
            is_qual     :: Bool,       -- ^ Was this import qualified?
            is_dloc     :: SrcSpan     -- ^ The location of the entire import declaration
        } deriving (Data, Typeable)

    -- | Describes import info a particular Name
    data ImpItemSpec
      = ImpAll              -- ^ The import had no import list,
                            -- or had a hiding list

      | ImpSome {
            is_explicit :: Bool,
            is_iloc     :: SrcSpan  -- Location of the import item
        }   -- ^ The import had an import list.
            -- The 'is_explicit' field is @True@ iff the thing was named
            -- /explicitly/ in the import specs rather
            -- than being imported as part of a "..." group. Consider:
            --
            -- > import C( T(..) )
            --
            -- Here the constructors of @T@ are not named explicitly;
            -- only @T@ is named explicitly.
      deriving (Data, Typeable)

    instance Eq ImpDeclSpec where
      p1 == p2 = case p1 `compare` p2 of EQ -> True; _ -> False

    instance Ord ImpDeclSpec where
       compare is1 is2 = (is_mod is1 `compare` is_mod is2) `thenCmp`
                         (is_dloc is1 `compare` is_dloc is2)

    instance Eq ImpItemSpec where
      p1 == p2 = case p1 `compare` p2 of EQ -> True; _ -> False

    instance Ord ImpItemSpec where
       compare is1 is2 = is_iloc is1 `compare` is_iloc is2

    bestImport :: [ImportSpec] -> ImportSpec
    -- Given a non-empty bunch of ImportSpecs, return the one that
    -- imported the item most specficially (e.g. by name), using
    -- textually-first as a tie breaker. This is used when reporting
    -- redundant imports
    bestImport iss
      = case sortBy best iss of
          (is:_) -> is
          []     -> pprPanic "bestImport" (ppr iss)
      where
        best :: ImportSpec -> ImportSpec -> Ordering
        -- Less means better
        best (ImpSpec { is_item = item1, is_decl = d1 })
             (ImpSpec { is_item = item2, is_decl = d2 })
          = best_item item1 item2 `thenCmp` (is_dloc d1 `compare` is_dloc d2)

        best_item :: ImpItemSpec -> ImpItemSpec -> Ordering
        best_item ImpAll ImpAll = EQ
        best_item ImpAll (ImpSome {}) = GT
        best_item (ImpSome {}) ImpAll = LT
        best_item (ImpSome { is_explicit = e1 })
                  (ImpSome { is_explicit = e2 }) = e2 `compare` e1
         -- False < True, so if e1 is explicit and e2 is not, we get LT

    unQualSpecOK :: ImportSpec -> Bool
    -- ^ Is in scope unqualified?
    unQualSpecOK is = not (is_qual (is_decl is))

    qualSpecOK :: ModuleName -> ImportSpec -> Bool
    -- ^ Is in scope qualified with the given module?
    qualSpecOK mod is = mod == is_as (is_decl is)

    importSpecLoc :: ImportSpec -> SrcSpan
    importSpecLoc (ImpSpec decl ImpAll) = is_dloc decl
    importSpecLoc (ImpSpec _    item)   = is_iloc item

    importSpecModule :: ImportSpec -> ModuleName
    importSpecModule is = is_mod (is_decl is)

    isExplicitItem :: ImpItemSpec -> Bool
    isExplicitItem ImpAll                        = False
    isExplicitItem (ImpSome {is_explicit = exp}) = exp

    pprNameProvenance :: GlobalRdrElt -> SDoc
    -- ^ Print out one place where the name was define/imported
    -- (With -dppr-debug, print them all)
    pprNameProvenance (GRE { gre_name = name, gre_lcl = lcl, gre_imp = iss })
      | opt_PprStyle_Debug = vcat pp_provs
      | otherwise          = head pp_provs
      where
        pp_provs = pp_lcl ++ map pp_is iss
        pp_lcl = if lcl then [text "defined at" <+> ppr (nameSrcLoc name)]
                        else []
        pp_is is = sep [ppr is, ppr_defn_site is name]

    -- If we know the exact definition point (which we may do with GHCi)
    -- then show that too.  But not if it's just "imported from X".
    ppr_defn_site :: ImportSpec -> Name -> SDoc
    ppr_defn_site imp_spec name
      | same_module && not (isGoodSrcSpan loc)
      = empty              -- Nothing interesting to say
      | otherwise
      = parens $ hang (text "and originally defined" <+> pp_mod)
                    2 (pprLoc loc)
      where
        loc = nameSrcSpan name
        defining_mod = nameModule name
        same_module = importSpecModule imp_spec == moduleName defining_mod
        pp_mod | same_module = empty
               | otherwise   = text "in" <+> quotes (ppr defining_mod)

    instance Outputable ImportSpec where
       ppr imp_spec
         = text "imported" <+> qual
            <+> text "from" <+> quotes (ppr (importSpecModule imp_spec))
            <+> pprLoc (importSpecLoc imp_spec)
         where
           qual | is_qual (is_decl imp_spec) = text "qualified"
                | otherwise                  = empty

    pprLoc :: SrcSpan -> SDoc
    pprLoc (RealSrcSpan s)    = text "at" <+> ppr s
    pprLoc (UnhelpfulSpan {}) = empty