From 3aafdc1609ee60c4d5629b279c45ccbb943fa4a7 Mon Sep 17 00:00:00 2001 From: Max Bolingbroke Date: Thu, 31 Jul 2008 05:22:38 +0000 Subject: [PATCH] Document OccName and expand it's API --- compiler/basicTypes/OccName.lhs | 200 ++++++++++++++++++++++++++------------- 1 file changed, 134 insertions(+), 66 deletions(-) diff --git a/compiler/basicTypes/OccName.lhs b/compiler/basicTypes/OccName.lhs index debaa28..1868c3f 100644 --- a/compiler/basicTypes/OccName.lhs +++ b/compiler/basicTypes/OccName.lhs @@ -4,28 +4,49 @@ % \begin{code} +-- | +-- #name_types# +-- GHC uses several kinds of name internally: +-- +-- * 'OccName.OccName' represents names as strings with just a little more information: +-- the "namespace" that the name came from, e.g. the namespace of value, type constructors or +-- data constructors +-- +-- * 'RdrName.RdrName': see "RdrName#name_types" +-- +-- * 'Name.Name': see "Name#name_types" +-- +-- * 'Id.Id': see "Id#name_types" +-- +-- * 'Var.Var': see "Var#name_types" module OccName ( - mk_deriv, - -- * The NameSpace type; abstact - NameSpace, tcName, clsName, tcClsName, dataName, varName, + -- * The 'NameSpace' type + NameSpace, -- Abstract + + -- ** Construction + -- $real_vs_source_data_constructors + tcName, clsName, tcClsName, dataName, varName, tvName, srcDataName, - -- ** Printing + -- ** Pretty Printing pprNameSpace, pprNonVarNameSpace, pprNameSpaceBrief, - -- * The OccName type + -- * The 'OccName' type OccName, -- Abstract, instance of Outputable pprOccName, -- ** Construction mkOccName, mkOccNameFS, mkVarOcc, mkVarOccFS, - mkTyVarOcc, + mkDataOcc, mkDataOccFS, + mkTyVarOcc, mkTyVarOccFS, + mkTcOcc, mkTcOccFS, + mkClsOcc, mkClsOccFS, mkDFunOcc, mkTupleOcc, setOccNameSpace, - -- ** Derived OccNames + -- ** Derived 'OccName's isDerivedOccName, mkDataConWrapperOcc, mkWorkerOcc, mkDefaultMethodOcc, mkDerivedTyConOcc, mkNewTyCoOcc, @@ -44,26 +65,28 @@ module OccName ( occNameFS, occNameString, occNameSpace, isVarOcc, isTvOcc, isTcOcc, isDataOcc, isDataSymOcc, isSymOcc, isValOcc, - parenSymOcc, reportIfUnused, isTcClsName, isVarName, + parenSymOcc, reportIfUnused, + + isTcClsNameSpace, isTvNameSpace, isDataConNameSpace, isVarNameSpace, isValNameSpace, isTupleOcc_maybe, - -- The OccEnv type + -- * The 'OccEnv' type OccEnv, emptyOccEnv, unitOccEnv, extendOccEnv, mapOccEnv, lookupOccEnv, mkOccEnv, mkOccEnv_C, extendOccEnvList, elemOccEnv, occEnvElts, foldOccEnv, plusOccEnv, plusOccEnv_C, extendOccEnv_C, filterOccEnv, delListFromOccEnv, delFromOccEnv, - -- The OccSet type + -- * The 'OccSet' type OccSet, emptyOccSet, unitOccSet, mkOccSet, extendOccSet, extendOccSetList, unionOccSets, unionManyOccSets, minusOccSet, elemOccSet, occSetElts, foldOccSet, isEmptyOccSet, intersectOccSet, intersectsOccSet, - -- Tidying up + -- * Tidying up TidyOccEnv, emptyTidyOccEnv, tidyOccName, initTidyOccEnv, - -- The basic form of names + -- * Lexical characteristics of Haskell names isLexCon, isLexVar, isLexId, isLexSym, isLexConId, isLexConSym, isLexVarId, isLexVarSym, startsVarSym, startsVarId, startsConSym, startsConId @@ -82,7 +105,9 @@ import Binary import GHC.Exts import Data.Char +\end{code} +\begin{code} -- Unicode TODO: put isSymbol in libcompat #if !defined(__GLASGOW_HASKELL__) || __GLASGOW_HASKELL__ > 604 #else @@ -109,19 +134,21 @@ data NameSpace = VarName -- Variables, including "real" data constructors -- Note [Data Constructors] -- see also: Note [Data Constructor Naming] in DataCon.lhs --- --- "Source" data constructors are the data constructors mentioned --- in Haskell source code -- --- "Real" data constructors are the data constructors of the --- representation type, which may not be the same as the source --- type - --- Example: --- data T = T !(Int,Int) +-- $real_vs_source_data_constructors +-- There are two forms of data constructor: +-- +-- [Source data constructors] The data constructors mentioned in Haskell source code +-- +-- [Real data constructors] The data constructors of the representation type, which may not be the same as the source type +-- +-- For example: +-- +-- > data T = T !(Int, Int) +-- +-- The source datacon has type @(Int, Int) -> T@ +-- The real datacon has type @Int -> Int -> T@ -- --- The source datacon has type (Int,Int) -> T --- The real datacon has type Int -> Int -> T -- GHC chooses a representation based on the strictness etc. tcName, clsName, tcClsName :: NameSpace @@ -141,14 +168,27 @@ srcDataName = DataName -- Haskell-source data constructors should be tvName = TvName varName = VarName -isTcClsName :: NameSpace -> Bool -isTcClsName TcClsName = True -isTcClsName _ = False +isDataConNameSpace :: NameSpace -> Bool +isDataConNameSpace DataName = True +isDataConNameSpace _ = False + +isTcClsNameSpace :: NameSpace -> Bool +isTcClsNameSpace TcClsName = True +isTcClsNameSpace _ = False + +isTvNameSpace :: NameSpace -> Bool +isTvNameSpace TvName = True +isTvNameSpace _ = False -isVarName :: NameSpace -> Bool -- Variables or type variables, but not constructors -isVarName TvName = True -isVarName VarName = True -isVarName _ = False +isVarNameSpace :: NameSpace -> Bool -- Variables or type variables, but not constructors +isVarNameSpace TvName = True +isVarNameSpace VarName = True +isVarNameSpace _ = False + +isValNameSpace :: NameSpace -> Bool +isValNameSpace DataName = True +isValNameSpace VarName = True +isValNameSpace _ = False pprNameSpace :: NameSpace -> SDoc pprNameSpace DataName = ptext (sLit "data constructor") @@ -233,8 +273,29 @@ mkVarOcc s = mkOccName varName s mkVarOccFS :: FastString -> OccName mkVarOccFS fs = mkOccNameFS varName fs -mkTyVarOcc :: FastString -> OccName -mkTyVarOcc fs = mkOccNameFS tvName fs +mkDataOcc :: String -> OccName +mkDataOcc = mkOccName dataName + +mkDataOccFS :: FastString -> OccName +mkDataOccFS = mkOccNameFS dataName + +mkTyVarOcc :: String -> OccName +mkTyVarOcc = mkOccName tvName + +mkTyVarOccFS :: FastString -> OccName +mkTyVarOccFS fs = mkOccNameFS tvName fs + +mkTcOcc :: String -> OccName +mkTcOcc = mkOccName tcName + +mkTcOccFS :: FastString -> OccName +mkTcOccFS = mkOccNameFS tcName + +mkClsOcc :: String -> OccName +mkClsOcc = mkOccName clsName + +mkClsOccFS :: FastString -> OccName +mkClsOccFS = mkOccNameFS clsName \end{code} @@ -351,7 +412,7 @@ occNameString (OccName _ s) = unpackFS s setOccNameSpace :: NameSpace -> OccName -> OccName setOccNameSpace sp (OccName _ occ) = OccName sp occ -isVarOcc, isTvOcc, isDataSymOcc, isSymOcc, isTcOcc, isValOcc, isDataOcc :: OccName -> Bool +isVarOcc, isTvOcc, isTcOcc, isDataOcc :: OccName -> Bool isVarOcc (OccName VarName _) = True isVarOcc _ = False @@ -362,33 +423,40 @@ isTvOcc _ = False isTcOcc (OccName TcClsName _) = True isTcOcc _ = False +-- | /Value/ 'OccNames's are those that are either in +-- the variable or data constructor namespaces +isValOcc :: OccName -> Bool isValOcc (OccName VarName _) = True isValOcc (OccName DataName _) = True isValOcc _ = False --- Data constructor operator (starts with ':', or '[]') --- Pretty inefficient! -isDataSymOcc (OccName DataName s) = isLexConSym s -isDataSymOcc (OccName VarName s) - | isLexConSym s = pprPanic "isDataSymOcc: check me" (ppr s) - -- Jan06: I don't think this should happen -isDataSymOcc _ = False - isDataOcc (OccName DataName _) = True isDataOcc (OccName VarName s) | isLexCon s = pprPanic "isDataOcc: check me" (ppr s) -- Jan06: I don't think this should happen isDataOcc _ = False --- Any operator (data constructor or variable) +-- | Test if the 'OccName' is a data constructor that starts with +-- a symbol (e.g. @:@, or @[]@) +isDataSymOcc :: OccName -> Bool +isDataSymOcc (OccName DataName s) = isLexConSym s +isDataSymOcc (OccName VarName s) + | isLexConSym s = pprPanic "isDataSymOcc: check me" (ppr s) + -- Jan06: I don't think this should happen +isDataSymOcc _ = False -- Pretty inefficient! + +-- | Test if the 'OccName' is that for any operator (whether +-- it is a data constructor or variable or whatever) +isSymOcc :: OccName -> Bool isSymOcc (OccName DataName s) = isLexConSym s isSymOcc (OccName TcClsName s) = isLexConSym s isSymOcc (OccName VarName s) = isLexSym s isSymOcc (OccName TvName s) = isLexSym s +-- Pretty inefficient! parenSymOcc :: OccName -> SDoc -> SDoc --- Wrap parens around an operator +-- ^ Wrap parens around an operator parenSymOcc occ doc | isSymOcc occ = parens doc | otherwise = doc \end{code} @@ -396,8 +464,9 @@ parenSymOcc occ doc | isSymOcc occ = parens doc \begin{code} reportIfUnused :: OccName -> Bool - -- Haskell 98 encourages compilers to suppress warnings about - -- unused names in a pattern if they start with "_". +-- ^ Haskell 98 encourages compilers to suppress warnings about +-- unused names in a pattern if they start with @_@: this implements +-- that test reportIfUnused occ = case occNameString occ of ('_' : _) -> False _other -> True @@ -415,14 +484,14 @@ Here's our convention for splitting up the interface file name space: d... dictionary identifiers (local variables, so no name-clash worries) - $f... dict-fun identifiers (from inst decls) - $dm... default methods - $p... superclass selectors - $w... workers + \$f... dict-fun identifiers (from inst decls) + \$dm... default methods + \$p... superclass selectors + \$w... workers :T... compiler-generated tycons for dictionaries :D... ...ditto data cons :Co... ...ditto coercions - $sf.. specialised version of f + \$sf.. specialised version of f in encoded form these appear as Zdfxxx etc @@ -512,38 +581,37 @@ mkDataConWorkerOcc datacon_occ = setOccNameSpace varName datacon_occ \end{code} \begin{code} -mkSuperDictSelOcc :: Int -- Index of superclass, eg 3 - -> OccName -- Class, eg "Ord" - -> OccName -- eg "$p3Ord" +mkSuperDictSelOcc :: Int -- ^ Index of superclass, e.g. 3 + -> OccName -- ^ Class, e.g. @Ord@ + -> OccName -- ^ Derived 'Occname', e.g. @$p3Ord@ mkSuperDictSelOcc index cls_occ = mk_deriv varName "$p" (show index ++ occNameString cls_occ) -mkLocalOcc :: Unique -- Unique - -> OccName -- Local name (e.g. "sat") - -> OccName -- Nice unique version ("$L23sat") +mkLocalOcc :: Unique -- ^ Unique to combine with the 'OccName' + -> OccName -- ^ Local name, e.g. @sat@ + -> OccName -- ^ Nice unique version, e.g. @$L23sat@ mkLocalOcc uniq occ = mk_deriv varName ("$L" ++ show uniq) (occNameString occ) -- The Unique might print with characters -- that need encoding (e.g. 'z'!) \end{code} -Derive a name for the representation type constructor of a data/newtype -instance. - \begin{code} -mkInstTyTcOcc :: Int -- Index - -> OccName -- Family name (e.g. "Map") - -> OccName -- Nice unique version (":R23Map") +-- | Derive a name for the representation type constructor of a @data@/@newtype@ +-- instance. +mkInstTyTcOcc :: Int -- ^ DFun Index + -> OccName -- ^ Family name, e.g. @Map@ + -> OccName -- ^ Nice unique version, e.g. @:R23Map@ mkInstTyTcOcc index occ = mk_deriv tcName (":R" ++ show index) (occNameString occ) \end{code} \begin{code} -mkDFunOcc :: String -- Typically the class and type glommed together e.g. "OrdMaybe" +mkDFunOcc :: String -- ^ Typically the class and type glommed together e.g. @OrdMaybe@. -- Only used in debug mode, for extra clarity - -> Bool -- True <=> hs-boot instance dfun - -> Int -- Unique index - -> OccName -- "$f3OrdMaybe" + -> Bool -- ^ Is this a hs-boot instance DFun? + -> Int -- ^ Unique index + -> OccName -- ^ E.g. @$f3OrdMaybe@ -- In hs-boot files we make dict funs like $fx7ClsTy, which get bound to the real -- thing when we compile the mother module. Reason: we don't know exactly -- 1.7.10.4