Main data types

Type & coercion & id substitution

The Subst data type defined in this module contains substitution for tyvar, covar and id. However, operations on IdSubstEnv (mapping from Id to CoreExpr) that require the definition of the Expr data type are defined in GHC.Core.Subst to avoid circular module dependency.

A substitution of Types for TyVars and Kinds for KindVars

A substitution of Exprs for non-coercion Ids

A set of variables that are in scope at some point.

Note that this is a superset of the variables that are currently in scope. See Note [The InScopeSet invariant].

"Secrets of the Glasgow Haskell Compiler inliner" Section 3.2 provides the motivation for this abstraction.

De-shadowing the program is sometimes a useful pre-pass. It can be done simply by running over the bindings with an empty substitution, because substitution returns a result that has no-shadowing guaranteed.

(Actually, within a single type there might still be shadowing, because substTy is a no-op for the empty substitution, but that's probably OK.)

Aug 09

This function is not used in GHC at the moment, but seems so short and simple that I'm going to leave it here

Substitutes for the Ids within the RuleInfo given the new function Id

Substitute within a Type disabling the sanity checks. The problems that the sanity checks in substTy catch are described in Note [The substitution invariant]. The goal of #11371 is to migrate all the calls of substTyUnchecked to substTy and remove this function. Please don't use in new code.

Substitute within a Coercion The substitution has to satisfy the invariants described in Note [The substitution invariant].

substExpr applies a substitution to an entire CoreExpr. Remember, you may only apply the substitution once: See Note [Substitutions apply only once] in GHC.Core.TyCo.Subst

Do *not* attempt to short-cut in the case of an empty substitution! See Note [Extending the IdSubstEnv]

Apply a substitution to an entire CoreBind, additionally returning an updated Subst that should be used by subsequent substitutions.

Apply a substitution to an entire CoreBind, additionally returning an updated Subst that should be used by subsequent substitutions.

Substitutes for the Ids within an unfolding NB: substUnfolding discards any unfolding without without a Stable source. This is usually what we want, but it may be a bit unexpected

Substitutes for the Ids within an unfolding NB: substUnfolding discards any unfolding without without a Stable source. This is usually what we want, but it may be a bit unexpected

Find the substitution for an Id in the Subst The Id should not be a CoVar

Substitute into some IdInfo with regard to the supplied new Id. Discards unfoldings, unless they are Stable

Simultaneously substitute for a bunch of variables No left-right shadowing ie the substitution for (x y. e) a1 a2 so neither x nor y scope over a1 a2

Add a substitution for an Id to the Subst: you must ensure that the in-scope set is such that TyCoSubst Note [The substitution invariant] holds after extending the substitution like this

Adds multiple Id substitutions to the Subst: see also extendIdSubst

Adds multiple TyVar substitutions to the Subst: see also extendTvSubst

Add a substitution appropriate to the thing being substituted (whether an expression, type, or coercion). See also extendIdSubst, extendTvSubst, extendCvSubst

Add a substitution as appropriate to each of the terms being substituted (whether expressions, types, or coercions). See also extendSubst.

Add the Var to the in-scope set

Add the Vars to the in-scope set: see also extendInScope

Add the Vars to the in-scope set: see also extendInScope

Find the in-scope set: see Note [The substitution invariant]

Add a substitution for a TyVar to the Subst The TyVar *must* be a real TyVar, and not a CoVar You must ensure that the in-scope set is such that Note [The substitution invariant] holds after extending the substitution like this.

Add a substitution from a CoVar to a Coercion to the Subst: you must ensure that the in-scope set satisfies Note [The substitution invariant] after extending the substitution like this

Remove all substitutions that might have been built up while preserving the in-scope set originally called zapSubstEnv

Substitutes a Expr for another one according to the Subst given, returning the result and an updated Subst that should be used by subsequent substitutions. IdInfo is preserved by this process, although it is substituted into appropriately.

Applies substBndr to a number of Exprs, accumulating a new Subst left-to-right

Substitute in a mutually recursive group of Ids

Very similar to substBndr, but it always allocates a new Unique for each variable in its output. It substitutes the IdInfo though. Discards non-Stable unfoldings

Applies cloneIdBndr to a number of Ids, accumulating a final substitution from left to right Discards non-Stable unfoldings

Clone a mutually recursive group of Ids