[commit: ghc] master: Rename setRole_maybe to downgradeRole_maybe (9c81db4)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/9c81db45b098b2a44b1cad3d1043fba49aa070a7/ghc

>---------------------------------------------------------------

commit 9c81db45b098b2a44b1cad3d1043fba49aa070a7
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Wed Oct 29 16:35:19 2014 +0000

    Rename setRole_maybe to downgradeRole_maybe
    
    This change is just for naming uniformity with the existing downgradeRole


>---------------------------------------------------------------

9c81db45b098b2a44b1cad3d1043fba49aa070a7
 compiler/types/Coercion.lhs | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/compiler/types/Coercion.lhs b/compiler/types/Coercion.lhs
index 36eb711..dc0a7d0 100644
--- a/compiler/types/Coercion.lhs
+++ b/compiler/types/Coercion.lhs
@@ -844,7 +844,7 @@ mkSubCo: Requires a nominal input coercion and always produces a
 representational output. This is used when you (the programmer) are sure you
 know exactly that role you have and what you want.
 
-setRole_maybe: This function takes both the input role and the output role
+downgradeRole_maybe: This function takes both the input role and the output role
 as parameters. (The *output* role comes first!) It can only *downgrade* a
 role -- that is, change it from N to R or P, or from R to P. This one-way
 behavior is why there is the "_maybe". If an upgrade is requested, this
@@ -853,10 +853,10 @@ coercion, but you're not sure (as you're writing the code) of which roles are
 involved.
 
 This function could have been written using coercionRole to ascertain the role
-of the input. But, that function is recursive, and the caller of setRole_maybe
+of the input. But, that function is recursive, and the caller of downgradeRole_maybe
 often knows the input role. So, this is more efficient.
 
-downgradeRole: This is just like setRole_maybe, but it panics if the conversion
+downgradeRole: This is just like downgradeRole_maybe, but it panics if the conversion
 isn't a downgrade.
 
 setNominalRole_maybe: This is the only function that can *upgrade* a coercion. The result
@@ -880,7 +880,7 @@ API, as he was decomposing Core casts. The Core casts use representational coerc
 as they must, but his use case required nominal coercions (he was building a GADT).
 So, that's why this function is exported from this module.
 
-One might ask: shouldn't setRole_maybe just use setNominalRole_maybe as appropriate?
+One might ask: shouldn't downgradeRole_maybe just use setNominalRole_maybe as appropriate?
 I (Richard E.) have decided not to do this, because upgrading a role is bizarre and
 a caller should have to ask for this behavior explicitly.
 
@@ -1081,15 +1081,15 @@ mkSubCo co = ASSERT2( coercionRole co == Nominal, ppr co <+> ppr (coercionRole c
              SubCo co
 
 -- only *downgrades* a role. See Note [Role twiddling functions]
-setRole_maybe :: Role   -- desired role
-              -> Role   -- current role
-              -> Coercion -> Maybe Coercion
-setRole_maybe Representational Nominal = Just . mkSubCo
-setRole_maybe Nominal Representational = const Nothing
-setRole_maybe Phantom Phantom          = Just
-setRole_maybe Phantom _                = Just . mkPhantomCo
-setRole_maybe _ Phantom                = const Nothing
-setRole_maybe _ _                      = Just
+downgradeRole_maybe :: Role   -- desired role
+                    -> Role   -- current role
+                    -> Coercion -> Maybe Coercion
+downgradeRole_maybe Representational Nominal co = Just (mkSubCo co)
+downgradeRole_maybe Nominal Representational _  = Nothing
+downgradeRole_maybe Phantom Phantom          co = Just co
+downgradeRole_maybe Phantom _                co = Just (mkPhantomCo co)
+downgradeRole_maybe _ Phantom                _  = Nothing
+downgradeRole_maybe _ _                      co = Just co
 
 -- panics if the requested conversion is not a downgrade.
 -- See also Note [Role twiddling functions]
@@ -1097,7 +1097,7 @@ downgradeRole :: Role  -- desired role
               -> Role  -- current role
               -> Coercion -> Coercion
 downgradeRole r1 r2 co
-  = case setRole_maybe r1 r2 co of
+  = case downgradeRole_maybe r1 r2 co of
       Just co' -> co'
       Nothing  -> pprPanic "downgradeRole" (ppr co)
 
@@ -1158,8 +1158,9 @@ nthRole Phantom _ _ = Phantom
 nthRole Representational tc n
   = (tyConRolesX Representational tc) !! n
 
--- is one role "less" than another?
 ltRole :: Role -> Role -> Bool
+-- Is one role "less" than another?
+--     Nominal < Representational < Phantom
 ltRole Phantom          _       = False
 ltRole Representational Phantom = True
 ltRole Representational _       = False
@@ -1619,17 +1620,16 @@ failing for reason 2) is fine. matchAxiom is trying to find a set of coercions
 that match, but it may fail, and this is healthy behavior. Bottom line: if
 you find that liftCoSubst is doing weird things (like leaving out-of-scope
 variables lying around), disable coercion optimization (bypassing matchAxiom)
-and use downgradeRole instead of setRole_maybe. The panic will then happen,
+and use downgradeRole instead of downgradeRole_maybe. The panic will then happen,
 and you may learn something useful.
 
 \begin{code}
-
 liftCoSubstTyVar :: LiftCoSubst -> Role -> TyVar -> Maybe Coercion
 liftCoSubstTyVar (LCS _ cenv) r tv
   = do { co <- lookupVarEnv cenv tv
        ; let co_role = coercionRole co   -- could theoretically take this as
                                          -- a parameter, but painful
-       ; setRole_maybe r co_role co } -- see Note [liftCoSubstTyVar]
+       ; downgradeRole_maybe r co_role co } -- see Note [liftCoSubstTyVar]
 
 liftCoSubstTyVarBndr :: LiftCoSubst -> TyVar -> (LiftCoSubst, TyVar)
 liftCoSubstTyVarBndr subst@(LCS in_scope cenv) old_var