--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+ <title>The GHC Commentary - The truth about names: OccNames, and Names</title>
+ </head>
+
+ <body BGCOLOR="FFFFFF">
+ <h1>The GHC Commentary - The truth about names: OccNames, and Names</h1>
+ <p>
+
+
+Every entity (type constructor, class, identifier, type variable) has
+a <code>Name</code>. The <code>Name</code> type is pervasive in GHC,
+and is defined in <code>basicTypes/Name.lhs</code>. Here is what a Name looks like,
+though it is private to the Name module.
+<pre>
+ data Name = Name {
+ n_sort :: NameSort, -- What sort of name it is
+ n_occ :: !OccName, -- Its occurrence name
+ n_uniq :: Unique, -- Its identity
+ n_loc :: !SrcLoc -- Definition site
+ }
+</pre>
+
+<ul>
+<li> The <code>n_sort</code> field says what sort of name this is: see
+<a href="#sort">NameSort below</a>.
+<li> The <code>n_occ</code> field gives the "occurrence name" of the Name; see
+<a href="#occname">OccName below</a>.
+<li> The <code>n_uniq</code> field allows fast tests for equality of Names.
+<li> The <code>n_loc</code> field gives some indication of where the name was bound.
+</ul>
+
+<h2><a name="sort">The <code>NameSort</code> of a <code>Name</code></a></h2>
+
+There are three flavours of <code>Name</code>:
+<pre>
+ data NameSort
+ = External Module
+ | Internal
+ | System
+</pre>
+
+<ul>
+<li> Here are the sorts of Name an entity can have:
+<ul>
+<li> Class, TyCon: External.
+<li> Id: External, Internal, or System.
+<li> TyVar: Internal, or System.
+</ul>
+
+<p><li> An <code>ExternalName</code> has a globally-unique
+(module name,occurrence name) pair, namely the
+<em>original name</em> of the entity,
+describing where the thing was originally defined. So for example,
+if we have
+<pre>
+ module M where
+ f = e1
+ g = e2
+
+ module A where
+ import qualified M as Q
+ import M
+ a = Q.f + g
+</pre>
+then the RdrNames for "a", "Q.f" and "g" get replaced (by the Renamer)
+by the Names "A.a", "M.f", and "M.g" respectively.
+
+<p><li> An <code>InternalName</code>
+has only an occurrence name. Distinct InternalNames may have the same occurrence
+name; use the Unique to distinguish them.
+
+<p> <li> An <code>ExternalName</code> has a unique that never changes. It is never
+cloned. This is important, because the simplifier invents new names pretty freely,
+but we don't want to lose the connnection with the type environment (constructed earlier).
+An <code>InternalName</code> name can be cloned freely.
+
+<p><li> <strong>Before CoreTidy</strong>: the Ids that were defined at top level
+in the original source program get <code>ExternalNames</code>, whereas extra
+top-level bindings generated (say) by the type checker get <code>InternalNames</code>.
+This distinction is occasionally useful for filtering diagnostic output; e.g.
+for -ddump-types.
+
+<p><li> <strong>After CoreTidy</strong>: An Id with an <code>ExternalName</code> will generate symbols that
+appear as external symbols in the object file. An Id with an <code>InternalName</code>
+cannot be referenced from outside the module, and so generates a local symbol in
+the object file. The CoreTidy pass makes the decision about which names should
+be External and which Internal.
+
+<p><li> A <code>System</code> name is for the most part the same as an
+<code>Internal</code>. Indeed, the differences are purely cosmetic:
+<ul>
+<li>Internal names usually come from some name the
+user wrote, whereas a System name has an OccName like "a", or "t". Usually
+there are masses of System names with the same OccName but different uniques,
+whereas typically there are only a handful of distince Internal names with the same
+OccName.
+<li>
+Another difference is that when unifying the type checker tries to
+unify away type variables with System names, leaving ones with Internal names
+(to improve error messages).
+</ul>
+</ul>
+
+
+<h2> <a name="occname">Occurrence names: <code>OccName</code></a> </h2>
+
+An <code>OccName</code> is more-or-less just a string, like "foo" or "Tree",
+giving the (unqualified) name of an entity.
+
+Well, not quite just a string, because in Haskell a name like "C" could mean a type
+constructor or data constructor, depending on context. So GHC defines a type
+<tt>OccName</tt> (defined in <tt>basicTypes/OccName.lhs</tt>) that is a pair of
+a <tt>FastString</tt> and a <tt>NameSpace</tt> indicating which name space the
+name is drawn from:
+<pre>
+ data OccName = OccName NameSpace EncodedFS
+</pre>
+The <tt>EncodedFS</tt> is a synonym for <tt>FastString</tt> indicating that the
+string is Z-encoded. (Details in <tt>OccName.lhs</tt>.) Z-encoding encodes
+funny characters like '%' and '$' into alphabetic characters, like "zp" and "zd",
+so that they can be used in object-file symbol tables without confusing linkers
+and suchlike.
+
+<p>
+The name spaces are:
+<ul>
+<li> <tt>VarName</tt>: ordinary variables
+<li> <tt>TvName</tt>: type variables
+<li> <tt>DataName</tt>: data constructors
+<li> <tt>TcClsName</tt>: type constructors and classes (in Haskell they share a name space)
+</ul>
+
+<!-- hhmts start -->
+Last modified: Tue Nov 13 14:11:35 EST 2001
+<!-- hhmts end -->
+ </small>
+ </body>
+</html>
+
projects / ghc-hetmet.git / blobdiff