diff options
Diffstat (limited to 'docs')
27 files changed, 1984 insertions, 403 deletions
diff --git a/docs/comm/the-beast/data-types.html b/docs/comm/the-beast/data-types.html index fef4852d4d..4ec220c937 100644 --- a/docs/comm/the-beast/data-types.html +++ b/docs/comm/the-beast/data-types.html @@ -147,7 +147,7 @@ top-level nullary constructors (like True and False). Furthermore, what if the code generator encounters a non-saturated application of a worker? E.g. <tt>(map Just xs)</tt>. We could declare that to be an error (CorePrep should saturate them). But instead we currently -generate a top-level defintion for each constructor worker, whether +generate a top-level definition for each constructor worker, whether nullary or not. It takes the form: <pre> MkT{v} = \ p q r -> MkT{v} p q r @@ -157,7 +157,7 @@ one that generates abstract C and the byte-code generator) treats it as a specia allocates a MkT; it does not make a recursive call! So now there's a top-level curried version of the worker which is available to anyone who wants it. <p> -This strange defintion is not emitted into External Core. Indeed, you might argue that +This strange definition is not emitted into External Core. Indeed, you might argue that we should instead pass the list of <tt>TyCon</tt>s to the code generator and have it generate magic bindings directly. As it stands, it's a real hack: see the code in CorePrep.mkImplicitBinds. diff --git a/docs/comm/the-beast/ncg.html b/docs/comm/the-beast/ncg.html index 5810a35212..84beac2d51 100644 --- a/docs/comm/the-beast/ncg.html +++ b/docs/comm/the-beast/ncg.html @@ -542,7 +542,7 @@ the reg-alloc abstraction (implicitly) assumes. Our strategy is: do a good job for the common small subset, that is integer loads, stores, address calculations, basic ALU ops (+, -, and, or, xor), and jumps. That covers the vast majority of -executed insns. And indeed we do do a good job, with a loss of +executed insns. And indeed we do a good job, with a loss of less than 2% compared with gcc. <p> Initially we tried to handle integer instructions with awkward @@ -742,7 +742,7 @@ other way is a total time waster. <p><small> <!-- hhmts start --> -Last modified: Fri Feb 1 16:14:11 GMT 2002 +Last modified: Mon Aug 19 11:41:43 CEST 2013 <!-- hhmts end --> </small> </body> diff --git a/docs/core-spec/CoreLint.ott b/docs/core-spec/CoreLint.ott index beaf52a7d9..f2799841dc 100644 --- a/docs/core-spec/CoreLint.ott +++ b/docs/core-spec/CoreLint.ott @@ -1,3 +1,9 @@ +%% +%% CoreLint.ott +%% +%% defines formal version of core typing rules +%% +%% See accompanying README file %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Static semantics %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -54,7 +60,7 @@ t = literalType lit G |-tm lit : t G |-tm e : s -G |-co g : s ~#k t +G |-co g : s ~Rep k t ------------------- :: Cast G |-tm e |> g : t @@ -115,10 +121,14 @@ G |-ty t : k2 ---------------------------------------------------- :: Case G |-tm case e as z_s return t of </ alti // i /> : t -G |-co g : t1 ~#k t2 --------------------- :: Coercion +G |-co g : t1 ~Nom k t2 +-------------------- :: CoercionNom G |-tm g : t1 ~#k t2 +G |-co g : t1 ~Rep k t2 +----------------------- :: CoercionRep +G |-tm g : (~R#) k t1 t2 + defn G |- name n ok :: :: lintSingleBinding_lintBinder :: 'Name_' {{ com Name consistency check, \coderef{coreSyn/CoreLint.lhs}{lintSingleBinding\#lintBinder} }} {{ tex [[G]] \labeledjudge{n} [[n]] [[ok]] }} @@ -144,97 +154,179 @@ G |-ki k ok ---------------------------------------- :: TyVar G |-bnd alpha_k ok -defn G |- co g : t1 ~# k t2 :: :: lintCoercion :: 'Co_' +defn G |- co g : t1 ~ R k t2 :: :: lintCoercion :: 'Co_' {{ com Coercion typing, \coderef{coreSyn/CoreLint.lhs}{lintCoercion} }} - {{ tex [[G]] \labeledjudge{co} [[g]] : [[t1]] \mathop{\sim_{\#}^{[[k]]} } [[t2]] }} + {{ tex [[G]] \labeledjudge{co} [[g]] : [[t1]] \mathop{\sim_{[[R]]}^{[[k]]} } [[t2]] }} by G |-ty t : k ---------------------- :: Refl -G |-co <t> : t ~#k t +G |-co <t>_R : t ~R k t -G |-co g1 : s1 ~#k1 t1 -G |-co g2 : s2 ~#k2 t2 +G |-co g1 : s1 ~R k1 t1 +G |-co g2 : s2 ~R k2 t2 G |-arrow k1 -> k2 : k ------------------------- :: TyConAppCoFunTy -G |-co (->) g1 g2 : (s1 -> s2) ~#k (t1 -> t2) +G |-co (->)_R g1 g2 : (s1 -> s2) ~R k (t1 -> t2) T /= (->) -</ G |-co gi : si ~#ki ti // i /> +</ Ri // i /> = tyConRolesX R T +</ G |-co gi : si ~Ri ki ti // i /> G |-app </ (si : ki) // i /> : tyConKind T ~> k --------------------------------- :: TyConAppCo -G |-co T </ gi // i /> : T </ si // i /> ~#k T </ ti // i /> +G |-co T_R </ gi // i /> : T </ si // i /> ~R k T </ ti // i /> -G |-co g1 : s1 ~#k1 t1 -G |-co g2 : s2 ~#k2 t2 +G |-co g1 : s1 ~R k1 t1 +G |-co g2 : s2 ~Nom k2 t2 G |-app (s2 : k2) : k1 ~> k --------------------- :: AppCo -G |-co g1 g2 : (s1 s2) ~#k (t1 t2) +G |-co g1 g2 : (s1 s2) ~R k (t1 t2) + +G |-co g1 : s1 ~Ph k1 t1 +G |-co g2 : s2 ~Ph k2 t2 +G |-app (s2 : k2) : k1 ~> k +--------------------- :: AppCoPhantom +G |-co g1 g2 : (s1 s2) ~Ph k (t1 t2) G |-ki k1 ok -G, z_k1 |-co g : s ~#k2 t +G, z_k1 |-co g : s ~R k2 t --------------------------- :: ForAllCo -G |-co forall z_k1. g : (forall z_k1.s) ~#k2 (forall z_k1.t) +G |-co forall z_k1. g : (forall z_k1.s) ~R k2 (forall z_k1.t) z_(t ~#BOX t) elt G ----------------------- :: CoVarCoBox -G |-co z_(t ~#BOX t) : t ~#BOX t +G |-co z_(t ~#BOX t) : t ~Nom BOX t z_(s ~#k t) elt G k /= BOX ------------------------ :: CoVarCo -G |-co z_(s ~#k t) : s ~#k t +----------------------- :: CoVarCoNom +G |-co z_(s ~#k t) : s ~Nom k t + +z_(s ~R#k t) elt G +k /= BOX +----------------------- :: CoVarCoRepr +G |-co z_(s ~R#k t) : s ~Rep k t G |-ty t1 : k ------------------------------ :: UnsafeCo -G |-co t1 ==>! t2 : t1 ~#k t2 +----------------------------- :: UnivCo +G |-co t1 ==>!_R t2 : t1 ~R k t2 -G |-co g : t1 ~#k t2 +G |-co g : t1 ~R k t2 ------------------------- :: SymCo -G |-co sym g : t2 ~#k t1 +G |-co sym g : t2 ~R k t1 -G |-co g1 : t1 ~#k t2 -G |-co g2 : t2 ~#k t3 +G |-co g1 : t1 ~R k t2 +G |-co g2 : t2 ~R k t3 ----------------------- :: TransCo -G |-co g1 ; g2 : t1 ~#k t3 +G |-co g1 ; g2 : t1 ~R k t3 -G |-co g : (T </ sj // j />) ~#k (T </ tj // j />) +G |-co g : (T </ sj // j />) ~R k (T </ tj // j />) length </ sj // j /> = length </ tj // j /> i < length </ sj // j /> G |-ty si : k +R' = (tyConRolesX R T)[i] ---------------------- :: NthCo -G |-co nth i g : si ~#k ti +G |-co nth i g : si ~R' k ti -G |-co g : (s1 s2) ~#k (t1 t2) +G |-co g : (s1 s2) ~Nom k' (t1 t2) G |-ty s1 : k ----------------------- :: LRCoLeft -G |-co Left g : s1 ~#k t1 +G |-co Left g : s1 ~Nom k t1 -G |-co g : (s1 s2) ~#k (t1 t2) +G |-co g : (s1 s2) ~Nom k' (t1 t2) G |-ty s2 : k ----------------------- :: LRCoRight -G |-co Right g : s2 ~#k t2 +G |-co Right g : s2 ~Nom k t2 -G |-co g : forall m.s ~#k forall n.t +G |-co g : forall m.s ~R k forall n.t G |-ty t0 : k0 m = z_k1 k0 <: k1 --------------------- :: InstCo -G |-co g t0 : s[m |-> t0] ~#k t[n |-> t0] +G |-co g t0 : s[m |-> t0] ~R k t[n |-> t0] -C = T </ axBranchkk // kk /> +C = T_R0 </ axBranchkk // kk /> 0 <= ind < length </ axBranchkk // kk /> -forall </ ni // i />. (</ s1j // j /> ~> t1) = (</ axBranchkk // kk />)[ind] -</ G |-co gi : s'i ~#k'i t'i // i /> +forall </ ni_Ri // i />. (</ s1j // j /> ~> t1) = (</ axBranchkk // kk />)[ind] +</ G |-co gi : s'i ~Ri k'i t'i // i /> </ substi @ // i /> = inits(</ [ ni |-> s'i ] // i />) </ ni = zi_ki // i /> </ k'i <: substi(ki) // i /> -no_conflict(C, </ s2j // j />, ind-1) +no_conflict(C, </ s2j // j />, ind, ind-1) </ s2j = s1j </ [ni |-> s'i] // i/> // j /> t2 = t1 </ [ni |-> t'i] // i /> G |-ty t2 : k ------------------------------------------------------ :: AxiomInstCo -G |-co C ind </ gi // i /> : T </ s2j // j /> ~#k t2 +G |-co C ind </ gi // i /> : T </ s2j // j /> ~R0 k t2 + +defn validRoles T :: :: checkValidRoles :: 'Cvr_' + {{ com Type constructor role validity, \coderef{typecheck/TcTyClsDecls.lhs}{checkValidRoles} }} +by + +</ Ki // i /> = tyConDataCons T +</ Rj // j /> = tyConRoles T +</ validDcRoles </ Rj // j /> Ki // i /> +------------------------------------ :: DataCons +validRoles T + +defn validDcRoles </ Raa // aa /> K :: :: check_dc_roles :: 'Cdr_' + {{ com Data constructor role validity, \coderef{typecheck/TcTyClsDecls.lhs}{check\_dc\_roles} }} +by + +forall </ naa // aa />. forall </ mbb // bb />. </ tcc // cc /> @ -> T </ naa // aa /> = dataConRepType K +</ </ naa : Raa // aa />, </ mbb : Nom // bb /> |- tcc : Rep // cc /> +--------------------------------- :: Args +validDcRoles </ Raa // aa /> K + +defn O |- t : R :: :: check_ty_roles :: 'Ctr_' + {{ com Type role validity, \coderef{typecheck/TcTyClsDecls.lhs}{check\_ty\_roles} }} + {{ tex [[O]] \labeledjudge{ctr} [[t]] : [[R]] }} +by + +O(n) = R' +R' <= R +---------- :: TyVarTy +O |- n : R + +</ Ri // i /> = tyConRoles T +</ Ri elt { Nom, Rep } => O |- ti : Ri // i /> +-------------------------- :: TyConAppRep +O |- T </ ti // i /> : Rep + +</ O |- ti : Nom // i /> +--------------------------- :: TyConAppNom +O |- T </ ti // i /> : Nom + +O |- t1 : R +O |- t2 : Nom +-------------------------- :: AppTy +O |- t1 t2 : R + +O |- t1 : R +O |- t2 : R +------------------- :: FunTy +O |- t1 -> t2 : R + +O, n : Nom |- t : R +--------------------- :: ForAllTy +O |- forall n. t : R + +------------------ :: LitTy +O |- lit : R + +defn R1 <= R2 :: :: ltRole :: 'Rlt_' + {{ com Sub-role relation, \coderef{types/Coercion.lhs}{ltRole} }} + {{ tex [[R1]] \leq [[R2]] }} +by + +-------- :: Nominal +Nom <= R + +-------- :: Phantom +R <= Ph + +------- :: Refl +R <= R defn G |- ki k ok :: :: lintKind :: 'K_' {{ com Kind validity, \coderef{coreSyn/CoreLint.lhs}{lintKind} }} @@ -403,16 +495,32 @@ Constraint <: * ------------------ :: LiftedConstraint * <: Constraint -defn no_conflict ( C , </ sj // j /> , ind ) :: :: check_no_conflict :: 'NoConflict_' - {{ com Branched axiom conflict checking, \coderef{coreSyn/CoreLint.lhs}{lintCoercion\#check\_no\_conflict} }} +defn no_conflict ( C , </ sj // j /> , ind1 , ind2 ) :: :: check_no_conflict :: 'NoConflict_' + {{ com \parbox{5in}{Branched axiom conflict checking, \coderef{types/OptCoercion.lhs}{checkAxInstCo} \\ and \coderef{types/FamInstEnv.lhs}{compatibleBranches} } }} by ------------------------------------------------ :: NoBranch -no_conflict(C, </ si // i/>, -1) +no_conflict(C, </ si // i/>, ind, -1) -C = T </ axBranchkk // kk /> -forall </ ni // i />. (</ tj // j /> ~> t') = (</ axBranchkk // kk />)[ind] +C = T_R </ axBranchkk // kk /> +forall </ ni_Ri // i />. (</ tj // j /> ~> t') = (</ axBranchkk // kk />)[ind2] apart(</ sj // j />, </ tj // j />) -no_conflict(C, </ sj // j />, ind-1) ------------------------------------------------- :: Branch -no_conflict(C, </ sj // j />, ind) +no_conflict(C, </ sj // j />, ind1, ind2-1) +------------------------------------------------ :: Incompat +no_conflict(C, </ sj // j />, ind1, ind2) + +C = T_R </ axBranchkk // kk /> +forall </ ni_Ri // i />. (</ tj // j /> ~> s) = (</ axBranchkk // kk />)[ind1] +forall </ n'i_R'i // i />. (</ t'j // j /> ~> s') = (</ axBranchkk // kk />)[ind2] +apart(</ tj // j />, </ t'j // j />) +no_conflict(C, </ sj // j />, ind1, ind2-1) +------------------------------------------- :: CompatApart +no_conflict(C, </ sj // j />, ind1, ind2) + +C = T_R </ axBranchkk // kk /> +forall </ ni_Ri // i />. (</ tj // j /> ~> s) = (</ axBranchkk // kk />)[ind1] +forall </ n'i_R'i // i />. (</ t'j // j /> ~> s') = (</ axBranchkk // kk />)[ind2] +unify(</ tj // j />, </ t'j // j />) = subst +subst(s) = subst(s') +----------------------------------------- :: CompatCoincident +no_conflict(C, </ sj // j />, ind1, ind2)
\ No newline at end of file diff --git a/docs/core-spec/CoreSyn.ott b/docs/core-spec/CoreSyn.ott index 4c59849bb6..ca060f2f72 100644 --- a/docs/core-spec/CoreSyn.ott +++ b/docs/core-spec/CoreSyn.ott @@ -1,3 +1,9 @@ +%% +%% CoreSyn.ott +%% +%% defines formal version of core syntax +%% +%% See accompanying README file embed {{ tex-preamble \newcommand{\coderef}[2]{\ghcfile{#1}:\texttt{#2}% @@ -16,7 +22,7 @@ metavar alpha {{ tex \alpha }}, beta {{ tex \beta }} ::= metavar N ::= {{ com Type-level constructor names }} metavar K ::= {{ com Term-level data constructor names }} -indexvar i, j, kk {{ tex k }} ::= {{ com Indices to be used in lists }} +indexvar i, j, kk {{ tex k }}, aa {{ tex a }}, bb {{ tex b }}, cc {{ tex c }} ::= {{ com Indices to be used in lists }} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Syntax %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -34,12 +40,17 @@ z :: 'Name_' ::= {{ com Term or type name }} n, m :: 'Var_' ::= {{ com Variable names, \coderef{basicTypes/Var.lhs}{Var} }} | z _ t :: :: IdOrTyVar {{ com Name, labeled with type/kind }} {{ tex {[[z]]}^{[[t]]} }} + | K :: M :: DataCon {{ com Data constructor }} vars :: 'Vars_' ::= {{ com List of variables }} - | </ ni // , // i /> :: :: List - | fv ( t ) :: M :: fv + | </ ni // , // i /> :: :: List + | fv ( t ) :: M :: fv_t {{ tex \textit{fv}([[t]]) }} - | empty :: M :: empty + | fv ( e ) :: M :: fv_e + {{ tex \textit{fv}([[e]]) }} + | empty :: M :: empty + | vars1 \inter vars2 :: M :: intersection + {{ tex [[vars1]] \cap [[vars2]] }} e, u :: 'Expr_' ::= {{ com Expressions, \coderef{coreSyn/CoreSyn.lhs}{Expr} }} | n :: :: Var {{ com Variable }} @@ -53,7 +64,10 @@ e, u :: 'Expr_' ::= {{ com Expressions, \coderef{coreSyn/CoreSyn.lhs}{Expr} }} {{ tex {[[e]]}_{\{[[tick]]\} } }} | t :: :: Type {{ com Type }} | g :: :: Coercion {{ com Coercion }} - | e [ n |-> t ] :: M :: TySubst {{ com Type substitution }} + | e subst :: M :: Subst {{ com Substitution }} + | ( e ) :: M :: Parens {{ com Parenthesized expression }} + | e </ ui // i /> :: M :: Apps {{ com Nested application }} + | S ( n ) :: M :: Lookup {{ com Lookup in the runtime store }} binding :: 'Bind_' ::= {{ com Let-bindings, \coderef{coreSyn/CoreSyn.lhs}{Bind} }} | n = e :: :: NonRec {{ com Non-recursive binding }} @@ -85,43 +99,58 @@ t {{ tex \tau }}, k {{ tex \kappa }}, s {{ tex \sigma }} | tyConKind T :: M :: tyConKind {{ com \coderef{types/TyCon.lhs}{tyConKind} }} | t1 ~# k t2 :: M :: unliftedEq {{ com Metanotation for coercion types }} {{ tex [[t1]] \mathop{\sim_{\#}^{[[k]]} } [[t2]] }} + | t1 ~R# k t2 :: M :: unliftedREq {{ com Metanotation for coercion types }} + {{ tex [[t1]] \mathop{\sim_{\mathsf{R}\#}^{[[k]]} } [[t2]] }} | literalType t :: M :: literalType {{ com \coderef{basicTypes/Literal.lhs}{literalType} }} | ( t ) :: M :: parens {{ com Parentheses }} | t [ n |-> s ] :: M :: TySubst {{ com Type substitution }} | subst ( k ) :: M :: TySubstList {{ com Type substitution list }} | t subst :: M :: TySubstListPost {{ com Type substitution list }} | dataConRepType K :: M :: dataConRepType {{ com Type of DataCon }} + | forall </ ni // , // i /> . t + :: M :: ForAllTys {{ com Nested polymorphism }} + | </ ti // i /> @ -> t' :: M :: FunTys {{ com Nested arrows }} %% COERCIONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% g {{ tex \gamma }} :: 'Coercion_' ::= {{ com Coercions, \coderef{types/Coercion.lhs}{Coercion} }} - | < t > :: :: Refl {{ com Reflexivity }} - {{ tex \langle [[t]] \rangle }} - | T </ gi // i /> :: :: TyConAppCo {{ com Type constructor application }} + | < t > _ R :: :: Refl {{ com Reflexivity }} + {{ tex {\langle [[t]] \rangle}_{[[R]]} }} + | T RA </ gi // i /> :: :: TyConAppCo {{ com Type constructor application }} | g1 g2 :: :: AppCo {{ com Application }} | forall n . g :: :: ForAllCo {{ com Polymorphism }} | n :: :: CoVarCo {{ com Variable }} | C ind </ gj // j /> :: :: AxiomInstCo {{ com Axiom application }} - | t1 ==>! t2 :: :: UnsafeCo {{ com Unsafe coercion }} + | t1 ==>! RA t2 :: :: UnivCo {{ com Universal coercion }} | sym g :: :: SymCo {{ com Symmetry }} | g1 ; g2 :: :: TransCo {{ com Transitivity }} - | nth i g :: :: NthCo {{ com Projection (0-indexed) }} - {{ tex \textsf{nth}_{[[i]]}\,[[g]] }} + | nth I g :: :: NthCo {{ com Projection (0-indexed) }} + {{ tex \textsf{nth}_{[[I]]}\,[[g]] }} | LorR g :: :: LRCo {{ com Left/right projection }} | g t :: :: InstCo {{ com Type application }} | ( g ) :: M :: Parens {{ com Parentheses }} + | t @ liftingsubst :: M :: Lifted {{ com Type lifted to coercion }} LorR :: 'LeftOrRight_' ::= {{ com left or right deconstructor, \coderef{types/Coercion.lhs}{LeftOrRight} }} | Left :: :: CLeft {{ com Left projection }} | Right :: :: CRight {{ com Right projection }} C :: 'CoAxiom_' ::= {{ com Axioms, \coderef{types/TyCon.lhs}{CoAxiom} }} - | T </ axBranchi // ; // i /> :: :: CoAxiom {{ com Axiom }} - | ( C ) :: M :: Parens {{ com Parentheses }} + | T RA </ axBranchi // ; // i /> :: :: CoAxiom {{ com Axiom }} + | ( C ) :: M :: Parens {{ com Parentheses }} + +R {{ tex \rho }} :: 'Role_' ::= {{ com Roles, \coderef{types/CoAxiom.lhs}{Role} }} + | Nom :: :: Nominal {{ com Nominal }} + {{ tex \mathsf{N} }} + | Rep :: :: Representational {{ com Representational }} + {{ tex \mathsf{R} }} + | Ph :: :: Phantom {{ com Phantom }} + {{ tex \mathsf{P} }} + | role_list [ i ] :: M :: RoleListIndex {{ com Look up in list }} axBranch, b :: 'CoAxBranch_' ::= {{ com Axiom branches, \coderef{types/TyCon.lhs}{CoAxBranch} }} - | forall </ ni // i /> . ( </ tj // j /> ~> s ) :: :: CoAxBranch {{ com Axiom branch }} - | ( </ axBranchi // i /> ) [ ind ] :: M :: lookup {{ com List lookup }} + | forall </ ni RAi // i /> . ( </ tj // j /> ~> s ) :: :: CoAxBranch {{ com Axiom branch }} + | ( </ axBranchi // i /> ) [ ind ] :: M :: lookup {{ com List lookup }} %% TYCONS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -137,13 +166,14 @@ T :: 'TyCon_' ::= {{ com Type constructors, \coderef{types/TyCon.lhs}{TyCon} }} | dataConTyCon K :: M :: dataConTyCon {{ com TyCon extracted from DataCon }} H :: 'PrimTyCon_' ::= {{ com Primitive type constructors, \coderef{prelude/TysPrim.lhs}{} }} - | Int# :: :: intPrimTyCon {{ com Unboxed Int }} - | ( ~# ) :: :: eqPrimTyCon {{ com Unboxed equality }} - | BOX :: :: superKindTyCon {{ com Sort of kinds }} - | * :: :: liftedTypeKindTyCon {{ com Kind of lifted types }} - | # :: :: unliftedTypeKindTyCon {{ com Kind of unlifted types }} - | OpenKind :: :: openTypeKindTyCon {{ com Either $*$ or $\#$ }} - | Constraint :: :: constraintTyCon {{ com Constraint }} + | Int# :: :: intPrimTyCon {{ com Unboxed Int (\texttt{intPrimTyCon}) }} + | ( ~# ) :: :: eqPrimTyCon {{ com Unboxed equality (\texttt{eqPrimTyCon}) }} + | ( ~R# ) :: :: eqReprPrimTyCon {{ com Unboxed representational equality (\texttt{eqReprPrimTyCon}) }} + | BOX :: :: superKindTyCon {{ com Sort of kinds (\texttt{superKindTyCon}) }} + | * :: :: liftedTypeKindTyCon {{ com Kind of lifted types (\texttt{liftedTypeKindTyCon}) }} + | # :: :: unliftedTypeKindTyCon {{ com Kind of unlifted types (\texttt{unliftedTypeKindTyCon}) }} + | OpenKind :: :: openTypeKindTyCon {{ com Either $*$ or $\#$ (\texttt{openTypeKindTyCon}) }} + | Constraint :: :: constraintTyCon {{ com Constraint (\texttt{constraintTyCon}) }} %% CONTEXTS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -152,6 +182,14 @@ G {{ tex \Gamma }} :: 'LintM_Bindings_' ::= {{ com List of bindings, \coderef{co | </ Gi // , // i /> :: :: Concat {{ com Context concatenation }} | vars_of binding :: M :: VarsOf {{ com \coderef{coreSyn/CoreSyn.lhs}{bindersOf} }} +O {{ tex \Omega }} :: 'VarEnv_Role_' ::= {{ com Mapping from type variables to roles }} + | </ ni : Ri // i /> :: :: List {{ com List of bindings }} + | O1 , O2 :: M :: Concat {{ com Concatenate two lists }} + +S {{ tex \Sigma }} :: 'St_' ::= {{ com Runtime store }} + | [ n |-> e ] :: :: Binding {{ com Single binding }} + | </ Si // , // i /> :: :: Concat {{ com Store concatentation }} + %% UTILITY %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% B {{ tex \mathbb{B} }} :: 'Bool_' ::= {{ com Booleans in metatheory }} @@ -162,17 +200,39 @@ kinded_types {{ tex \overline{(\sigma_i : \kappa_i)}^i }} :: 'Kinded_Types_' ::= | </ ( si : ki ) // , // i /> :: :: List | empty :: M :: empty -subst :: 'Subst_' ::= {{ com List of type substitutions }} - | [ n |-> t ] :: :: Mapping +subst :: 'Subst_' ::= {{ com List of substitutions }} + | [ n |-> t ] :: :: TyMapping + | [ n |-> e ] :: :: TmMapping | </ substi // i /> :: :: List -ind :: 'Ind_' ::= {{ com Indices, numbers }} +liftingsubst :: 'LiftSubst_' ::= {{ com List of lifting substitutions }} + | [ n |-> g ] :: :: Mapping + | </ liftingsubsti // i /> :: :: List + +ind, I {{ tex i }} :: 'Ind_' ::= {{ com Indices, numbers }} | i :: :: index | length </ ti // i /> :: M :: length_t | length </ axBranchi // i /> :: M :: length_axBranch | tyConArity T :: M :: tyConArity | ind - 1 :: M :: decrement | -1 :: M :: minusOne + | 0 :: M :: zero + | 1 :: M :: one + | 2 :: M :: two + +type_list :: 'TypeList_' ::= {{ com List of types }} + | </ si // i /> :: :: List + +RA {{ tex {\!\!\!{}_{\rho} } }} :: 'RoleAnnot_' ::= {{ com Role annotation }} + | _ R :: M :: annotation + {{ tex {}_{[[R]]} }} + +role_list :: 'RoleList_' ::= {{ com List of roles }} + | </ Ri // , // i /> :: :: List + | tyConRolesX R T :: M :: tyConRolesX + | tyConRoles T :: M :: tyConRoles + | ( role_list ) :: M :: Parens + | { role_list } :: M :: Braces %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Terminals %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -199,6 +259,7 @@ terminals :: 'terminals_' ::= | BOX :: :: BOX {{ tex \Box }} | Int# :: :: int_hash {{ tex {\textsf{Int} }_{\#} }} | ~# :: :: eq_hash {{ tex \mathop{ {\sim}_{\#} } }} + | ~R# :: :: eq_repr_hash {{ tex \mathop{ {\sim}_{\mathsf{R}\#} } }} | OpenKind :: :: OpenKind {{ tex \textsf{OpenKind} }} | ok :: :: ok {{ tex \textsf{ ok} }} | no_duplicates :: :: no_duplicates {{ tex \textsf{no\_duplicates } }} @@ -229,6 +290,14 @@ terminals :: 'terminals_' ::= | Constraint :: :: Constraint {{ tex \textsf{Constraint} }} | no_conflict :: :: no_conflict {{ tex \textsf{no\_conflict} }} | apart :: :: apart {{ tex \textsf{apart} }} + | unify :: :: unify {{ tex \textsf{unify} }} + | tyConRolesX :: :: tyConRolesX {{ tex \textsf{tyConRolesX} }} + | tyConRoles :: :: tyConRoles {{ tex \textsf{tyConRoles} }} + | tyConDataCons :: :: tyConDataCons {{ tex \textsf{tyConDataCons} }} + | validRoles :: :: validRoles {{ tex \textsf{validRoles} }} + | validDcRoles :: :: validDcRoles {{ tex \textsf{validDcRoles} }} + | --> :: :: steps {{ tex \longrightarrow }} + | coercionKind :: :: coercionKind {{ tex \textsf{coercionKind} }} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Formulae %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -264,12 +333,28 @@ formula :: 'formula_' ::= | k1 elt { </ ki // , // i /> } :: :: kind_elt | e is_a_type :: :: is_a_type {{ tex \exists \tau \text{ s.t.~} [[e]] = \tau }} - | t is_a_coercion :: :: is_a_coercion + | e is_a_coercion :: :: is_a_coercion + {{ tex \exists \gamma \text{ s.t.~} [[e]] = \gamma }} + | t is_a_prop :: :: is_a_prop {{ tex \exists \tau_1, \tau_2, \kappa \text{ s.t.~} [[t]] = \tau_1 \mathop{ {\sim}_{\#}^{\kappa} } \tau_2 }} | axBranch1 = axBranch2 :: :: branch_rewrite | C1 = C2 :: :: axiom_rewrite | apart ( </ ti // i /> , </ sj // j /> ) :: :: apart + | unify ( </ ti // i /> , </ sj // j /> ) = subst :: :: unify + | role_list1 = role_list2 :: :: eq_role_list + | R1 /= R2 :: :: role_neq + | R1 = R2 :: :: eq_role + | </ Ki // i /> = tyConDataCons T :: :: tyConDataCons + | O ( n ) = R :: :: role_lookup + | R elt role_list :: :: role_elt + | formula1 => formula2 :: :: implication + {{ tex [[formula1]] \implies [[formula2]] }} + | alt1 = alt2 :: :: alt_rewrite + | e1 = e2 :: :: e_rewrite + | no other case matches :: :: no_other_case + {{ tex \text{no other case matches} }} + | t = coercionKind g :: :: coercionKind %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Subrules and Parsing %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -289,8 +374,15 @@ TyCon_AlgTyCon right Coercion_AppCo TyCon_PromotedDataCon right Coercion_AppCo TyCon_PromotedTyCon right Coercion_AppCo -Subst_Mapping <= Type_TySubstList +Subst_TyMapping <= Type_TySubstList +Subst_TmMapping <= Type_TySubstList Subst_List <= Type_TySubstList -Subst_Mapping <= Type_TySubstListPost +Subst_TyMapping <= Type_TySubstListPost +Subst_TmMapping <= Type_TySubstListPost + +Expr_Type <= formula_e_rewrite + +Coercion_TyConAppCo <= Coercion_AppCo +Expr_Coercion <= Subst_TmMapping diff --git a/docs/core-spec/Makefile b/docs/core-spec/Makefile index 1a5b27cd75..402f9dbe4e 100644 --- a/docs/core-spec/Makefile +++ b/docs/core-spec/Makefile @@ -1,10 +1,11 @@ -OTT_FILES = CoreSyn.ott CoreLint.ott +OTT_FILES = CoreSyn.ott CoreLint.ott OpSem.ott OTT_TEX = CoreOtt.tex OTT_OPTS = -tex_show_meta false TARGET = core-spec $(TARGET).pdf: $(TARGET).tex $(OTT_TEX) - latexmk -pdf $< + latex -output-format=pdf $< + latex -output-format=pdf $< $(TARGET).tex: $(TARGET).mng $(OTT_FILES) ott $(OTT_OPTS) -tex_filter $< $@ $(OTT_FILES) diff --git a/docs/core-spec/OpSem.ott b/docs/core-spec/OpSem.ott new file mode 100644 index 0000000000..1c21ada0ec --- /dev/null +++ b/docs/core-spec/OpSem.ott @@ -0,0 +1,97 @@ + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Dynamic semantics %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% The definitions in this file do *not* strictly correspond to any specific +% code in GHC. They are here to provide a reasonable operational semantic +% interpretation to the typing rules presented in the other ott files. Thus, +% your mileage may vary. In particular, there has been *no* attempt to +% write any formal proofs over these semantics. +% +% With that disclaimer disclaimed, these rules are a reasonable jumping-off +% point for an analysis of FC's operational semantics. If you don't want to +% worry about mutual recursion (and who does?), you can even drop the +% environment S. + +grammar + +defns +OpSem :: '' ::= + +defn S |- e --> e' :: :: step :: 'S_' {{ com Single step semantics }} +{{ tex [[S]] \labeledjudge{op} [[e]] [[-->]] [[e']] }} +by + +S(n) = e +----------------- :: Var +S |- n --> e + +S |- e1 --> e1' +------------------- :: App +S |- e1 e2 --> e1' e2 + +----------------------------- :: Beta +S |- (\n.e1) e2 --> e1[n |-> e2] + +g0 = sym (nth 0 g) +g1 = nth 1 g +not e2 is_a_type +not e2 is_a_coercion +----------------------------------------------- :: Push +S |- ((\n.e1) |> g) e2 --> (\n.e1 |> g1) (e2 |> g0) + +---------------------------------------- :: TPush +S |- ((\n.e) |> g) t --> (\n.(e |> g n)) t + +g0 = nth 1 (nth 0 g) +g1 = sym (nth 2 (nth 0 g)) +g2 = nth 1 g +------------------------------- :: CPush +S |- ((\n.e) |> g) g' --> (\n.e |> g2) (g0 ; g' ; g1) + +----------------- :: LetNonRec +S |- let n = e1 in e2 --> e2[n |-> e1] + + +S, </ [ni |-> ei] // i /> |- u --> u' +------------------------------------ :: LetRec +S |- let rec </ ni = ei // i /> in u --> let rec </ ni = ei // i /> in u' + +fv(u) \inter </ ni // i /> = empty +------------------------------------------ :: LetRecReturn +S |- let rec </ ni = ei // i /> in u --> u + + +S |- e --> e' +--------------------------------------- :: Case +S |- case e as n return t of </ alti // i /> --> case e' as n return t of </ alti // i /> + +altj = K </ alphabb_kbb // bb /> </ xcc_tcc // cc /> -> u +u' = u[n |-> e] </ [alphabb_kbb |-> sbb] // bb /> </ [xcc_tcc |-> ecc] // cc /> +-------------------------------------------------------------- :: MatchData +S |- case K </ t'aa // aa /> </ sbb // bb /> </ ecc // cc /> as n return t of </ alti // i /> --> u' + +altj = lit -> u +---------------------------------------------------------------- :: MatchLit +S |- case lit as n return t of </ alti // i /> --> u[n |-> lit] + +altj = _ -> u +no other case matches +------------------------------------------------------------ :: MatchDefault +S |- case e as n return t of </ alti // i /> --> u[n |-> e] + +T </ taa // aa /> ~#k T </ t'aa // aa /> = coercionKind g +forall </ alphaaa_kaa // aa />. forall </ betabb_k'bb // bb />. </ t1cc // cc /> @-> T </ alphaaa_kaa // aa /> = dataConRepType K +</ e'cc = ecc |> (t1cc @ </ [alphaaa_kaa |-> nth aa g] // aa /> </ [betabb_k'bb |-> <sbb>_Nom] // bb />) // cc /> +--------------------------- :: CasePush +S |- case (K </ taa // aa /> </ sbb // bb /> </ ecc // cc />) |> g as n return t2 of </ alti // i /> --> case K </ t'aa // aa /> </ sbb // bb /> </ e'cc // cc /> as n return t2 of </ alti // i /> + +S |- e --> e' +------------------------ :: Cast +S |- e |> g --> e' |> g + +S |- e --> e' +------------------------------ :: Tick +S |- e { tick } --> e' { tick } + diff --git a/docs/core-spec/README b/docs/core-spec/README index e193955490..1fb304d261 100644 --- a/docs/core-spec/README +++ b/docs/core-spec/README @@ -64,7 +64,7 @@ your notation to LaTeX. Three different homs are used: help disambiguate otherwise-ambiguous parses. Getting these right is hard, so if you have trouble, you're not alone. -- In one place, it was necessary to use an @ symbol to disambiguate parses. The +- In a few places, it is necessary to use an @ symbol to disambiguate parses. The @ symbol is not typeset and is used solely for disambiguation. Feel free to use it if necessary to disambiguate other parses. diff --git a/docs/core-spec/core-spec.mng b/docs/core-spec/core-spec.mng index 4b1e986c6d..2e8134c7a1 100644 --- a/docs/core-spec/core-spec.mng +++ b/docs/core-spec/core-spec.mng @@ -7,6 +7,7 @@ \usepackage{xcolor} \usepackage{fullpage} \usepackage{multirow} +\usepackage{url} \newcommand{\ghcfile}[1]{\textsl{#1}} \newcommand{\arraylabel}[1]{\multicolumn{2}{l}{\!\!\!\!\!\!\!\!\!\text{\underline{#1}:}}} @@ -19,7 +20,7 @@ \setlength{\parindent}{0in} \setlength{\parskip}{1ex} -\newcommand{\gram}[1]{\ottgrammartabular{#1\ottinterrule}} +\newcommand{\gram}[1]{\ottgrammartabular{#1\ottafterlastrule}} \begin{document} @@ -29,11 +30,28 @@ System FC, as implemented in GHC\footnote{This document was originally prepared by Richard Eisenberg (\texttt{eir@cis.upenn.edu}), but it should be maintained by anyone who edits the functions or data structures mentioned in this file. Please feel free to contact Richard for more information.}\\ -\Large\today +\Large 2 August, 2013 \end{center} \section{Introduction} +This document presents the typing system of System FC, very closely to how it is +implemented in GHC. Care is taken to include only those checks that are actually +written in the GHC code. It should be maintained along with any changes to this +type system. + +Who will use this? Any implementer of GHC who wants to understand more about the +type system can look here to see the relationships among constructors and the +different types used in the implementation of the type system. Note that the +type system here is quite different from that of Haskell---these are the details +of the internal language, only. + +At the end of this document is a \emph{hypothetical} operational semantics for GHC. +It is hypothetical because GHC does not strictly implement a concrete operational +semantics anywhere in its code. While all the typing rules can be traced back to +lines of real code, the operational semantics do not, in general, have as clear +a provenance. + There are a number of details elided from this presentation. The goal of the formalism is to aid in reasoning about type safety, and checks that do not work toward this goal were omitted. For example, various scoping checks (other @@ -64,7 +82,6 @@ variables: \gram{ \ottz } -foo \gram{ \ottn @@ -132,13 +149,21 @@ a term-level literal, but we are ignoring this distinction here. Invariants on coercions: \begin{itemize} -\item $[[<t1 t2>]]$ is used; never $[[<t1> <t2>]]$. -\item If $[[<T>]]$ is applied to some coercions, at least one of which is not -reflexive, use $[[T </ gi // i />]]$, never $[[<T> g1 g2]] \ldots$. -\item The $[[T]]$ in $[[T </gi//i/>]]$ is never a type synonym, though it could +\item $[[<t1 t2>_R]]$ is used; never $[[<t1>_R <t2>_Nom]]$. +\item If $[[<T>_R]]$ is applied to some coercions, at least one of which is not +reflexive, use $[[T_R </ gi // i />]]$, never $[[<T>_R g1 g2]] \ldots$. +\item The $[[T]]$ in $[[T_R </gi//i/>]]$ is never a type synonym, though it could be a type function. \end{itemize} +Roles label what equality relation a coercion is a witness of. Nominal equality +means that two types are identical (have the same name); representational equality +means that two types have the same representation (introduced by newtypes); and +phantom equality includes all types. See \url{http://ghc.haskell.org/trac/ghc/wiki/Roles} +for more background. + +\gram{\ottR} + Is it a left projection or a right projection? \gram{\ottLorR} @@ -150,6 +175,12 @@ Axioms: \ottaxBranch } +The definition for $[[axBranch]]$ above does not include the list of +incompatible branches (field \texttt{cab\_incomps} of \texttt{CoAxBranch}), +as that would unduly clutter this presentation. Instead, as the list +of incompatible branches can be computed at any time, it is checked for +in the judgment $[[no_conflict]]$. See Section~\ref{sec:no_conflict}. + \subsection{Type constructors} Type constructors in GHC contain \emph{lots} of information. We leave most of it out @@ -179,7 +210,7 @@ the context sometimes requires creating a new, fresh variable name and then applying a substitution. We elide these details in this formalism, but see \coderef{types/Type.lhs}{substTyVarBndr} for details. -\section{Judgments} +\section{Typing judgments} The following functions are used from GHC. Their names are descriptive, and they are not formalized here: \coderef{types/TyCon.lhs}{tyConKind}, @@ -263,12 +294,22 @@ a dead id and for one-tuples. These checks are omitted here. \subsection{Coercion typing} +In the coercion typing judgment, the $\#$ marks are left off the equality +operators to reduce clutter. This is not actually inconsistent, because +the GHC function that implements this check, \texttt{lintCoercion}, actually +returns four separate values (the kind, the two types, and the role), not +a type with head $[[(~#)]]$ or $[[(~R#)]]$. Note that the difference between +these two forms of equality is interpreted in the rules \ottdrulename{Co\_CoVarCoNom} +and \ottdrulename{Co\_CoVarCoRepr}. + \ottdefnlintCoercion{} In \ottdrulename{Co\_AxiomInstCo}, the use of $[[inits]]$ creates substitutions from the first $i$ mappings in $[[ </ [ni |-> si] // i /> ]]$. This has the effect of folding the substitution over the kinds for kind-checking. +See Section~\ref{sec:tyconroles} for more information about $[[tyConRolesX]]$. + \subsection{Name consistency} There are two very similar checks for names, one declared as a local function: @@ -305,17 +346,108 @@ There are two very similar checks for names, one declared as a local function: \ottdefnisSubKind{} +\subsection{Roles} +\label{sec:tyconroles} + +During type-checking, role inference is carried out, assigning roles to the +arguments of every type constructor. The function $[[tyConRoles]]$ extracts these +roles. Also used in other judgments is $[[tyConRolesX]]$, which is the same as +$[[tyConRoles]]$, but with an arbitrary number of $[[Nom]]$ at the end, to account +for potential oversaturation. + +The checks encoded in the following +judgments are run from \coderef{typecheck/TcTyClsDecls.lhs}{checkValidTyCon} +when \texttt{-dcore-lint} is set. + +\ottdefncheckValidRoles{} + +\ottdefncheckXXdcXXroles{} + +In the following judgment, the role $[[R]]$ is an \emph{input}, not an output. + +\ottdefncheckXXtyXXroles{} + +These judgments depend on a sub-role relation: + +\ottdefnltRole{} + \subsection{Branched axiom conflict checking} +\label{sec:no_conflict} The following judgment is used within \ottdrulename{Co\_AxiomInstCo} to make sure that a type family application cannot unify with any previous branch -in the axiom. +in the axiom. The actual code scans through only those branches that are +flagged as incompatible. These branches are stored directly in the +$[[axBranch]]$. However, it is cleaner in this presentation to simply +check for compatibility here. \ottdefncheckXXnoXXconflict{} -The judgment $[[apart]]$ checks to see whether two lists of types are surely apart. -It checks to see if \coderef{types/Unify.lhs}{tcApartTys} returns \texttt{SurelyApart}. -Two types are apart if neither type is a type family application and if they do not -unify. +The judgment $[[apart]]$ checks to see whether two lists of types are surely +apart. $[[apart( </ ti // i />, </ si // i /> )]]$, where $[[ </ ti // i /> +]]$ is a list of types and $[[ </ si // i /> ]]$ is a list of type +\emph{patterns} (as in a type family equation), first flattens the $[[ </ ti + // i /> ]]$ using \coderef{types/FamInstEnv.lhs}{flattenTys} and then checks to +see if \coderef{types/Unify.lhs}{tcUnifyTysFG} returns \texttt{SurelyApart}. +Flattening takes all type family applications and replaces them with fresh variables, +taking care to map identical type family applications to the same fresh variable. + +The algorithm $[[unify]]$ is implemented in \coderef{types/Unify.lhs}{tcUnifyTys}. +It performs a standard unification, returning a substitution upon success. + +\section{Operational semantics} + +\subsection{Disclaimer} +GHC does not implement an operational semantics in any concrete form. Most +of the rules below are implied by algorithms in, for example, the simplifier +and optimizer. Yet, there is no one place in GHC that states these rules, +analogously to \texttt{CoreLint.lhs}. +Nevertheless, these rules are included in this document to help the reader +understand System FC. + +\subsection{The context $[[S]]$} +We use a context $[[S]]$ to keep track of the values of variables in a (mutually) +recursive group. Its definition is as follows: +\[ +[[S]] \quad ::= \quad [[ empty ]] \ |\ [[S]], [[ [n |-> e] ]] +\] +The presence of the context $[[S]]$ is solely to deal with recursion. If your +use of FC does not require modeling recursion, you will not need to track $[[S]]$. + +\subsection{Operational semantics rules} + +\ottdefnstep{} + +\subsection{Notes} + +\begin{itemize} +\item The \ottdrulename{S\_LetRec} and \ottdrulename{S\_LetRecReturn} rules +implement recursion. \ottdrulename{S\_LetRec} adds to the context $[[S]]$ bindings +for all of the mutually recursive equations. Then, after perhaps many steps, +when the body of the $[[let]]\ [[rec]]$ contains no variables that are bound +in the $[[let]]\ [[rec]]$, the context is popped. +\item In the $[[case]]$ rules, a constructor $[[K]]$ is written taking three +lists of arguments: two lists of types and a list of terms. The types passed +in are the universally and, respectively, existentially quantified type variables +to the constructor. The terms are the regular term arguments stored in an +algebraic datatype. Coercions (say, in a GADT) are considered term arguments. +\item The rule \ottdrulename{S\_CasePush} is the most complex rule. +\begin{itemize} +\item The logic in this rule is implemented in \coderef{coreSyn/CoreSubst.lhs}{exprIsConApp\_maybe}. +\item The $[[coercionKind]]$ function (\coderef{types/Coercion.lhs}{coercionKind}) +extracts the two types (and their kind) from +a coercion. It does not require a typing context, as it does not \emph{check} the +coercion, just extracts its types. +\item The $[[dataConRepType]]$ function (\coderef{basicTypes/DataCon.lhs}{dataConRepType}) extracts the full type of a data constructor. Following the notation for +constructor expressions, the parameters to the constructor are broken into three +groups: universally quantified types, existentially quantified types, and terms. +\item The substitutions in the last premise to the rule are unusual: they replace +\emph{type} variables with \emph{coercions}. This substitution is called lifting +and is implemented in \coderef{types/Coercion.lhs}{liftCoSubst}. The notation is +essentially a pun on the fact that types and coercions have such similar structure. +\item Note that the types $[[ </ sbb // bb /> ]]$---the existentially quantified +types---do not change during this step. +\end{itemize} +\end{itemize} \end{document} diff --git a/docs/core-spec/core-spec.pdf b/docs/core-spec/core-spec.pdf Binary files differindex be13ca22c5..4e4ca924fb 100644 --- a/docs/core-spec/core-spec.pdf +++ b/docs/core-spec/core-spec.pdf diff --git a/docs/storage-mgt/ldv.tex b/docs/storage-mgt/ldv.tex index 936407c701..79f0f23282 100644 --- a/docs/storage-mgt/ldv.tex +++ b/docs/storage-mgt/ldv.tex @@ -388,7 +388,7 @@ There are four cases in which a closure is destroyed: \begin{enumerate} \item A closure is overwritten with a blackhole: - @UPD_BH_UPDATABLE()@ and @UPD_BH_SINGLE_ENTRY()@ in @includes/StgMacros.h@, + @UPD_BH_UPDATABLE()@ in @includes/StgMacros.h@, @threadLazyBlackHole()@ and @threadSqueezeStack()@ in @GC.c@, the entry code for @BLACKHOLE@ closures in @StgMiscClosures.hc@ (a @BLACKHOLE@ closure is changed into a @BLACKHOLE_BQ@ closure). @@ -499,7 +499,7 @@ size, we invoke @LDV_recordDead_FILL_SLOP_DYNAMIC()@ only from: \begin{enumerate} \item @threadLazyBlackHole()@ and @threadSqueezeStack()@ in @GC.c@ (for lazy blackholing), -\item @UPD_BH_UPDATABLE()@ and @UPD_BH_SINGLE_ENTRY()@ in +\item @UPD_BH_UPDATABLE()@ in @includes/StgMacros.h@ (for eager blackholing, which isn't the default), \item @updateWithIndirection()@ and @updateWithPermIndirection()@ @@ -639,7 +639,7 @@ Only three files (@includes/StgLdvProf.h@, @LdvProfile.c@, and with LDVU profiling. \item[ClosureMacros.h] changes macro @SET_PROF_HDR()@. \item[Stg.h] includes th header file @StgLdvProf.h@. -\item[StgMacros.h] changes macros @UPD_BH_UPDATABLE()@ and @UPD_BH_SINGLE_ENTRY()@. +\item[StgMacros.h] changes macros @UPD_BH_UPDATABLE()@. \end{description} @\rts@ directory: diff --git a/docs/users_guide/7.8.1-notes.xml b/docs/users_guide/7.8.1-notes.xml index 20785d09fa..f3fa0e1984 100644 --- a/docs/users_guide/7.8.1-notes.xml +++ b/docs/users_guide/7.8.1-notes.xml @@ -3,9 +3,9 @@ <title>Release notes for version 7.8.1</title> <para> - The significant changes to the various parts of the compiler are - listed in the following sections. There have also been numerous bug - fixes and performance improvements over the 7.6 branch. + The significant changes to the various parts of the compiler are listed + in the following sections. There have also been numerous bug fixes and + performance improvements over the 7.6 branch. </para> <sect2> @@ -16,18 +16,585 @@ </para> <itemizedlist> - <listitem> - <para> - TODO: Format these nicely and expand: - - type holes - - rebindable list syntax - - major changes to the type inference engine - - type level naturals - - overlapping type families - - new codegen - </para> - </listitem> + <listitem> + <para> + GHC now supports "type holes" with the + <literal>TypeHoles</literal> extension. When enabled, the + unbound literal <literal>_</literal> may be used during + development in place of a regular identifier, and GHC will + respond with the type necessary to "fill in the hole." + + TODO FIXME: reference. + </para> + </listitem> + + <listitem> + <para> + It is now possible to declare a 'closed' <literal>type + family</literal> when using the + <literal>TypeFamilies</literal> extension. A closed + <literal>type family</literal> cannot have any + instances created other than the ones in its + definition. + + TODO FIXME: reference. + </para> + </listitem> + + <listitem> + <para> + Use of the <literal>GeneralizedNewtypeDeriving</literal> + extension is now subject to <emphasis>role checking</emphasis>, + to ensure type safety of the derived instances. As this change + increases the type safety of GHC, it is possible that some code + that previously compiled will no longer work. + + TODO FIXME: reference. + </para> + </listitem> + + <listitem> + <para> + GHC now supports overloading list literals using the new + <literal>OverloadedLists</literal> extension. + + TODO FIXME: reference. + </para> + </listitem> + + <listitem> + <para> + There has been significant overhaul of the type inference engine and + constraint solver. + + TODO FIXME: reference. + </para> + </listitem> + + <listitem> + <para> + By default, GHC will now unbox all "small" strict + fields in a data type. A "small" data type is one + whose size is equivalent to or smaller than the native + word size of the machine. This means you no longer + have to specify <literal>UNPACK</literal> pragmas for + e.g. strict <literal>Int</literal> fields. This also + applies to floating-point values. + </para> + </listitem> + + <listitem> + <para> + GHC now has a brand-new I/O manager that scales significantly + better for larger workloads compared to the previous one. It + should scale linearly up to approximately 32 cores. + </para> + </listitem> + + <listitem> + <para> + The LLVM backend now supports 128bit SIMD operations. This is + now exploited in both the <literal>vector</literal> and + <literal>dph</literal> packages, exposing a high level + interface. + + TODO FIXME: reference. + </para> + <para> + This is only available with the LLVM backend. + </para> + </listitem> + + <listitem> + <para> + The new code generator, after significant work by many + individuals over the past several years, is now enabled by + default. This is a complete rewrite of the STG to Cmm + transformation. In general, your programs may get slightly + faster. + </para> + + <para> + The old code generator has been removed completely. + </para> + </listitem> + + <listitem> + <para> + PrimOps for comparing unboxed values now return + <literal>Int#</literal> instead of <literal>Bool</literal>. + New PrimOps' names end with <literal>$#</literal> for operators and + <literal>I#</literal> for ordinary names, e.g. <literal>==$#</literal> + compares <literal>Int#</literal>s for equality and + <literal>eqCharI#</literal> does the same for <literal>Char#</literal>s. + Old PrimOps have been removed and turned into wrappers. See + <ulink url="http://ghc.haskell.org/trac/ghc/wiki/NewPrimopsInGHC7.8"> + this GHC wiki page</ulink> for instructions how to update your + existing code. + </para> + </listitem> + + <listitem> + <para> + TODO: mention dynamic changes + </para> + </listitem> + + <listitem> + <para> + TODO: mention new <literal>Typeable</literal> and + <literal>AutoDeriveTypeable</literal> + </para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Full details</title> + <sect3> + <title>Language</title> + <itemizedlist> + <listitem> + <para> + There is a new extension, + <literal>NullaryTypeClasses</literal>, which + allows you to declare a type class without any + parameters. + + TODO FIXME: example? + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Compiler</title> + <itemizedlist> + <listitem> + <para> + GHC now supports a <literal>--show-options</literal> flag, + which will dump all of the flags it supports to standard out. + </para> + </listitem> + <listitem> + <para> + It's now possible to switch the system linker on Linux + (between GNU gold and GNU ld) at runtime without problem. + </para> + </listitem> + <listitem> + <para> + The <literal>-fwarn-dodgy-imports</literal> flag now warns + in the case an <literal>import</literal> statement hides an + entity which is not exported. + </para> + </listitem> + <listitem> + <para> + The LLVM backend was overhauled and rewritten, and + should hopefully be easier to maintain and work on + in the future. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>GHCi</title> + <itemizedlist> + <listitem> + <para> + GHCi now supports a <literal>prompt2</literal> + setting, which allows you to customize the + continuation prompt of multi-line input. + + TODO FIXME: reference. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Template Haskell</title> + <itemizedlist> + <listitem> + <para> + TODO FIXME + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Runtime system</title> + <itemizedlist> + <listitem> + <para> + The performance of <literal>StablePtr</literal>s and + <literal>StableName</literal>s has been improved. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Build system</title> + <itemizedlist> + <listitem> + <para> + GHC >= 7.4 is now required for bootstrapping. + </para> + </listitem> + <listitem> + <para> + GHC can now be built with Clang, and use Clang as the + preprocessor for Haskell code. Only Clang version 3.4svn is + reliably supported. + </para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + + <sect2> + <title>Libraries</title> + + <para> + There have been some changes that have effected multiple + libraries: + </para> + + <itemizedlist> + <listitem> + <para> + TODO FIXME + </para> + </listitem> </itemizedlist> + + <para> + The following libraries have been removed from the GHC tree: + </para> + + <itemizedlist> + <listitem> + <para>TODO FIXME</para> + </listitem> + </itemizedlist> + + <para> + The following libraries have been added to the GHC tree: + </para> + + <itemizedlist> + <listitem> + <para>TODO FIXME</para> + </listitem> + </itemizedlist> + + <sect3> + <title>array</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>base</title> + <itemizedlist> + <listitem> + <para> + Version number 4.7.0.0 (was 4.6.0.1) + </para> + </listitem> + <listitem> + <para> + The <literal>Control.Category</literal> module now has the + <literal>PolyKinds</literal> extension enabled, meaning + that instances of <literal>Category</literal> no longer + need be of kind <literal>* -> * -> *</literal> + </para> + </listitem> + <listitem> + <para> + There are now <literal>Foldable</literal> and <literal>Traversable</literal> + instances for <literal>Either a</literal> and <literal>(,) a</literal> + </para> + </listitem> + <listitem> + <para> + <literal>Control.Concurrent.MVar</literal> has a new + implementation of <literal>readMVar</literal>, which + fixes a long-standing bug where + <literal>readMVar</literal> is only atomic if there + are no other threads running + <literal>putMVar</literal>. + <literal>readMVar</literal> now is atomic, and is + guaranteed to return the value from the first + <literal>putMVar</literal>. There is also a new <literal>tryReadMVar</literal> + which is a non-blocking version. + </para> + </listitem> + <listitem> + <para> + There are now byte endian-swapping primitives + available in <literal>Data.Word</literal>, which + use optimized machine instructions when available. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>bin-package-db</title> + <itemizedlist> + <listitem> + <para> + This is an internal package, and should not be used. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>binary</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>bytestring</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Cabal</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>containers</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>deepseq</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>directory</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>filepath</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>ghc-prim</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>haskell98</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>haskell2010</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>hoopl</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>hpc</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>integer-gmp</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>old-locale</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>old-time</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>process</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>template-haskell</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>time</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>unix</title> + <itemizedlist> + <listitem> + <para> + Version number 2.7.0.0 (was 2.6.0.0) + </para> + </listitem> + <listitem> + <para> + A crash in <literal>getGroupEntryForID</literal> + (and related functions like + <literal>getUserEntryForID</literal> and + <literal>getUserEntryForName</literal>) in + multi-threaded applications has been fixed. + </para> + </listitem> + <listitem> + <para> + The functions <literal>getGroupEntryForID</literal> + and <literal>getUserEntryForID</literal> now fail + with a <literal>isDoesNotExist</literal> error when + the specified ID cannot be found. + </para> + </listitem> + </itemizedlist> + </sect3> + + <sect3> + <title>Win32</title> + <itemizedlist> + <listitem> + <para> + Version number XXXX (was XXXX) + </para> + </listitem> + </itemizedlist> + </sect3> </sect2> </sect1> - diff --git a/docs/users_guide/extending_ghc.xml b/docs/users_guide/extending_ghc.xml index 1abe8a8f68..dc8d5b4739 100644 --- a/docs/users_guide/extending_ghc.xml +++ b/docs/users_guide/extending_ghc.xml @@ -247,9 +247,8 @@ pass = do dflags <- getDynFlags {-# LANGUAGE DeriveDataTypeable #-} module SayAnnNames.Plugin (plugin, SomeAnn) where import GhcPlugins -import Control.Monad (when) +import Control.Monad (unless) import Data.Data -import Data.Typeable data SomeAnn = SomeAnn deriving (Data, Typeable) @@ -264,13 +263,15 @@ install _ todo = do return (CoreDoPluginPass "Say name" pass : todo) pass :: ModGuts -> CoreM ModGuts -pass g = mapM_ (printAnn g) (mg_binds g) >> return g - where printAnn :: ModGuts -> CoreBind -> CoreM CoreBind - printAnn guts bndr@(NonRec b _) = do +pass g = do + dflags <- getDynFlags + mapM_ (printAnn dflags g) (mg_binds g) >> return g + where printAnn :: DynFlags -> ModGuts -> CoreBind -> CoreM CoreBind + printAnn dflags guts bndr@(NonRec b _) = do anns <- annotationsOn guts b :: CoreM [SomeAnn] - when (not $ null anns) $ putMsgS $ "Annotated binding found: " ++ showSDoc (ppr b) + unless (null anns) $ putMsgS $ "Annotated binding found: " ++ showSDoc dflags (ppr b) return bndr - printAnn _ bndr = return bndr + printAnn _ _ bndr = return bndr annotationsOn :: Data a => ModGuts -> CoreBndr -> CoreM [a] annotationsOn guts bndr = do diff --git a/docs/users_guide/external_core.xml b/docs/users_guide/external_core.xml index faf7148f20..bc9d350d34 100644 --- a/docs/users_guide/external_core.xml +++ b/docs/users_guide/external_core.xml @@ -27,8 +27,7 @@ I am unsure of the proper DocBook elements. <para>Andrew Tolmach, Tim Chevalier ({apt,tjc}@cs.pdx.edu) and The GHC Team</para> - <abstract> - <para>This document provides a precise definition for the GHC Core + <para>This chapter provides a precise definition for the GHC Core language, so that it can be used to communicate between GHC and new stand-alone compilation tools such as back-ends or optimizers.<footnote> @@ -51,8 +50,6 @@ I am unsure of the proper DocBook elements. formally embody the static and dynamic semantics, are available separately.</para> - </abstract> - <section id="introduction"> <title>Introduction</title> diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml index a2fe177612..32f714851f 100644 --- a/docs/users_guide/ffi-chap.xml +++ b/docs/users_guide/ffi-chap.xml @@ -274,7 +274,7 @@ extern HsInt foo(HsInt a0);</programlisting> <filename>M_stub.o</filename> in the final link command line, or you'll get link errors for the missing function(s) (this isn't necessary when building your program with <literal>ghc - ––make</literal>, as GHC will automatically link in the + --make</literal>, as GHC will automatically link in the correct bits).</para> <sect3 id="using-own-main"> diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index 5366360f37..ba4b0b13b0 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -30,7 +30,7 @@ <entry>-</entry> </row> <row> - <entry><option>-help</option></entry> + <entry><option>--help</option></entry> <entry>help</entry> <entry>mode</entry> <entry>-</entry> @@ -54,31 +54,37 @@ <entry>-</entry> </row> <row> - <entry><option>––supported-extensions</option> or <option>––supported-languages</option></entry> + <entry><option>--supported-extensions</option> or <option>--supported-languages</option></entry> <entry>display the supported languages and language extensions</entry> <entry>mode</entry> <entry>-</entry> </row> <row> - <entry><option>––info</option></entry> + <entry><option>--show-options</option></entry> + <entry>display the supported command line options</entry> + <entry>mode</entry> + <entry>-</entry> + </row> + <row> + <entry><option>--info</option></entry> <entry>display information about the compiler</entry> <entry>mode</entry> <entry>-</entry> </row> <row> - <entry><option>––version</option></entry> + <entry><option>--version</option></entry> <entry>display GHC version</entry> <entry>mode</entry> <entry>-</entry> </row> <row> - <entry><option>––numeric-version</option></entry> + <entry><option>--numeric-version</option></entry> <entry>display GHC version (numeric only)</entry> <entry>mode</entry> <entry>-</entry> </row> <row> - <entry><option>––print-libdir</option></entry> + <entry><option>--print-libdir</option></entry> <entry>display GHC library directory</entry> <entry>mode</entry> <entry>-</entry> @@ -784,6 +790,12 @@ <entry><option>-XNPlusKPatterns</option></entry> </row> <row> + <entry><option>-XNegativeLiterals</option></entry> + <entry>Enable support for negative literals</entry> + <entry>dynamic</entry> + <entry><option>-XNoNegativeLiterals</option></entry> + </row> + <row> <entry><option>-XNoTraditionalRecordSyntax</option></entry> <entry>Disable support for traditional record syntax (as supported by Haskell 98) <literal>C {f = x}</literal></entry> <entry>dynamic</entry> @@ -1009,7 +1021,7 @@ </row> <row> <entry><option>-XTypeOperators</option></entry> - <entry>Enable type operators.</entry> + <entry>Enable <link linkend="type-operators">type operators</link>.</entry> <entry>dynamic</entry> <entry><option>-XNoTypeOperators</option></entry> </row> diff --git a/docs/users_guide/ghc.mk b/docs/users_guide/ghc.mk index bfd9433f7c..69864cc689 100644 --- a/docs/users_guide/ghc.mk +++ b/docs/users_guide/ghc.mk @@ -20,8 +20,8 @@ docs/users_guide_DOCBOOK_SOURCES := \ $(wildcard docs/users_guide/*.xml) \ $(basename $(wildcard docs/users_guide/*.xml.in))) -$(docs/users_guide_GENERATED_DOCBOOK_SOURCES): %.xml: inplace/bin/mkUserGuidePart$(exeext) - inplace/bin/mkUserGuidePart$(exeext) $@ +$(docs/users_guide_GENERATED_DOCBOOK_SOURCES): %.xml: $(mkUserGuidePart_INPLACE) + $(mkUserGuidePart_INPLACE) $@ $(eval $(call docbook,docs/users_guide,users_guide)) diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 93ab62bf29..df483e81f3 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -161,7 +161,7 @@ Ok, modules loaded: Main. <para>or it can be set using the <literal>:set</literal> command from within GHCi (see <xref linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in - GHCi, and <option>––make</option> mode, the <option>-i</option> + GHCi, and <option>--make</option> mode, the <option>-i</option> option is used to specify the search path for <emphasis>source</emphasis> files, whereas in standard batch-compilation mode the <option>-i</option> option is used to @@ -338,7 +338,7 @@ Compiling A ( A.hs, interpreted ) <para>HINT: since GHCi will only use a compiled object file if it can be sure that the compiled version is up-to-date, a good technique when working on a large program is to occasionally run - <literal>ghc ––make</literal> to compile the whole project (say + <literal>ghc --make</literal> to compile the whole project (say before you go for lunch :-), then continue working in the interpreter. As you modify code, the changed modules will be interpreted, but the rest of the project will remain @@ -1715,7 +1715,7 @@ a :: a <para>The history is only available when using <literal>:trace</literal>; the reason for this is we found that logging each breakpoint in the history cuts performance by a factor of - 2 or more. By default, GHCi remembers the last 50 steps in the history, but this can be changed with the <option>-fghci-hist-size=<replaceable>n</replaceable></option><indexterm><primary><option>–fghci-hist-size</option></primary></indexterm> option).</para> + 2 or more. By default, GHCi remembers the last 50 steps in the history, but this can be changed with the <option>-fghci-hist-size=<replaceable>n</replaceable></option><indexterm><primary><option>-fghci-hist-size</option></primary></indexterm> option).</para> </sect2> <sect2 id="ghci-debugger-exceptions"> @@ -1910,10 +1910,10 @@ Just 20 <sect1 id="ghci-invocation"> <title>Invoking GHCi</title> <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm> - <indexterm><primary><option>––interactive</option></primary></indexterm> + <indexterm><primary><option>--interactive</option></primary></indexterm> <para>GHCi is invoked with the command <literal>ghci</literal> or - <literal>ghc ––interactive</literal>. One or more modules or + <literal>ghc --interactive</literal>. One or more modules or filenames can also be specified on the command line; this instructs GHCi to load the specified modules or filenames (and all the modules they depend on), just as if you had said @@ -2180,6 +2180,93 @@ maybe :: b -> (a -> b) -> Maybe a -> b <varlistentry> <term> + <literal>:complete</literal> <replaceable>type</replaceable> + <optional><replaceable>n</replaceable>-</optional><optional><replaceable>m</replaceable></optional> + <replaceable>string-literal</replaceable> + <indexterm><primary><literal>:complete</literal></primary></indexterm> + </term> + <listitem> + <para>This command allows to request command completions + from GHCi even when interacting over a pipe instead of a + proper terminal and is designed for integrating GHCi's + completion with text editors and IDEs.</para> + + <para>When called, <literal>:complete</literal> prints the + <replaceable>n</replaceable><superscript>th</superscript> to + <replaceable>m</replaceable><superscript>th</superscript> + completion candidates for the partial input + <replaceable>string-literal</replaceable> for the completion + domain denoted by + <replaceable>type</replaceable>. Currently, only the + <literal>repl</literal> domain is supported which denotes + the kind of completion that would be provided interactively + by GHCi at the input prompt.</para> + + <para>If omitted, <replaceable>n</replaceable> and + <replaceable>m</replaceable> default to the first or last + available completion candidate respectively. If there are + less candidates than requested via the range argument, + <replaceable>n</replaceable> and + <replaceable>m</replaceable> are implicitly capped to the + number of available completition candidates.</para> + + <para>The output of <literal>:complete</literal> begins with + a header line containing three space-delimited fields: + + <itemizedlist> + <listitem>An integer denoting the number + <replaceable>l</replaceable> of printed + completions,</listitem> + + <listitem>an integer denoting the total number of + completions available, and finally</listitem> + + <listitem>a string literal denoting a common + prefix to be added to the returned completion + candidates.</listitem> + </itemizedlist> + + The header line is followed by <replaceable>l</replaceable> + lines each containing one completion candidate encoded as + (quoted) string literal. Here are some example invocations + showing the various cases:</para> + +<screen> +Prelude> :complete repl 0 "" +0 470 "" +Prelude> :complete repl 5 "import For" +5 21 "import " +"Foreign" +"Foreign.C" +"Foreign.C.Error" +"Foreign.C.String" +"Foreign.C.Types" +Prelude> :complete repl 5-10 "import For" +6 21 "import " +"Foreign.C.Types" +"Foreign.Concurrent" +"Foreign.ForeignPtr" +"Foreign.ForeignPtr.Safe" +"Foreign.ForeignPtr.Unsafe" +"Foreign.Marshal" +Prelude> :complete repl 20- "import For" +2 21 "import " +"Foreign.StablePtr" +"Foreign.Storable" +Prelude> :complete repl "map" +3 3 "" +"map" +"mapM" +"mapM_" +Prelude> :complete repl 5-10 "map" +0 3 "" +</screen> + + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>:continue</literal> <indexterm><primary><literal>:continue</literal></primary></indexterm> </term> @@ -2255,11 +2342,11 @@ Prelude> :mycd .. </screen> <para>Or I could define a simple way to invoke - “<literal>ghc ––make Main</literal>” in the + “<literal>ghc --make Main</literal>” in the current directory:</para> <screen> -Prelude> :def make (\_ -> return ":! ghc ––make Main") +Prelude> :def make (\_ -> return ":! ghc --make Main") </screen> <para>We can define a command that reads GHCi input from a @@ -2410,9 +2497,11 @@ Prelude> :. cmds.ghci and (b) all the other things mentioned in the instance are in scope (either qualified or otherwise) as a result of a <literal>:load</literal> or <literal>:module</literal> commands. </para> + <para> The command <literal>:info!</literal> works in a similar fashion but it removes restriction (b), showing all instances that are in scope and mention <replaceable>name</replaceable> in their head. + </para> </listitem> </varlistentry> @@ -2426,7 +2515,21 @@ Prelude> :. cmds.ghci <para>Infers and prints the kind of <replaceable>type</replaceable>. The latter can be an arbitrary type expression, including a partial application of a type constructor, - such as <literal>Either Int</literal>. If you specify the + such as <literal>Either Int</literal>. In fact, <literal>:kind</literal> + even allows you to write a partial application of a type synonym (usually disallowed), + so that this works: +<programlisting> +ghci> type T a b = (a,b,a) +ghci> :k T Int Bool +T Int Bool :: * +ghci> :k T +T :: * -> * -> * +ghci> :k T Int +T Int :: * -> * +</programlisting> + </para> + <para> + If you specify the optional "<literal>!</literal>", GHC will in addition normalise the type by expanding out type synonyms and evaluating type-function applications, and display the normalised result.</para> @@ -2684,8 +2787,10 @@ bar <para>Sets the string to be used as the prompt in GHCi. Inside <replaceable>prompt</replaceable>, the sequence <literal>%s</literal> is replaced by the names of the - modules currently in scope, and <literal>%%</literal> is - replaced by <literal>%</literal>. If <replaceable>prompt</replaceable> + modules currently in scope, <literal>%l</literal> is replaced + by the line number (as referenced in compiler messages) of the + current prompt, and <literal>%%</literal> is replaced by + <literal>%</literal>. If <replaceable>prompt</replaceable> starts with " then it is parsed as a Haskell String; otherwise it is treated as a literal string.</para> </listitem> @@ -2693,6 +2798,16 @@ bar <varlistentry> <term> + <literal>:set</literal> <literal>prompt2</literal> <replaceable>prompt</replaceable> + </term> + <listitem> + <para>Sets the string to be used as the continuation prompt + (used when using the <literal>:{</literal> command) in GHCi.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal>:set</literal> <literal>stop</literal> [<replaceable>num</replaceable>] <replaceable>cmd</replaceable> </term> diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index c396237f27..0b16156595 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -440,6 +440,21 @@ Indeed, the bindings can even be recursive. </para> </sect2> + <sect2 id="negative-literals"> + <title>Negative Literals</title> + <para> + The literal <literal>-123</literal> is, according to + Haskell98 and Haskell 2010, desugared as + <literal>negate (fromInteger 123)</literal>. + </para> + + <para> + The language extension <option>-XNegativeLiterals</option> + means that it is instead desugared as + <literal>fromInteger (-123)</literal>. + </para> + </sect2> + <!-- ====================== HIERARCHICAL MODULES ======================= --> @@ -844,10 +859,10 @@ To disable it, you can use the <option>-XNoTraditionalRecordSyntax</option> flag The do-notation of Haskell 98 does not allow <emphasis>recursive bindings</emphasis>, that is, the variables bound in a do-expression are visible only in the textually following code block. Compare this to a let-expression, where bound variables are visible in the entire binding - group. -</para> + group. +</para> -<para> +<para> It turns out that such recursive bindings do indeed make sense for a variety of monads, but not all. In particular, recursion in this sense requires a fixed-point operator for the underlying monad, captured by the <literal>mfix</literal> method of the <literal>MonadFix</literal> class, defined in <literal>Control.Monad.Fix</literal> as follows: @@ -888,7 +903,7 @@ justOnes = do { rec { xs <- Just (1:xs) } As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [-1,-1,-1,...</literal>. </para> -<para> +<para> GHC's implementation the mdo-notation closely follows the original translation as described in the paper <ulink url="https://sites.google.com/site/leventerkok/recdo.pdf">A recursive do for Haskell</ulink>, which in turn is based on the work <ulink url="http://sites.google.com/site/leventerkok/erkok-thesis.pdf">Value Recursion @@ -922,14 +937,14 @@ As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [-1, to the underlying monadic value-recursion operator <literal>mfix</literal>, belonging to the <literal>MonadFix</literal> class. Here is an example: <programlisting> -rec { b <- f a c ===> (b,c) <- mfix (\~(b,c) -> do { b <- f a c - ; c <- f b a } ; c <- f b a - ; return (b,c) }) +rec { b <- f a c ===> (b,c) <- mfix (\ ~(b,c) -> do { b <- f a c + ; c <- f b a } ; c <- f b a + ; return (b,c) }) </programlisting> As usual, the meta-variables <literal>b</literal>, <literal>c</literal> etc., can be arbitrary patterns. In general, the statement <literal>rec <replaceable>ss</replaceable></literal> is desugared to the statement <programlisting> -<replaceable>vs</replaceable> <- mfix (\~<replaceable>vs</replaceable> -> do { <replaceable>ss</replaceable>; return <replaceable>vs</replaceable> }) +<replaceable>vs</replaceable> <- mfix (\ ~<replaceable>vs</replaceable> -> do { <replaceable>ss</replaceable>; return <replaceable>vs</replaceable> }) </programlisting> where <replaceable>vs</replaceable> is a tuple of the variables bound by <replaceable>ss</replaceable>. </para> @@ -1677,8 +1692,8 @@ Note that <literal>\case</literal> starts a layout, so you can write <sect2 id="empty-case"> <title>Empty case alternatives</title> <para> -The <option>-XEmptyCase</option> flag enables -case expressions, or lambda-case expressions, that have no alternatives, +The <option>-XEmptyCase</option> flag enables +case expressions, or lambda-case expressions, that have no alternatives, thus: <programlisting> case e of { } -- No alternatives @@ -1692,7 +1707,7 @@ has no non-bottom values. For example: f :: Void -> Int f x = case x of { } </programlisting> -With dependently-typed features it is more useful +With dependently-typed features it is more useful (see <ulink url="http://hackage.haskell.org/trac/ghc/ticket/2431">Trac</ulink>). For example, consider these two candidate definitions of <literal>absurd</literal>: <programlisting> @@ -1704,7 +1719,7 @@ absurd x = error "absurd" -- (A) absurd x = case x of {} -- (B) </programlisting> We much prefer (B). Why? Because GHC can figure out that <literal>(True :~: False)</literal> -is an empty type. So (B) has no partiality and GHC should be able to compile with +is an empty type. So (B) has no partiality and GHC should be able to compile with <option>-fwarn-incomplete-patterns</option>. (Though the pattern match checking is not yet clever enough to do that. On the other hand (A) looks dangerous, and GHC doesn't check to make @@ -2284,25 +2299,10 @@ to be written infix, very much like expressions. More specifically: </para></listitem> <listitem><para> Types, and class constraints, can be written infix. For example - <screen> - x :: Int :*: Bool - f :: (a :=: b) => a -> b - </screen> - </para></listitem> -<listitem><para> - A type variable can be an (unqualified) operator e.g. <literal>+</literal>. - The lexical syntax is the same as that for variable operators, excluding "(.)", - "(!)", and "(*)". In a binding position, the operator must be - parenthesised. For example: -<programlisting> - type T (+) = Int + Int - f :: T Either - f = Left 3 - - liftA2 :: Arrow (~>) - => (a -> b -> c) -> (e ~> a) -> (e ~> b) -> (e ~> c) - liftA2 = ... -</programlisting> +<screen> + x :: Int :*: Bool + f :: (a :=: b) => a -> b +</screen> </para></listitem> <listitem><para> Back-quotes work @@ -2328,6 +2328,56 @@ to be written infix, very much like expressions. More specifically: </para> </sect2> +<sect2 id="type-operators"> +<title>Type operators</title> +<para> +In types, an operator symbol like <literal>(+)</literal> is normally treated as a type +<emphasis>variable</emphasis>, just like <literal>a</literal>. Thus in Haskell 98 you can say +<programlisting> +type T (+) = ((+), (+)) +-- Just like: type T a = (a,a) + +f :: T Int -> Int +f (x,y)= x +</programlisting> +As you can see, using operators in this way is not very useful, and Haskell 98 does not even +allow you to write them infix. +</para> +<para> +The language <option>-XTypeOperators</option> changes this behaviour: +<itemizedlist> +<listitem><para> +Operator symbols become type <emphasis>constructors</emphasis> rather than +type <emphasis>variables</emphasis>. +</para></listitem> +<listitem><para> +Operator symbols in types can be written infix, both in definitions and uses. +for example: +<programlisting> +data a + b = Plus a b +type Foo = Int + Bool +</programlisting> +</para></listitem> +<listitem><para> +There is now some potential ambiguity in import and export lists; for example +if you write <literal>import M( (+) )</literal> do you mean the +<emphasis>function</emphasis> <literal>(+)</literal> or the +<emphasis>type constructor</emphasis> <literal>(+)</literal>? +The default is the former, but GHC allows you to specify the latter +by preceding it with the keyword <literal>type</literal>, thus: +<programlisting> +import M( type (+) ) +</programlisting> +</para></listitem> +<listitem><para> +The fixity of a type operator may be set using the usual fixity declarations +but, as in <xref linkend="infix-tycons"/>, the function and type constructor share +a single fixity. +</para></listitem> +</itemizedlist> +</para> +</sect2> + <sect2 id="type-synonyms"> <title>Liberalised type synonyms</title> @@ -3086,12 +3136,11 @@ selectors. Here is the example of that section, in GADT-style syntax: <programlisting> data Counter a where - NewCounter { _this :: self - , _inc :: self -> self - , _display :: self -> IO () - , tag :: a - } - :: Counter a + NewCounter :: { _this :: self + , _inc :: self -> self + , _display :: self -> IO () + , tag :: a + } -> Counter a </programlisting> As before, only one selector function is generated here, that for <literal>tag</literal>. Nevertheless, you can still use all the field names in pattern matching and record construction. @@ -3105,7 +3154,7 @@ So GHC implements the following design: a data constructor declared in a GADT-st declaration is displayed infix by <literal>Show</literal> iff (a) it is an operator symbol, (b) it has two arguments, (c) it has a programmer-supplied fixity declaration. For example <programlisting> - infix 6 (:--:) + infix 6 (:--:) data T a where (:--:) :: Int -> Bool -> T Int </programlisting> @@ -3203,17 +3252,17 @@ As mentioned in <xref linkend="gadt-style"/>, record syntax is supported. For example: <programlisting> data Term a where - Lit { val :: Int } :: Term Int - Succ { num :: Term Int } :: Term Int - Pred { num :: Term Int } :: Term Int - IsZero { arg :: Term Int } :: Term Bool - Pair { arg1 :: Term a - , arg2 :: Term b - } :: Term (a,b) - If { cnd :: Term Bool - , tru :: Term a - , fls :: Term a - } :: Term a + Lit :: { val :: Int } -> Term Int + Succ :: { num :: Term Int } -> Term Int + Pred :: { num :: Term Int } -> Term Int + IsZero :: { arg :: Term Int } -> Term Bool + Pair :: { arg1 :: Term a + , arg2 :: Term b + } -> Term (a,b) + If :: { cnd :: Term Bool + , tru :: Term a + , fls :: Term a + } -> Term a </programlisting> However, for GADTs there is the following additional constraint: every constructor that has a field <literal>f</literal> must have @@ -3389,10 +3438,13 @@ modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> re </para> <para>Since GHC 7.8.1, <literal>Typeable</literal> is kind-polymorphic (see <xref linkend="kind-polymorphism"/>) and can be derived for any datatype and -type class. Instances for datatypes can be derived by attaching a +type class. Instances for datatypes can be derived by attaching a <literal>deriving Typeable</literal> clause to the datatype declaration, or by using standalone deriving (see <xref linkend="stand-alone-deriving"/>). Instances for type classes can only be derived using standalone deriving. +For data families, <literal>Typeable</literal> should only be derived for the +uninstantiated family type; each instance will then automatically have a +<literal>Typeable</literal> instance too. See also <xref linkend="auto-derive-typeable"/>. </para> <para> @@ -3434,7 +3486,9 @@ can be mentioned in the <literal>deriving</literal> clause. <para> The flag <option>-XAutoDeriveTypeable</option> triggers the generation of derived <literal>Typeable</literal> instances for every datatype and type -class declaration in the module it is used. This flag implies +class declaration in the module it is used. It will also generate +<literal>Typeable</literal> instances for any promoted data constructors +(<xref linkend="promotion"/>). This flag implies <option>-XDeriveDataTypeable</option> (<xref linkend="deriving-typeable"/>). </para> @@ -3471,7 +3525,7 @@ dictionary, only slower! </para> -<sect3> <title> Generalising the deriving clause </title> +<sect3 id="generalized-newtype-deriving"> <title> Generalising the deriving clause </title> <para> GHC now permits such instances to be derived instead, using the flag <option>-XGeneralizedNewtypeDeriving</option>, @@ -3592,6 +3646,8 @@ where derive these classes for a newtype, but it happens in the usual way, not via this new mechanism. </para></listitem> +<listitem><para> + The role of the last parameter of each of the <literal>ci</literal> is <emphasis>not</emphasis> <literal>N</literal>. (See <xref linkend="roles"/>.)</para></listitem> </itemizedlist> Then, for each <literal>ci</literal>, the derived instance declaration is: @@ -3809,7 +3865,7 @@ globally configurable settings in a program. For example, assumeRH :: a -> a -- Deterministic version of the Miller test - -- correctness depends on the generalized Riemann hypothesis + -- correctness depends on the generalized Riemann hypothesis isPrime :: RiemannHypothesis => Integer -> Bool isPrime n = assumeRH (...) </programlisting> @@ -4186,7 +4242,7 @@ including both declarations (A) and (B), say); an error is only reported if a particular constraint matches more than one. </para></listitem> </itemizedlist> -See also <xref linkend="instance-overlap"/> for flags that loosen the +See also <xref linkend="instance-overlap"/> for flags that loosen the instance resolution rules. </para> @@ -4416,7 +4472,7 @@ with <option>-fcontext-stack=</option><emphasis>N</emphasis>. <title>Overlapping instances</title> <para> -In general, as discussed in <xref linkend="instance-resolution"/>, +In general, as discussed in <xref linkend="instance-resolution"/>, <emphasis>GHC requires that it be unambiguous which instance declaration should be used to resolve a type-class constraint</emphasis>. This behaviour @@ -4431,7 +4487,7 @@ an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file- <para> The <option>-XOverlappingInstances</option> flag instructs GHC to loosen the instance resolution described in <xref linkend="instance-resolution"/>, by -allowing more than one instance to match, <emphasis>provided there is a most specific one</emphasis>. +allowing more than one instance to match, <emphasis>provided there is a most specific one</emphasis>. For example, consider <programlisting> instance context1 => C Int a where ... -- (A) @@ -4444,9 +4500,9 @@ The constraint <literal>C Int [Int]</literal> matches instances (A), most-specific match, the program is rejected. </para> <para> -An instance declaration is <emphasis>more specific</emphasis> than another iff +An instance declaration is <emphasis>more specific</emphasis> than another iff the head of former is a substitution instance of the latter. For example -(D) is "more specific" than (C) because you can get from (C) to (D) by +(D) is "more specific" than (C) because you can get from (C) to (D) by substituting <literal>a:=Int</literal>. </para> <para> @@ -4609,7 +4665,7 @@ instance C a => C (T a) where xs :: [b] xs = [x,x,x] </programlisting> -Provided that you also specify <option>-XScopedTypeVariables</option> +Provided that you also specify <option>-XScopedTypeVariables</option> (<xref linkend="scoped-type-variables"/>), the <literal>forall b</literal> scopes over the definition of <literal>foo</literal>, and in particular over the type signature for <literal>xs</literal>. @@ -4703,7 +4759,7 @@ constructing lists. In Haskell, the list notation can be be used in the following seven ways: <programlisting> -[] -- Empty list +[] -- Empty list [x] -- x : [] [x,y,z] -- x : y : z : [] [x .. ] -- enumFrom x @@ -4738,7 +4794,7 @@ listing gives a few examples:</para> ['a' .. 'z'] :: Text </programlisting> <para> -List patterns are also overloaded. When the <option>OverloadedLists</option> +List patterns are also overloaded. When the <option>OverloadedLists</option> extension is turned on, these definitions are desugared as follows <programlisting> f [] = ... -- f (toList -> []) = ... @@ -4752,7 +4808,7 @@ g [x,y,z] = ... -- g (toList -> [x,y,z]) = ... <para>In the above desugarings, the functions <literal>toList</literal>, <literal>fromList</literal> and <literal>fromListN</literal> are all -methods of +methods of the <literal>IsList</literal> class, which is itself exported from the <literal>GHC.Exts</literal> module. The type class is defined as follows:</para> @@ -4769,18 +4825,18 @@ class IsList l where </programlisting> <para>The <literal>FromList</literal> class and its methods are intended to be -used in conjunction with the <option>OverloadedLists</option> extension. +used in conjunction with the <option>OverloadedLists</option> extension. <itemizedlist> <listitem> <para> The type function <literal>Item</literal> returns the type of items of the structure <literal>l</literal>. </para></listitem> -<listitem><para> -The function <literal>fromList</literal> +<listitem><para> +The function <literal>fromList</literal> constructs the structure <literal>l</literal> from the given list of -<literal>Item l</literal>. +<literal>Item l</literal>. </para></listitem> -<listitem><para> +<listitem><para> The function <literal>fromListN</literal> takes the input list's length as a hint. Its behaviour should be equivalent to <literal>fromList</literal>. The hint can be used for more efficient @@ -4789,8 +4845,8 @@ construction of the structure <literal>l</literal> compared to list's length the behaviour of <literal>fromListN</literal> is not specified. </para></listitem> -<listitem><para> -The function <literal>toList</literal> should be +<listitem><para> +The function <literal>toList</literal> should be the inverse of <literal>fromList</literal>. </para></listitem> </itemizedlist> @@ -4812,12 +4868,12 @@ instance (Ord a) => FromList (Set a) where instance (Ord k) => FromList (Map k v) where type Item (Map k v) = (k,v) - fromList = Map.fromList + fromList = Map.fromList toList = Map.toList instance FromList (IntMap v) where type Item (IntMap v) = (Int,v) - fromList = IntMap.fromList + fromList = IntMap.fromList toList = IntMap.toList instance FromList Text where @@ -4841,7 +4897,7 @@ instance FromList (Vector a) where GHC uses the <literal>fromList</literal> (etc) methods from module <literal>GHC.Exts</literal>. You do not need to import <literal>GHC.Exts</literal> for this to happen. </para> -<para> However if you use <option>-XRebindableSyntax</option>, then +<para> However if you use <option>-XRebindableSyntax</option>, then GHC instead uses whatever is in scope with the names of <literal>toList</literal>, <literal>fromList</literal> and <literal>fromListN</literal>. That is, these functions are rebindable; @@ -4883,7 +4939,7 @@ representation).</para> <title>Type families</title> <para> - <firstterm>Indexed type families</firstterm> are a new GHC extension to + <firstterm>Indexed type families</firstterm> form an extension to facilitate type-level programming. Type families are a generalisation of <firstterm>associated data types</firstterm> @@ -4926,11 +4982,11 @@ representation).</para> indices. </para> <para> - Indexed type families come in two flavours: <firstterm>data - families</firstterm> and <firstterm>type synonym - families</firstterm>. They are the indexed family variants of algebraic - data types and type synonyms, respectively. The instances of data families - can be data types and newtypes. + Indexed type families come in three flavours: <firstterm>data + families</firstterm>, <firstterm>open type synonym families</firstterm>, and + <firstterm>closed type synonym families</firstterm>. They are the indexed + family variants of algebraic data types and type synonyms, respectively. The + instances of data families can be data types and newtypes. </para> <para> Type families are enabled by the flag <option>-XTypeFamilies</option>. @@ -5038,7 +5094,7 @@ data instance G [a] b where </para> <para> - Even if type families are defined as toplevel declarations, functions + Even if data families are defined as toplevel declarations, functions that perform different computations for different family instances may still need to be defined as methods of type classes. In particular, the following is not possible: @@ -5084,22 +5140,24 @@ instance Foo Char where <title>Synonym families</title> <para> - Type families appear in two flavours: (1) they can be defined on the - toplevel or (2) they can appear inside type classes (in which case they - are known as associated type synonyms). The former is the more general - variant, as it lacks the requirement for the type-indexes to coincide with - the class parameters. However, the latter can lead to more clearly - structured code and compiler warnings if some type instances were - - possibly accidentally - omitted. In the following, we always discuss the - general toplevel form first and then cover the additional constraints - placed on associated types. + Type families appear in three flavours: (1) they can be defined as open + families on the toplevel, (2) they can be defined as closed families on + the toplevel, or (3) they can appear inside type classes (in which case + they are known as associated type synonyms). Toplevel families are more + general, as they lack the requirement for the type-indexes to coincide + with the class parameters. However, associated type synonyms can lead to + more clearly structured code and compiler warnings if some type instances + were - possibly accidentally - omitted. In the following, we always + discuss the general toplevel forms first and then cover the additional + constraints placed on associated types. Note that closed associated type + synonyms do not exist. </para> <sect3 id="type-family-declarations"> <title>Type family declarations</title> <para> - Indexed type families are introduced by a signature, such as + Open indexed type families are introduced by a signature, such as <programlisting> type family Elem c :: * </programlisting> @@ -5135,12 +5193,7 @@ F Bool -- WRONG: unsaturated application <sect3 id="type-instance-declarations"> <title>Type instance declarations</title> <para> - There are two forms of type family instance declaration: unbranched and - branched. Branched instances list any number of alternatives, to be - checked in order from top to bottom, similarly to normal function - declarations. Unbranched instances supply only one left-hand side. - - Unbranched instance declarations of type families are very similar to + Instance declarations of type families are very similar to standard type synonym declarations. The only two differences are that the keyword <literal>type</literal> is followed by <literal>instance</literal> and that some or all of the type arguments @@ -5156,45 +5209,55 @@ type instance Elem [e] = e </para> <para> - Branched instance declarations, on the other hand, allow many different - left-hand-side type patterns. These patterns are tried in order, from - top to bottom, when simplifying a type family application. A branched instance - declaration is introduced by <literal>type instance where</literal>. For example: + Type family instance declarations are only legitimate when an + appropriate family declaration is in scope - just like class instances + require the class declaration to be visible. Moreover, each instance + declaration has to conform to the kind determined by its family + declaration, and the number of type parameters in an instance + declaration must match the number of type parameters in the family + declaration. Finally, the right-hand side of a type instance must be a + monotype (i.e., it may not include foralls) and after the expansion of + all saturated vanilla type synonyms, no synonyms, except family synonyms + may remain. + </para> + </sect3> + + <sect3 id="closed-type-families"> + <title>Closed type families</title> + <para> + A type family can also be declared with a <literal>where</literal> clause, + defining the full set of equations for that family. For example: <programlisting> -type instance where +type family F a where F Int = Double F Bool = Char F a = String </programlisting> - In this example, we declare an instance for <literal>F</literal> such - that <literal>F Int</literal> simplifies to <literal>Double</literal>, - <literal>F Bool</literal> simplifies to <literal>Char</literal>, and for - any other type <literal>a</literal> that is known not to be - <literal>Int</literal> or <literal>Bool</literal>, <literal>F - a</literal> simplifies to <literal>String</literal>. Note that GHC must - be sure that <literal>a</literal> cannot unify with - <literal>Int</literal> or <literal>Bool</literal> in that last case; if - a programmer specifies just <literal>F a</literal> in their code, GHC will - not be able to simplify the type. After all, <literal>a</literal> might later - be instantiated with <literal>Int</literal>. + A closed type family's equations are tried in order, from top to bottom, + when simplifying a type family application. In this example, we declare + an instance for <literal>F</literal> such that <literal>F Int</literal> + simplifies to <literal>Double</literal>, <literal>F Bool</literal> + simplifies to <literal>Char</literal>, and for any other type + <literal>a</literal> that is known not to be <literal>Int</literal> or + <literal>Bool</literal>, <literal>F a</literal> simplifies to + <literal>String</literal>. Note that GHC must be sure that + <literal>a</literal> cannot unify with <literal>Int</literal> or + <literal>Bool</literal> in that last case; if a programmer specifies + just <literal>F a</literal> in their code, GHC will not be able to + simplify the type. After all, <literal>a</literal> might later be + instantiated with <literal>Int</literal>. </para> <para> - Branched instances and unbranched instances may be mixed freely for the same - type family. + A closed type family's equations have the same restrictions as the + equations for an open type family instances. </para> + </sect3> + <sect3 id="type-family-examples"> + <title>Type family examples</title> <para> - Type family instance declarations are only legitimate when an - appropriate family declaration is in scope - just like class instances - require the class declaration to be visible. Moreover, each instance - declaration has to conform to the kind determined by its family - declaration, and the number of type parameters in an instance - declaration must match the number of type parameters in the family - declaration. Finally, the right-hand side of a type instance must be a - monotype (i.e., it may not include foralls) and after the expansion of - all saturated vanilla type synonyms, no synonyms, except family synonyms - may remain. Here are some examples of admissible and illegal type +Here are some examples of admissible and illegal type instances: <programlisting> type family F a :: * @@ -5203,13 +5266,11 @@ type instance F String = Char -- OK! type instance F (F a) = a -- WRONG: type parameter mentions a type family type instance F (forall a. (a, b)) = b -- WRONG: a forall type appears in a type parameter type instance F Float = forall a.a -- WRONG: right-hand side may not be a forall type -type instance where -- OK! - F (Maybe Int) = Int - F (Maybe Bool) = Bool - F (Maybe a) = String -type instance where -- WRONG: conflicts with earlier instances (see below) - F Int = Float - F a = [a] +type family H a where -- OK! + H Int = Int + H Bool = Bool + H a = String +type instance H Char = Char -- WRONG: cannot have instances of closed family type family G a b :: * -> * type instance G Int = (,) -- WRONG: must be two type parameters @@ -5218,35 +5279,83 @@ type instance G Int Char Float = Double -- WRONG: must be two type parameters </para> </sect3> <sect3 id="type-family-overlap"> - <title>Overlap of type synonym instances</title> + <title>Compatibility and apartness of type family equations</title> <para> - The unbranched instance declarations of a type family used in a single - program may only overlap if the right-hand sides of the overlapping - instances coincide for the overlapping types. More formally, two - instance declarations overlap if there is a substitution that makes - the left-hand sides of the instances syntactically the same. Whenever - that is the case, if the instances are unbranched, the right-hand - sides of the instances must also be syntactically equal under the same - substitution. This condition is independent of whether the type family - is associated or not, and it is not only a matter of consistency, but - one of type safety. Branched instances are not permitted to overlap - with any other instances, branched or unbranched. + There must be some restrictions on the equations of type families, lest + we define an ambiguous rewrite system. So, equations of open type families + are restricted to be <firstterm>compatible</firstterm>. Two type patterns + are compatible if +<orderedlist> +<listitem><para>all corresponding types in the patterns are <firstterm>apart</firstterm>, or</para></listitem> +<listitem><para>the two patterns unify producing a substitution, and the right-hand sides are equal under that substitution.</para></listitem> +</orderedlist> + Two types are considered <firstterm>apart</firstterm> if, for all possible + substitutions, the types cannot reduce to a common reduct. </para> + <para> - Here are two example to illustrate the condition under which overlap - is permitted. + The first clause of "compatible" is the more straightforward one. It says + that the patterns of two distinct type family instances cannot overlap. + For example, the following is disallowed: +<programlisting> +type instance F Int = Bool +type instance F Int = Char +</programlisting> + The second clause is a little more interesting. It says that two + overlapping type family instances are allowed if the right-hand + sides coincide in the region of overlap. Some examples help here: <programlisting> type instance F (a, Int) = [a] type instance F (Int, b) = [b] -- overlap permitted type instance G (a, Int) = [a] type instance G (Char, a) = [a] -- ILLEGAL overlap, as [Char] /= [Int] - -type instance H Int = Int -type instance where -- ILLEGAL overlap, as branched instances may not overlap - H a = a </programlisting> - </para> + Note that this compatibility condition is independent of whether the type family + is associated or not, and it is not only a matter of consistency, but + one of type safety. </para> + + <para> + The definition for "compatible" uses a notion of "apart", whose definition + in turn relies on type family reduction. This condition of "apartness", as + stated, is impossible to check, so we use this conservative approximation: + two types are considered to be apart when the two types cannot be unified, + even by a potentially infinite unifier. Allowing the unifier to be infinite + disallows the following pair of instances: +<programlisting> +type instance H x x = Int +type instance H [x] x = Bool +</programlisting> + The type patterns in this pair equal if <literal>x</literal> is replaced + by an infinite nesting of lists. Rejecting instances such as these is + necessary for type soundness. + </para> + + <para> + Compatibility also affects closed type families. When simplifying an + application of a closed type family, GHC will select an equation only + when it is sure that no incompatible previous equation will ever apply. + Here are some examples: +<programlisting> +type family F a where + F Int = Bool + F a = Char + +type family G a where + G Int = Int + G a = a +</programlisting> + In the definition for <literal>F</literal>, the two equations are + incompatible -- their patterns are not apart, and yet their + right-hand sides do not coincide. Thus, before GHC selects the + second equation, it must be sure that the first can never apply. So, + the type <literal>F a</literal> does not simplify; only a type such + as <literal>F Double</literal> will simplify to + <literal>Char</literal>. In <literal>G</literal>, on the other hand, + the two equations are compatible. Thus, GHC can ignore the first + equation when looking at the second. So, <literal>G a</literal> will + simplify to <literal>a</literal>.</para> + <para> However see <xref linkend="ghci-decls"/> for the overlap rules in GHCi.</para> </sect3> @@ -5377,10 +5486,6 @@ instance GMapKey Flob where the free indexed parameter is of a kind with a finite number of alternatives (unlike <literal>*</literal>). </para> - - <para> - Branched associated type instances are not currently supported. - </para> </sect3> <sect3 id="assoc-decl-defs"> @@ -5633,7 +5738,7 @@ instance Show v => Show (GMap () v) where ... <title>Kind polymorphism</title> <para> This section describes <emphasis>kind polymorphism</emphasis>, and extension -enabled by <option>-XPolyKinds</option>. +enabled by <option>-XPolyKinds</option>. It is described in more detail in the paper <ulink url="http://dreixel.net/research/pdf/ghp.pdf">Giving Haskell a Promotion</ulink>, which appeared at TLDI 2012. @@ -5679,27 +5784,53 @@ Note that the datatype <literal>Proxy</literal> has kind <para> Generally speaking, with <option>-XPolyKinds</option>, GHC will infer a polymorphic -kind for un-decorated whenever possible. For example: +kind for un-decorated declarations, whenever possible. For example: <programlisting> data T m a = MkT (m a) -- GHC infers kind T :: forall k. (k -> *) -> k -> * </programlisting> -Just as in the world of terms, you can restrict polymorphism using a signature +Just as in the world of terms, you can restrict polymorphism using a +kind signature (sometimes called a kind annotation) (<option>-XPolyKinds</option> implies <option>-XKindSignatures</option>): <programlisting> data T m (a :: *) = MkT (m a) -- GHC now infers kind T :: (* -> *) -> * -> * </programlisting> -There is no "forall" for kind variables. Instead, you can simply mention a kind -variable in a kind signature, thus: +There is no "forall" for kind variables. Instead, when binding a type variable, +you can simply mention a kind +variable in a kind annotation for that type-variable binding, thus: <programlisting> data T (m :: k -> *) a = MkT (m a) -- GHC now infers kind T :: forall k. (k -> *) -> k -> * </programlisting> +The kind "forall" is placed +just outside the outermost type-variable binding whose kind annotation mentions +the kind variable. For example +<programlisting> +f1 :: (forall a m. m a -> Int) -> Int + -- f1 :: forall (k:BOX). + -- (forall (a:k) (m:k->*). m a -> Int) + -- -> Int + +f2 :: (forall (a::k) m. m a -> Int) -> Int + -- f2 :: (forall (k:BOX) (a:k) (m:k->*). m a -> Int) + -- -> Int +</programlisting> +Here in <literal>f1</literal> there is no kind annotation mentioning the polymorphic +kind variable, so <literal>k</literal> is generalised at the top +level of the signature for <literal>f1</literal>, +making the signature for <literal>f1</literal> is as polymorphic as possible. +But in the case of of <literal>f2</literal> we give a kind annotation in the <literal>forall (a:k)</literal> +binding, and GHC therefore puts the kind <literal>forall</literal> right there too. +</para> +<para> +(Note: These rules are a bit indirect and clumsy. Perhaps GHC should allow explicit kind quantification. +But the implicit quantification (e.g. in the declaration for data type T above) is certainly +very convenient, and it is not clear what the syntax for explicit quantification should be.) </para> </sect2> -<sect2> <title>Polymorphic kind recursion and complete kind signatures</title> +<sect2 id="complete-kind-signatures"> <title>Polymorphic kind recursion and complete kind signatures</title> <para> Just as in type inference, kind inference for recursive types can only use <emphasis>monomorphic</emphasis> recursion. @@ -5709,7 +5840,7 @@ data T m a = MkT (m a) (T Maybe (m a)) -- GHC infers kind T :: (* -> *) -> * -> * </programlisting> The recursive use of <literal>T</literal> forced the second argument to have kind <literal>*</literal>. -However, just as in type inference, you can achieve polymorphic recursion by giving a +However, just as in type inference, you can achieve polymorphic recursion by giving a <emphasis>complete kind signature</emphasis> for <literal>T</literal>. The way to give a complete kind signature for a data type is to use a GADT-style declaration with an explicit kind signature thus: @@ -5744,14 +5875,21 @@ you must use GADT syntax. </para></listitem> <listitem><para> -A type or data family declaration <emphasis>always</emphasis> have a +An open type or data family declaration <emphasis>always</emphasis> has a complete user-specified kind signature; no "<literal>::</literal>" is required: <programlisting> data family D1 a -- D1 :: * -> * data family D2 (a :: k) -- D2 :: forall k. k -> * data family D3 (a :: k) :: * -- D3 :: forall k. k -> * type family S1 a :: k -> * -- S1 :: forall k. * -> k -> * + +class C a where -- C :: k -> Constraint + type AT a b -- AT :: k -> * -> * </programlisting> +In the last example, the variable <literal>a</literal> has an implicit kind +variable annotation from the class declaration. It keeps its polymorphic kind +in the associated type declaration. The variable <literal>b</literal>, however, +gets defaulted to <literal>*</literal>. </para></listitem> </itemizedlist> In a complete user-specified kind signature, any un-decorated type variable to the @@ -5760,6 +5898,39 @@ If you want kind polymorphism, specify a kind variable. </para> </sect2> + +<sect2><title>Kind inference in closed type families</title> + +<para>Although all open type families are considered to have a complete +user-specified kind signature, we can relax this condition for closed type +families, where we have equations on which to perform kind inference. GHC will +infer a kind for any type variable in a closed type family when that kind is +never used in pattern-matching. If you want a kind variable to be used in +pattern-matching, you must declare it explicitly. +</para> + +<para> +Here are some examples (assuming <literal>-XDataKinds</literal> is enabled): +<programlisting> +type family Not a where -- Not :: Bool -> Bool + Not False = True + Not True = False + +type family F a where -- ERROR: requires pattern-matching on a kind variable + F Int = Bool + F Maybe = Char + +type family G (a :: k) where -- G :: k -> * + G Int = Bool + G Maybe = Char + +type family SafeHead where -- SafeHead :: [k] -> Maybe k + SafeHead '[] = Nothing -- note that k is not required for pattern-matching + SafeHead (h ': t) = Just h +</programlisting> +</para> + +</sect2> </sect1> <sect1 id="promotion"> @@ -5825,7 +5996,7 @@ data Nat = Ze | Su Nat data List a = Nil | Cons a (List a) data Pair a b = Pair a b - + data Sum a b = L a | R b </programlisting> give rise to the following kinds and type constructors: @@ -5890,7 +6061,7 @@ type T1 = P -- 1 type T2 = 'P -- promoted 2 </programlisting> Note that promoted datatypes give rise to named kinds. Since these can never be -ambiguous, we do not allow quotes in kind names. +ambiguous, we do not allow quotes in kind names. </para> <para>Just as in the case of Template Haskell (<xref linkend="th-syntax"/>), there is no way to quote a data constructor or type constructor whose second character @@ -5968,7 +6139,7 @@ data Ex :: * where MkEx :: forall a. a -> Ex </programlisting> Both the type <literal>Ex</literal> and the data constructor <literal>MkEx</literal> -get promoted, with the polymorphic kind <literal>'MkEx :: forall k. k -> Ex</literal>. +get promoted, with the polymorphic kind <literal>'MkEx :: forall k. k -> Ex</literal>. Somewhat surprisingly, you can write a type family to extract the member of a type-level existential: <programlisting> @@ -5977,7 +6148,7 @@ type instance UnEx (MkEx x) = x </programlisting> At first blush, <literal>UnEx</literal> seems poorly-kinded. The return kind <literal>k</literal> is not mentioned in the arguments, and thus it would seem -that an instance would have to return a member of <literal>k</literal> +that an instance would have to return a member of <literal>k</literal> <emphasis>for any</emphasis> <literal>k</literal>. However, this is not the case. The type family <literal>UnEx</literal> is a kind-indexed type family. The return kind <literal>k</literal> is an implicit parameter to <literal>UnEx</literal>. @@ -6623,7 +6794,7 @@ field type signatures.</para> </listitem> <listitem> <para> As the type of an implicit parameter </para> </listitem> <listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem> </itemizedlist> -The <option>-XRankNTypes</option> option is also required for any +The <option>-XRankNTypes</option> option is also required for any type with a <literal>forall</literal> or context to the right of an arrow (e.g. <literal>f :: Int -> forall a. a->a</literal>, or <literal>g :: Int -> Ord a => a -> a</literal>). Such types are technically rank 1, but @@ -6633,7 +6804,7 @@ are clearly not Haskell-98, and an extra flag did not seem worth the bother. <para> The obselete language options <option>-XPolymorphicComponents</option> and <option>-XRank2Types</option> are synonyms for <option>-XRankNTypes</option>. They used to specify finer distinctions that -GHC no longer makes. (They should really elicit a deprecation warning, but they don't, purely +GHC no longer makes. (They should really elicit a deprecation warning, but they don't, purely to avoid the need to library authors to change their old flags specifciations.) </para> @@ -7181,8 +7352,24 @@ scope over the methods defined in the <literal>where</literal> part. For exampl </sect2> +<sect2> +<title>Bindings and generalisation</title> -<sect2 id="typing-binds"> +<sect3 id="monomorphism"> +<title>Switching off the dreaded Monomorphism Restriction</title> + <indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm> + +<para>Haskell's monomorphism restriction (see +<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section +4.5.5</ulink> +of the Haskell Report) +can be completely switched off by +<option>-XNoMonomorphismRestriction</option>. +</para> +</sect3> + + +<sect3 id="typing-binds"> <title>Generalised typing of mutually recursive bindings</title> <para> @@ -7243,28 +7430,14 @@ pattern binding must have the same context. For example, this is fine: g y = (y <= y) || f True </programlisting> </para> -</sect2> - -<sect2 id="monomorphism"> -<title>Switching off the dreaded Monomorphism Restriction</title> - <indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm> - -<para>Haskell's monomorphism restriction (see -<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section -4.5.5</ulink> -of the Haskell Report) -can be completely switched off by -<option>-XNoMonomorphismRestriction</option>. -</para> -</sect2> - +</sect3> -<sect2 id="mono-local-binds"> +<sect3 id="mono-local-binds"> <title>Let-generalisation</title> <para> An ML-style language usually generalises the type of any let-bound or where-bound variable, so that it is as polymorphic as possible. -With the flag <option>-XMonoLocalBinds</option> GHC implements a slightly more conservative policy: +With the flag <option>-XMonoLocalBinds</option> GHC implements a slightly more conservative policy: <emphasis>it generalises only "closed" bindings</emphasis>. A binding is considered "closed" if either <itemizedlist> @@ -7284,15 +7457,17 @@ But <literal>k</literal> is not closed because it mentions <literal>x</literal> Another way to think of it is this: all closed bindings <literal>could</literal> be defined at top level. (In the example, we could move <literal>h</literal> to top level.) </para><para> -All of this applies only to bindings that lack an explicit type signature, so that GHC has to +All of this applies only to bindings that lack an explicit type signature, so that GHC has to infer its type. If you supply a type signature, then that fixes type of the binding, end of story. </para><para> -The rationale for this more conservative strategy is given in -<ulink url="http://research.microsoft.com/~simonpj/papers/constraints/index.htm">the papers</ulink> "Let should not be generalised" and "Modular type inference with local assumptions". +The rationale for this more conservative strategy is given in +<ulink url="http://research.microsoft.com/~simonpj/papers/constraints/index.htm">the papers</ulink> "Let should not be generalised" and "Modular type inference with local assumptions", and +a related <ulink url="http://hackage.haskell.org/trac/ghc/blog/LetGeneralisationInGhc7">blog post</ulink>. </para><para> The flag <option>-XMonoLocalBinds</option> is implied by <option>-XTypeFamilies</option> and <option>-XGADTs</option>. You can switch it off again with <option>-XNoMonoLocalBinds</option> but type inference becomes less predicatable if you do so. (Read the papers!) </para> +</sect3> </sect2> <sect2 id="type-holes"> @@ -7312,7 +7487,7 @@ the term you're about to write. </para> <para> -This extension allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>", +This extension allows special placeholders, written with a leading underscore (e.g. "<literal>_</literal>", "<literal>_foo</literal>", "<literal>_bar</literal>"), to be used as an expression. During compilation these holes will generate an error message describing what type is expected there, information about the origin of any free type variables, and a list of local bindings @@ -7470,7 +7645,7 @@ Prelude> fst (True, 1 == 'a') In the expression: 1 == 'a' In the first argument of `fst', namely `(True, 1 == 'a')' </programlisting> -Otherwise, in the common case of a simple type error such as +Otherwise, in the common case of a simple type error such as typing <literal>reverse True</literal> at the prompt, you would get a warning and then an immediately-following type error when the expression is evaluated. </para> @@ -7590,7 +7765,7 @@ Wiki page</ulink>. <itemizedlist> <listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>. Similarly <literal>'C</literal> has type <literal>Name</literal> and names the data constructor <literal>C</literal>. - In general <literal>'</literal><replaceable>thing</replaceable> + In general <literal>'</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in an expression context.</para> <para>A name whose second character is a single quote (sadly) cannot be quoted in this way, @@ -10534,7 +10709,228 @@ Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh. </sect1> +<sect1 id="roles"> +<title>Roles +<indexterm><primary>roles</primary></indexterm> +</title> + +<para> +Using <option>-XGeneralizedNewtypeDeriving</option> (<xref +linkend="generalized-newtype-deriving" />), a programmer can take existing +instances of classes and "lift" these into instances of that class for a +newtype. However, this is not always safe. For example, consider the following: +</para> + +<programlisting> + newtype Age = MkAge { unAge :: Int } + + type family Inspect x + type instance Inspect Age = Int + type instance Inspect Int = Bool + class BadIdea a where + bad :: a -> Inspect a + + instance BadIdea Int where + bad = (> 0) + + deriving instance BadIdea Age -- not allowed! +</programlisting> + +<para> +If the derived instance were allowed, what would the type of its method +<literal>bad</literal> be? It would seem to be <literal>Age -> Inspect +Age</literal>, which is equivalent to <literal>Age -> Int</literal>, according +to the type family <literal>Inspect</literal>. Yet, if we simply adapt the +implementation from the instance for <literal>Int</literal>, the implementation +for <literal>bad</literal> produces a <literal>Bool</literal>, and we have trouble. +</para> + +<para> +The way to identify such situations is to have <emphasis>roles</emphasis> assigned +to type variables of datatypes, classes, and type synonyms.</para> + +<para> +Roles as implemented in GHC are a from a simplified version of the work +described in <ulink +url="http://www.seas.upenn.edu/~sweirich/papers/popl163af-weirich.pdf">Generative +type abstraction and type-level computation</ulink>, published at POPL 2011.</para> + +<sect2> +<title>Nominal, Representational, and Phantom</title> + +<para>The goal of the roles system is to track when two types have the same +underlying representation. In the example above, <literal>Age</literal> and +<literal>Int</literal> have the same representation. But, the corresponding +instances of <literal>BadIdea</literal> would <emphasis>not</emphasis> have +the same representation, because the types of the implementations of +<literal>bad</literal> would be different.</para> + +<para>Suppose we have two uses of a type constructor, each applied to the same +parameters except for one difference. (For example, <literal>T Age Bool +c</literal> and <literal>T Int Bool c</literal> for some type +<literal>T</literal>.) The role of a type parameter says what we need to +know about the two differing type arguments in order to know that the two +outer types have the same representation (in the example, what must be true +about <literal>Age</literal> and <literal>Int</literal> in order to show that +<literal>T Age Bool c</literal> has the same representation as <literal> +T Int Bool c</literal>).</para> + +<para>GHC supports three different roles for type parameters: nominal, +representational, and phantom. If a type parameter has a nominal (N) role, +then the two types that differ must not actually differ at all: they must be +identical (after type family reduction). If a type parameter has a +representational (R) role, then the two types must have the same +representation. (If <literal>T</literal>'s first parameter's role is R, then +<literal>T Age Bool c</literal> and <literal>T Int Bool c</literal> would have +the same representation, because <literal>Age</literal> and <literal>Int</literal> +have the same representation.) If a type parameter has a phantom (P) role, +then we need no further information.</para> + +<para>Here are some examples:</para> + +<programlisting> + data Simple a = MkSimple a -- a has role R + + type family F + type instance F Int = Bool + type instance F Age = Char + + data Complex a = MkComplex (F a) -- a has role N + + data Phant a = MkPhant Bool -- a has role P +</programlisting> + +<para>The type <literal>Simple</literal> has its parameter at role R, which is +generally the most common case. <literal>Simple Age</literal> would have the same +representation as <literal>Simple Int</literal>. The type <literal>Complex</literal>, +on the other hand, has its parameter at role N, because <literal>Simple Age</literal> +and <literal>Simple Int</literal> are <emphasis>not</emphasis> the same. Lastly, +<literal>Phant Age</literal> and <literal>Phant Bool</literal> have the same +representation, even though <literal>Age</literal> and <literal>Bool</literal> +are unrelated.</para> + +</sect2> + +<sect2> +<title>Role inference</title> + +<para> +What role should a given type parameter should have? GHC performs role +inference to determine the correct role for every parameter. It starts with a +few base facts: <literal>(->)</literal> has two R parameters; +<literal>(~)</literal> has two N parameters; all type families' parameters are +N; and all GADT-like parameters are N. Then, these facts are propagated to all +places where these types are used. By defaulting parameters to role P, any +parameters unused in the right-hand side (or used only in other types in P +positions) will be P. Whenever a parameter is used in an R position (that is, +used as a type argument to a constructor whose corresponding variable is at +role R), we raise its role from P to R. Similarly, when a parameter is used in +an N position, its role is upgraded to N. We never downgrade a role from N to +P or R, or from R to P. In this way, we infer the most-general role for each +parameter. +</para> + +<para>There is one particularly tricky case that should be explained:</para> + +<programlisting> + data Tricky a b = MkTricky (a b) +</programlisting> + +<para>What should <literal>Tricky</literal>'s roles be? At first blush, it would +seem that both <literal>a</literal> and <literal>b</literal> should be at role R, +since both are used in the right-hand side and neither is involved in a type family. +However, this would be wrong, as the following example shows:</para> + +<programlisting> + data Nom a = MkNom (F a) -- type family F from example above +</programlisting> + +<para>Is <literal>Tricky Nom Age</literal> representationally equal to +<literal>Tricky Nom Int</literal>? No! The former stores a <literal>Char</literal> +and the latter stores a <literal>Bool</literal>. The solution to this is +to require all parameters to type variables to have role N. Thus, GHC would +infer role R for <literal>a</literal> but role N for <literal>b</literal>.</para> + +</sect2> + +<sect2> +<title>Role annotations +<indexterm><primary>-XRoleAnnotations</primary></indexterm> +</title> + +<para> +Sometimes the programmer wants to constrain the inference process. For +example, the base library contains the following definition: +</para> + +<programlisting> + data Ptr a = Ptr Addr# +</programlisting> + +<para> +The idea is that <literal>a</literal> should really be an R parameter, but +role inference assigns it to P. This makes some level of sense: a pointer to +an <literal>Int</literal> really is representationally the same as a pointer +to a <literal>Bool</literal>. But, that's not at all how we want to use +<literal>Ptr</literal>s! So, we want to be able to say</para> + +<programlisting> + data Ptr a@R = Ptr Addr# +</programlisting> + +<para> +The <literal>@R</literal> (enabled with <option>-XRoleAnnotations</option>) annotation forces the +parameter a to be at role R, not role P. GHC then checks +the user-supplied roles to make sure they don't break any promises. It would +be bad, for example, if the user could make <literal>BadIdea</literal>'s role be R. +</para> + +<para>As another example, we can consider a type <literal>Set a</literal> that +represents a set of data, ordered according to <literal>a</literal>'s +<literal>Ord</literal> instance. While it would generally be type-safe to +consider <literal>a</literal> to be at role R, it is possible that a +<literal>newtype</literal> and its base type have +<emphasis>different</emphasis> orderings encoded in their respective +<literal>Ord</literal> instances. This would lead to misbehavior at runtime. +So, the author of the <literal>Set</literal> datatype would like its parameter +to be at role N. This would be done with a declaration</para> + +<programlisting> + data Set a@N = ... +</programlisting> + +<para>The other place where role annotations may be necessary are in +<literal>hs-boot</literal> files (<xref linkend="mutual-recursion"/>), where +the right-hand sides of definitions can be omitted. As usual, the +types/classes declared in an <literal>hs-boot</literal> file must match up +with the definitions in the <literal>hs</literal> file, including down to the +roles. The default role is R in <literal>hs-boot</literal> files, +corresponding to the common use case.</para> + +<para> +Role annotations are allowed on type variables in data, newtype, class, +and type declarations. They are not allowed on type/data family +declarations or in explicit foralls in function type signatures. +The syntax for a role annotation is an <literal>@</literal> sign followed +by one of <literal>N</literal>, <literal>R</literal>, or <literal>P</literal>, +directly following a type variable. If the type variable has an explicit +kind annotation, the role annotation goes after the kind annotation, outside +the parentheses. Here are some examples:</para> + +<programlisting> + data T1 a b@P = MkT1 a -- b is not used; annotation is fine but unnecessary + data T2 a b@P = MkT2 b -- ERROR: b is used and cannot be P + data T3 a b@N = MkT3 a -- OK: N is higher than necessary, but safe + data T4 (a :: * -> *)@N = MkT4 (a Int) -- OK, but N is higher than necessary + class C a@R b where ... -- OK + type X a@N = ... -- OK + type family F a@R -- ERROR: annotations not allowed on family declarations +</programlisting> + +</sect2> + +</sect1> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/docs/users_guide/intro.xml b/docs/users_guide/intro.xml index b21b793f73..a7cd33ac5c 100644 --- a/docs/users_guide/intro.xml +++ b/docs/users_guide/intro.xml @@ -302,7 +302,7 @@ <para>The version number of your copy of GHC can be found by invoking <literal>ghc</literal> with the - <literal>––version</literal> flag (see <xref + <literal>--version</literal> flag (see <xref linkend="options-help"/>).</para> </sect1> diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml index c6a1d089a2..3f2dd97aa5 100644 --- a/docs/users_guide/packages.xml +++ b/docs/users_guide/packages.xml @@ -13,7 +13,7 @@ Packages url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para> <para>Using a package couldn't be simpler: if you're using - <option>––make</option> or GHCi, then most of the installed packages will be + <option>--make</option> or GHCi, then most of the installed packages will be automatically available to your program without any further options. The exceptions to this rule are covered below in <xref linkend="using-packages" />.</para> @@ -147,8 +147,8 @@ exposed-modules: Network.BSD, or dynamically is controlled by the flag pair <option>-static</option>/<option>-dynamic</option>.</para> - <para>In <option>––make</option> mode - and <option>––interactive</option> mode (see + <para>In <option>--make</option> mode + and <option>--interactive</option> mode (see <xref linkend="modes" />), the compiler normally determines which packages are required by the current Haskell modules, and links only those. In batch mode @@ -961,9 +961,9 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf <varlistentry> <term> - <option>––force</option> + <option>--force</option> <indexterm><primary> - <option>––force</option> + <option>--force</option> </primary></indexterm> </term> <listitem> @@ -977,7 +977,7 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf <varlistentry> <term> - <option>––global</option><indexterm><primary><option>––global</option></primary> + <option>--global</option><indexterm><primary><option>--global</option></primary> </indexterm> </term> <listitem> @@ -991,7 +991,7 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf <varlistentry> <term> - <option>––help</option><indexterm><primary><option>––help</option></primary> + <option>--help</option><indexterm><primary><option>--help</option></primary> </indexterm> </term> <term> @@ -1005,7 +1005,7 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf <varlistentry> <term> - <option>––user</option><indexterm><primary><option>––user</option></primary> + <option>--user</option><indexterm><primary><option>--user</option></primary> </indexterm> </term> <listitem> @@ -1040,7 +1040,7 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf </indexterm> </term> <term> - <option>––version</option><indexterm><primary><option>––version</option></primary> + <option>--version</option><indexterm><primary><option>--version</option></primary> </indexterm> </term> <listitem> @@ -1115,11 +1115,11 @@ ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf it. To build one manually, the following GNU <command>ld</command> command can be used:</para> -<screen>ld -r ––whole-archive -o HSfoo.o libHSfoo.a</screen> +<screen>ld -r --whole-archive -o HSfoo.o libHSfoo.a</screen> <para>(replace - <literal>––whole-archive</literal> with - <literal>–all_load</literal> on MacOS X)</para> + <literal>--whole-archive</literal> with + <literal>-all_load</literal> on MacOS X)</para> </listitem> <listitem> <para>When building the package as shared library, GHC can be used to diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index f4019bd8cd..90489e84d2 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -693,7 +693,7 @@ $ cat foo.hspp</screen> </term> <listitem> <para>Omits the link step. This option can be used with - <option>––make</option> to avoid the automatic linking + <option>--make</option> to avoid the automatic linking that takes place if the program contains a <literal>Main</literal> module.</para> </listitem> diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml index a776382645..fdc7b2b24d 100644 --- a/docs/users_guide/profiling.xml +++ b/docs/users_guide/profiling.xml @@ -1077,7 +1077,7 @@ MAIN MAIN 102 0 0.0 0.0 100.0 1 </sect1> <sect1 id="hp2ps"> - <title><command>hp2ps</command>––heap profile to PostScript</title> + <title><command>hp2ps</command>--heap profile to PostScript</title> <indexterm><primary><command>hp2ps</command></primary></indexterm> <indexterm><primary>heap profiles</primary></indexterm> diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index bc50f28d3c..3e3ae3f7d2 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -100,7 +100,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar <para> If you absolutely positively want all the rest of the options in a command line to go to the program (and not the RTS), use a - <option>––RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>. + <option>--RTS</option><indexterm><primary><option>--RTS</option></primary></indexterm>. </para> <para> diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml index d0acbfb39f..84f6684307 100644 --- a/docs/users_guide/separate_compilation.xml +++ b/docs/users_guide/separate_compilation.xml @@ -836,7 +836,13 @@ values. For example: </programlisting> </para></listitem> <listitem><para> Fixity declarations are exactly as in Haskell.</para></listitem> -<listitem><para> Type synonym declarations are exactly as in Haskell.</para></listitem> +<listitem><para> Vanilla type synonym declarations are exactly as in Haskell.</para></listitem> +<listitem><para> Open type and data family declarations are exactly as in Haskell.</para></listitem> +<listitem><para> A closed type family may optionally omit its equations, as in the following example: +<programlisting> + type family ClosedFam a where .. +</programlisting> +The <literal>..</literal> is meant literally -- you should write two dots in your file. Note that the <literal>where</literal> clause is still necessary to distinguish closed families from open ones. If you give any equations of a closed family, you must give all of them, in the same order as they appear in the accompanying Haskell file.</para></listitem> <listitem><para> A data type declaration can either be given in full, exactly as in Haskell, or it can be given abstractly, by omitting the '=' sign and everything that follows. For example: <programlisting> @@ -1037,7 +1043,7 @@ M.o : X.hi-boot locate any imported modules that come from packages. The package modules won't be included in the dependencies generated, though (but see the - <option>––include-pkg-deps</option> option below).</para> + <option>--include-pkg-deps</option> option below).</para> <para>The dependency generation phase of GHC can take some additional options, which you may find useful. @@ -1104,7 +1110,7 @@ M.o : X.hi-boot </varlistentry> <varlistentry> - <term><option>––exclude-module=<file></option></term> + <term><option>--exclude-module=<file></option></term> <listitem> <para>Regard <filename><file></filename> as "stable"; i.e., exclude it from having dependencies on @@ -1113,7 +1119,7 @@ M.o : X.hi-boot </varlistentry> <varlistentry> - <term><option>––include-pkg-deps</option></term> + <term><option>--include-pkg-deps</option></term> <listitem> <para>Regard modules imported from packages as unstable, i.e., generate dependencies on any imported package modules diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index be7e3da2ce..7540279504 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -183,7 +183,7 @@ module X where <varlistentry> <term>Mode flags</term> <listitem> - <para>For example, <option>––make</option> or <option>-E</option>. + <para>For example, <option>--make</option> or <option>-E</option>. There may only be a single mode flag on the command line. The available modes are listed in <xref linkend="modes"/>.</para> </listitem> @@ -341,10 +341,10 @@ module X where <varlistentry> <term> - <cmdsynopsis><command>ghc ––make</command> + <cmdsynopsis><command>ghc --make</command> </cmdsynopsis> <indexterm><primary>make mode</primary></indexterm> - <indexterm><primary><option>––make</option></primary></indexterm> + <indexterm><primary><option>--make</option></primary></indexterm> </term> <listitem> <para>In this mode, GHC will build a multi-module Haskell @@ -357,7 +357,7 @@ module X where <para> This mode is the default if there are any Haskell source files mentioned on the command line, and in this case - the <option>––make</option> option can be omitted. + the <option>--make</option> option can be omitted. </para> </listitem> </varlistentry> @@ -435,7 +435,7 @@ module X where <cmdsynopsis> <command>ghc --help</command> <command>ghc -?</command> </cmdsynopsis> - <indexterm><primary><option>––help</option></primary></indexterm> + <indexterm><primary><option>--help</option></primary></indexterm> </term> <listitem> <para>Cause GHC to spew a long usage message to standard @@ -448,7 +448,7 @@ module X where <cmdsynopsis> <command>ghc --show-iface <replaceable>file</replaceable></command> </cmdsynopsis> - <indexterm><primary><option>––--show-iface</option></primary></indexterm> + <indexterm><primary><option>--show-iface</option></primary></indexterm> </term> <listitem> <para>Read the interface in @@ -463,7 +463,7 @@ module X where <command>ghc --supported-extensions</command> <command>ghc --supported-languages</command> </cmdsynopsis> - <indexterm><primary><option>––supported-extensions</option></primary><primary><option>––supported-languages</option></primary></indexterm> + <indexterm><primary><option>--supported-extensions</option></primary><primary><option>--supported-languages</option></primary></indexterm> </term> <listitem> <para>Print the supported language extensions.</para> @@ -473,9 +473,21 @@ module X where <varlistentry> <term> <cmdsynopsis> + <command>ghc --show-options</command> + </cmdsynopsis> + <indexterm><primary><option>--show-options</option></primary></indexterm> + </term> + <listitem> + <para>Print the supported command line options. This flag can be used for autocompletion in a shell.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <cmdsynopsis> <command>ghc --info</command> </cmdsynopsis> - <indexterm><primary><option>––info</option></primary></indexterm> + <indexterm><primary><option>--info</option></primary></indexterm> </term> <listitem> <para>Print information about the compiler.</para> @@ -489,7 +501,7 @@ module X where <command>ghc -V</command> </cmdsynopsis> <indexterm><primary><option>-V</option></primary></indexterm> - <indexterm><primary><option>––version</option></primary></indexterm> + <indexterm><primary><option>--version</option></primary></indexterm> </term> <listitem> <para>Print a one-line string including GHC's version number.</para> @@ -501,7 +513,7 @@ module X where <cmdsynopsis> <command>ghc --numeric-version</command> </cmdsynopsis> - <indexterm><primary><option>––numeric-version</option></primary></indexterm> + <indexterm><primary><option>--numeric-version</option></primary></indexterm> </term> <listitem> <para>Print GHC's numeric version number only.</para> @@ -513,7 +525,7 @@ module X where <cmdsynopsis> <command>ghc --print-libdir</command> </cmdsynopsis> - <indexterm><primary><option>––print-libdir</option></primary></indexterm> + <indexterm><primary><option>--print-libdir</option></primary></indexterm> </term> <listitem> <para>Print the path to GHC's library directory. This is @@ -530,8 +542,8 @@ module X where </variablelist> <sect2 id="make-mode"> - <title>Using <command>ghc</command> <option>––make</option></title> - <indexterm><primary><option>––make</option></primary></indexterm> + <title>Using <command>ghc</command> <option>--make</option></title> + <indexterm><primary><option>--make</option></primary></indexterm> <indexterm><primary>separate compilation</primary></indexterm> <para>In this mode, GHC will build a multi-module Haskell program by following @@ -542,7 +554,7 @@ module X where program like this:</para> <screen> -ghc ––make Main.hs +ghc --make Main.hs </screen> <para> @@ -563,7 +575,7 @@ ghc Main.hs program will also be linked into an executable.</para> <para>The main advantages to using <literal>ghc - ––make</literal> over traditional + --make</literal> over traditional <literal>Makefile</literal>s are:</para> <itemizedlist> @@ -571,7 +583,7 @@ ghc Main.hs <para>GHC doesn't have to be restarted for each compilation, which means it can cache information between compilations. Compiling a multi-module program with <literal>ghc - ––make</literal> can be up to twice as fast as + --make</literal> can be up to twice as fast as running <literal>ghc</literal> individually on each source file.</para> </listitem> @@ -588,7 +600,7 @@ ghc Main.hs <para>Any of the command-line options described in the rest of this chapter can be used with - <option>––make</option>, but note that any options + <option>--make</option>, but note that any options you give on the command line will apply to all the source files compiled, so if you want any options to apply to a single source file only, you'll need to use an <literal>OPTIONS_GHC</literal> @@ -828,8 +840,8 @@ ghc -c Foo.hs <listitem> <para>Minimal verbosity: print one line per compilation (this is the default when - <option>––make</option> or - <option>––interactive</option> is on).</para> + <option>--make</option> or + <option>--interactive</option> is on).</para> </listitem> </varlistentry> @@ -950,17 +962,23 @@ test.hs:(5,4)-(6,7): <option>-fwarn-overlapping-patterns</option>, <option>-fwarn-warnings-deprecations</option>, <option>-fwarn-deprecated-flags</option>, + <option>-fwarn-unrecognised-pragmas</option>, + <option>-fwarn-pointless-pragmas</option>, <option>-fwarn-duplicate-constraints</option>, <option>-fwarn-duplicate-exports</option>, + <option>-fwarn-overflowed-literals</option>, + <option>-fwarn-empty-enumerations</option>, <option>-fwarn-missing-fields</option>, <option>-fwarn-missing-methods</option>, <option>-fwarn-lazy-unlifted-bindings</option>, <option>-fwarn-wrong-do-bind</option>, <option>-fwarn-unsupported-calling-conventions</option>, - <option>-fwarn-dodgy-foreign-imports</option>, and - <option>-fwarn-typeable-instances</option>. The following - flags are - simple ways to select standard “packages” of warnings: + <option>-fwarn-dodgy-foreign-imports</option>, + <option>-fwarn-typeable-instances</option>, + <option>-fwarn-inline-rule-shadowing</option>, and + <option>-fwarn-unsupported-llvm-version</option>. + The following flags are simple ways to select standard + “packages” of warnings: </para> <variablelist> @@ -1078,6 +1096,20 @@ test.hs:(5,4)-(6,7): </varlistentry> <varlistentry> + <term><option>-fwarn-pointless-pragmas</option>:</term> + <listitem> + <indexterm><primary><option>-fwarn-pointless-pragmas</option></primary> + </indexterm> + <indexterm><primary>warnings</primary></indexterm> + <indexterm><primary>pragmas</primary></indexterm> + <para>Causes a warning to be emitted when GHC detects that a + module contains a pragma that has no effect.</para> + + <para>This option is on by default.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-fwarn-warnings-deprecations</option>:</term> <listitem> <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary> @@ -1183,6 +1215,30 @@ foreign import "&f" f :: FunPtr t </varlistentry> <varlistentry> + <term><option>-fwarn-overflowed-literals</option>:</term> + <listitem> + <indexterm><primary><option>-fwarn-overflowed-literals</option></primary> + </indexterm> + <para> + Causes a warning to be emitted if a literal will overflow, + e.g. <literal>300 :: Word8</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-fwarn-empty-enumerations</option>:</term> + <listitem> + <indexterm><primary><option>-fwarn-empty-enumerations</option></primary> + </indexterm> + <para> + Causes a warning to be emitted if an enumeration is + empty, e.g. <literal>[5 .. 3]</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-fwarn-lazy-unlifted-bindings</option>:</term> <listitem> <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary> @@ -1901,11 +1957,12 @@ f "2" = 2 <indexterm><primary>constructor fields, strict</primary></indexterm> </term> <listitem> - <para>This option causes all constructor fields which are - marked strict (i.e. “!”) and which - representation is smaller or equal to the size of a - pointer to be unpacked, if possible. It is equivalent to - adding an <literal>UNPACK</literal> pragma (see <xref + <para><emphasis>On by default.</emphasis>. This option + causes all constructor fields which are marked strict + (i.e. “!”) and which representation is smaller + or equal to the size of a pointer to be unpacked, if + possible. It is equivalent to adding an + <literal>UNPACK</literal> pragma (see <xref linkend="unpack-pragma"/>) to every strict constructor field that fulfils the size restriction. </para> diff --git a/docs/users_guide/utils.xml b/docs/users_guide/utils.xml index 109cc01752..005f2edaee 100644 --- a/docs/users_guide/utils.xml +++ b/docs/users_guide/utils.xml @@ -187,7 +187,7 @@ tags: <variablelist> <varlistentry> <term><literal>-o FILE</literal> or - <literal>––output=FILE</literal></term> + <literal>--output=FILE</literal></term> <listitem> <para>Name of the Haskell file.</para> </listitem> @@ -195,7 +195,7 @@ tags: <varlistentry> <term><literal>-t FILE</literal> or - <literal>––template=FILE</literal></term> + <literal>--template=FILE</literal></term> <listitem> <para>The template file (see below).</para> </listitem> @@ -203,7 +203,7 @@ tags: <varlistentry> <term><literal>-c PROG</literal> or - <literal>––cc=PROG</literal></term> + <literal>--cc=PROG</literal></term> <listitem> <para>The C compiler to use (default: <command>gcc</command>)</para> @@ -212,7 +212,7 @@ tags: <varlistentry> <term><literal>-l PROG</literal> or - <literal>––ld=PROG</literal></term> + <literal>--ld=PROG</literal></term> <listitem> <para>The linker to use (default: <command>gcc</command>).</para> @@ -221,7 +221,7 @@ tags: <varlistentry> <term><literal>-C FLAG</literal> or - <literal>––cflag=FLAG</literal></term> + <literal>--cflag=FLAG</literal></term> <listitem> <para>An extra flag to pass to the C compiler.</para> </listitem> @@ -236,7 +236,7 @@ tags: <varlistentry> <term><literal>-L FLAG</literal> or - <literal>––lflag=FLAG</literal></term> + <literal>--lflag=FLAG</literal></term> <listitem> <para>An extra flag to pass to the linker.</para> </listitem> @@ -244,7 +244,7 @@ tags: <varlistentry> <term><literal>-i FILE</literal> or - <literal>––include=FILE</literal></term> + <literal>--include=FILE</literal></term> <listitem> <para>As if the appropriate <literal>#include</literal> directive was placed in the source.</para> @@ -253,7 +253,7 @@ tags: <varlistentry> <term><literal>-D NAME[=VALUE]</literal> or - <literal>––define=NAME[=VALUE]</literal></term> + <literal>--define=NAME[=VALUE]</literal></term> <listitem> <para>As if the appropriate <literal>#define</literal> directive was placed in the source.</para> @@ -261,7 +261,7 @@ tags: </varlistentry> <varlistentry> - <term><literal>––no-compile</literal></term> + <term><literal>--no-compile</literal></term> <listitem> <para>Stop after writing out the intermediate C program to disk. The file name for the intermediate C program is the input file name @@ -271,7 +271,7 @@ tags: <varlistentry> <term><literal>-k</literal> or - <literal>––keep-files</literal></term> + <literal>--keep-files</literal></term> <listitem> <para>Proceed as normal, but do not delete any intermediate files.</para> </listitem> @@ -279,14 +279,14 @@ tags: <varlistentry> <term><literal>-x</literal> or - <literal>––cross-compile</literal></term> + <literal>--cross-compile</literal></term> <listitem> <para>Activate cross-compilation mode (see <xref linkend="hsc2hs_cross"/>).</para> </listitem> </varlistentry> <varlistentry> - <term><literal>––cross-safe</literal></term> + <term><literal>--cross-safe</literal></term> <listitem> <para>Restrict the .hsc directives to those supported by the <literal>--cross-compile</literal> mode (see <xref linkend="hsc2hs_cross"/>). @@ -298,14 +298,14 @@ tags: <varlistentry> - <term><literal>-?</literal> or <literal>––help</literal></term> + <term><literal>-?</literal> or <literal>--help</literal></term> <listitem> <para>Display a summary of the available flags and exit successfully.</para> </listitem> </varlistentry> <varlistentry> - <term><literal>-V</literal> or <literal>––version</literal></term> + <term><literal>-V</literal> or <literal>--version</literal></term> <listitem> <para>Output version information and exit successfully.</para> </listitem> diff --git a/docs/users_guide/win32-dlls.xml b/docs/users_guide/win32-dlls.xml index ad1c788ada..2e2cb46298 100644 --- a/docs/users_guide/win32-dlls.xml +++ b/docs/users_guide/win32-dlls.xml @@ -313,7 +313,7 @@ option on all the Haskell modules that make up your application. <para> <indexterm><primary>Creating a Win32 DLL</primary></indexterm> -<indexterm><primary>–shared</primary></indexterm> +<indexterm><primary>-shared</primary></indexterm> Sealing up your Haskell library inside a DLL is straightforward; compile up the object files that make up the library, and then build the DLL by issuing a command of the form: @@ -321,12 +321,12 @@ the DLL by issuing a command of the form: <para> <screen> -ghc –shared -o foo.dll bar.o baz.o wibble.a -lfooble +ghc -shared -o foo.dll bar.o baz.o wibble.a -lfooble </screen> </para> <para> -By feeding the ghc compiler driver the option <option>–shared</option>, it +By feeding the ghc compiler driver the option <option>-shared</option>, it will build a DLL rather than produce an executable. The DLL will consist of all the object files and archives given on the command line. @@ -366,12 +366,12 @@ you compile into a DLL must have a common root. <listitem> <para> By default, the entry points of all the object files will be exported from -the DLL when using <option>–shared</option>. Should you want to constrain +the DLL when using <option>-shared</option>. Should you want to constrain this, you can specify the <emphasis>module definition file</emphasis> to use on the command line as follows: <screen> -ghc –shared -o .... MyDef.def +ghc -shared -o .... MyDef.def </screen> See Microsoft documentation for details, but a module definition file @@ -390,7 +390,7 @@ EXPORTS <listitem> <para> -In addition to creating a DLL, the <option>–shared</option> option also +In addition to creating a DLL, the <option>-shared</option> option also creates an import library. The import library name is derived from the name of the DLL, as follows: |