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