docs/comm/the-beast/names.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
   5     <title>The GHC Commentary - The truth about names: OccNames, and Names</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>The GHC Commentary - The truth about names: OccNames, and Names</h1>
  10     <p>
  11       Every entity (type constructor, class, identifier, type variable) has a
  12       <code>Name</code>.  The <code>Name</code> type is pervasive in GHC, and
  13       is defined in <code>basicTypes/Name.lhs</code>.  Here is what a Name
  14       looks like, though it is private to the Name module.
  15     </p>
  16     <blockquote>
  17       <pre>
  18 data Name = Name {
  19               n_sort :: NameSort,       -- What sort of name it is
  20               n_occ  :: !OccName,       -- Its occurrence name
  21               n_uniq :: Unique,         -- Its identity
  22               n_loc  :: !SrcLoc         -- Definition site
  23           }</pre>
  24     </blockquote>
  25     <ul>
  26       <li> The <code>n_sort</code> field says what sort of name this is: see
  27         <a href="#sort">NameSort below</a>.
  28       <li> The <code>n_occ</code> field gives the "occurrence name" of the
  29         Name; see
  30         <a href="#occname">OccName below</a>.
  31       <li> The <code>n_uniq</code> field allows fast tests for equality of
  32         Names.
  33       <li> The <code>n_loc</code> field gives some indication of where the
  34         name was bound.
  35     </ul>
  36
  37     <h2><a name="sort">The <code>NameSort</code> of a <code>Name</code></a></h2>
  38     <p>
  39       There are four flavours of <code>Name</code>:
  40     </p>
  41     <blockquote>
  42       <pre>
  43 data NameSort
  44   = External Module (Maybe Name)
  45         -- (Just parent) => this Name is a subordinate name of 'parent'
  46         -- e.g. data constructor of a data type, method of a class
  47         -- Nothing => not a subordinate
  48
  49   | WiredIn Module (Maybe Name) TyThing BuiltInSyntax
  50         -- A variant of External, for wired-in things
  51
  52   | Internal            -- A user-defined Id or TyVar
  53                         -- defined in the module being compiled
  54
  55   | System              -- A system-defined Id or TyVar.  Typically the
  56                         -- OccName is very uninformative (like 's')</pre>
  57     </blockquote>
  58     <ul>
  59       <li>Here are the sorts of Name an entity can have:
  60         <ul>
  61           <li> Class, TyCon: External.
  62           <li> Id: External, Internal, or System.
  63           <li> TyVar: Internal, or System.
  64         </ul>
  65       </li>
  66       <li>An <code>External</code> name has a globally-unique
  67         (module name, occurrence name) pair, namely the
  68         <em>original name</em> of the entity,
  69         describing where the thing was originally defined.  So for example,
  70         if we have
  71         <blockquote>
  72           <pre>
  73 module M where
  74   f = e1
  75   g = e2
  76
  77 module A where
  78   import qualified M as Q
  79   import M
  80   a = Q.f + g</pre>
  81         </blockquote>
  82         <p>
  83           then the RdrNames for "a", "Q.f" and "g" get replaced (by the
  84           Renamer)  by the Names "A.a", "M.f", and "M.g" respectively.
  85         </p>
  86       </li>
  87       <li>An <code>InternalName</code>
  88         has only an occurrence name.  Distinct InternalNames may have the same
  89         occurrence name; use the Unique to distinguish them.
  90       </li>
  91       <li>An <code>ExternalName</code> has a unique that never changes.  It
  92         is never cloned.  This is important, because the simplifier invents
  93         new names pretty freely, but we don't want to lose the connnection
  94         with the type environment (constructed earlier).  An
  95         <code>InternalName</code> name can be cloned freely.
  96       </li>
  97       <li><strong>Before CoreTidy</strong>: the Ids that were defined at top
  98         level in the original source program get <code>ExternalNames</code>,
  99         whereas extra top-level bindings generated (say) by the type checker
 100         get <code>InternalNames</code>. q This distinction is occasionally
 101         useful for filtering diagnostic output; e.g.  for -ddump-types.
 102       </li>
 103       <li><strong>After CoreTidy</strong>: An Id with an
 104         <code>ExternalName</code> will generate symbols that
 105         appear as external symbols in the object file.  An Id with an
 106         <code>InternalName</code> cannot be referenced from outside the
 107         module, and so generates a local symbol in the object file.  The
 108         CoreTidy pass makes the decision about which names should be External
 109         and which Internal.
 110       </li>
 111       <li>A <code>System</code> name is for the most part the same as an
 112         <code>Internal</code>.  Indeed, the differences are purely cosmetic:
 113         <ul>
 114           <li>Internal names usually come from some name the
 115             user wrote, whereas a System name has an OccName like "a", or "t".
 116             Usually there are masses of System names with the same OccName but
 117             different uniques, whereas typically there are only a handful of
 118             distince Internal names with the same OccName.
 119           </li>
 120           <li>Another difference is that when unifying the type checker tries
 121             to  unify away type variables with System names, leaving ones with
 122             Internal names (to improve error messages).
 123           </li>
 124         </ul>
 125       </li>
 126     </ul>
 127
 128     <h2><a name="occname">Occurrence names: <code>OccName</code></a></h2>
 129     <p>
 130       An <code>OccName</code> is more-or-less just a string, like "foo" or
 131       "Tree", giving the (unqualified) name of an entity.
 132     </p>
 133     <p>
 134       Well, not quite just a string, because in Haskell a name like "C" could
 135       mean a type constructor or data constructor, depending on context.  So
 136       GHC defines a type <tt>OccName</tt> (defined in
 137       <tt>basicTypes/OccName.lhs</tt>) that is a pair of a <tt>FastString</tt>
 138       and a <tt>NameSpace</tt> indicating which name space the name is drawn
 139       from:
 140       <blockquote>
 141       <pre>
 142 data OccName = OccName NameSpace EncodedFS</pre>
 143     </blockquote>
 144     <p>
 145       The <tt>EncodedFS</tt> is a synonym for <tt>FastString</tt> indicating
 146       that the string is Z-encoded.  (Details in <tt>OccName.lhs</tt>.)
 147       Z-encoding encodes funny characters like '%' and '$' into alphabetic
 148       characters, like "zp" and "zd", so that they can be used in object-file
 149       symbol tables without confusing linkers and suchlike.
 150     </p>
 151     <p>
 152       The name spaces are:
 153     </p>
 154     <ul>
 155       <li> <tt>VarName</tt>: ordinary variables</li>
 156       <li> <tt>TvName</tt>: type variables</li>
 157       <li> <tt>DataName</tt>: data constructors</li>
 158       <li> <tt>TcClsName</tt>: type constructors and classes (in Haskell they
 159         share a name space) </li>
 160     </ul>
 161
 162     <small>
 163 <!-- hhmts start -->
 164 Last modified: Wed May  4 14:57:55 EST 2005
 165 <!-- hhmts end -->
 166     </small>
 167   </body>
 168 </html>
 169