[GHC] #15896: GHC API: add function to allow looking up Name for Located RdrName

[GHC]

#15896: GHC API: add function to allow looking up Name for Located RdrName
-------------------------------------+-------------------------------------
           Reporter:  alanz          |             Owner:  (none)
               Type:  task           |            Status:  new
           Priority:  normal         |         Milestone:  8.6.3
          Component:  GHC API        |           Version:  8.6.2
           Keywords:                 |  Operating System:  Unknown/Multiple
       Architecture:                 |   Type of failure:  None/Unknown
  Unknown/Multiple                   |
          Test Case:                 |        Blocked By:
           Blocking:                 |   Related Tickets:
Differential Rev(s):  Phab:D5330     |         Wiki Page:
-------------------------------------+-------------------------------------
 A tool writer using the GHC API to do a source level change must use the
 `ParsedSource` as it most closely represents the original source code, and
 has API Annotations.

 But the `ParsedSource` only has `RdrName`s in it, and many useful
 transformations need information from the renamer, the simplest example
 being renaming a variable in the presence of name shadowing.

 So we need a way to look up the `Name` corresponding to each `RdrName` in
 the `ParsedSource`.

 GHC does have a `GlobalRdrEnv` which is a mapping from `OccName` to a list
 of elements, each of which has the `Name`. But the `OccName` is only
 unique wrt its spelling, and so cannot distinguish the name shadowing
 case.

 Fortuitously (!), every `RdrName` in the `ParsedSource` is `Located`, and
 hence has a unique `SrcSpan` associated with it.

 So, given a `TypecheckedModule`, it is possible to construct a map from
 the `SrcSpan` of each `Located RdrName` to the corresponding `Name` from
 the `RenamedSource` (or `TypecheckedSource` for ambiguous record
 selectors).

 Introduce this as part of the GHC API.

 Note: this function has existed in `HaRe` for some time, and is the reason
 each `RdrName` in the `ParsedSource` is `Located`.

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/15896>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler