Test Trac #9036
[ghc.git] / 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