From 0ee3de0a4ed263648599dee5d94e00585c5584a2 Mon Sep 17 00:00:00 2001 From: Ian Lynagh Date: Sat, 4 Aug 2007 21:01:45 +0000 Subject: [PATCH] Canonicalise the flag format in the user guide --- docs/users_guide/flags.xml | 194 ++++++++++++++++++------------------- docs/users_guide/glasgow_exts.xml | 141 +++++++++++++-------------- 2 files changed, 164 insertions(+), 171 deletions(-) diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index 4ebcc96..eaa6225 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -593,23 +593,23 @@ - + Enable overlapping instances dynamic - + - + Enable incoherent instances. - Implies + Implies dynamic - + - + Enable undecidable instances dynamic - + n @@ -618,11 +618,11 @@ - + Enable arrow notation extension dynamic - + @@ -632,24 +632,24 @@ - or + Enable foreign function interface (implied by ) dynamic - + - + Enable generic classes dynamic - + - + Enable Implicit Parameters. Implied by . dynamic - + @@ -658,254 +658,254 @@ - + Don't implicitly import Prelude dynamic - + - + Disable the monomorphism restriction dynamic - + - + Make pattern bindings polymorphic dynamic - + - + Relaxed checking for mutually-recursive polymorphic functions dynamic - + - + Use GHCi's extended default rules in a normal module dynamic - + - + Enable overloaded string literals. dynamic - + - + Enable generalised algebraic data types. dynamic - + - + Enable type families. dynamic - + - + Enable lexically-scoped type variables. Implied by . dynamic - + - or + Enable Template Haskell. No longer implied by . dynamic - + - + Enable bang patterns. dynamic - + - + Enable the C preprocessor. dynamic - + - + Enable pattern guards. dynamic - + - + Enable unicode syntax. dynamic - + - + Enable the “magic hash”. dynamic - + - + Enable polymorphic components. dynamic - + - + Enable existential quantification. dynamic - + - + Enable kind signatures. dynamic - + - + Enable pattern type signatures. dynamic - + - + Enable empty data declarations. dynamic - + - + Enable parallel list comprehensions. dynamic - + - + Enable unlifted FFI types. dynamic - + - + Enable partially applied type synonyms. dynamic - + - + Enable rank-2 types. dynamic - + - + Enable rank-N types. dynamic - + - + Enable type operators. dynamic - + - + Enable recursive do (mdo) notation. dynamic - + - + Enable parallel arrays. dynamic - + - + Enable record wildcards. dynamic - + - + Enable record puns. dynamic - + - + Enable the disambiguate fields. exception dynamic - + - + Enable unboxed tuples. dynamic - + - + Enable standalone deriving. dynamic - + - + Enable deriving for the Data and Typeable classes. dynamic - + - + Enable type synonyms. dynamic - + - + Enable flexible contexts. dynamic - + - + Enable flexible instances. dynamic - + - + Enable constrained class methods. dynamic - + - + Enable multi parameter type classes. dynamic - + - + Enable functional dependencies. dynamic - + - + Enable newtype deriving. dynamic - + diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 27d38ee..053c4a9 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -42,23 +42,16 @@ documentation describes all the libraries that come with GHC. permitted. Leaving out all of them gives you standard Haskell 98. - Generally speaking, all the language options are introduced by "" or ""; - e.g. . Before anything else is done, the string following - "" is normalised by removing hyphens and converting - to lower case. So , , and - are all equivalent. + Generally speaking, all the language options are introduced by "", + e.g. . All the language options can be turned off by using the prefix ""; - e.g. "". + e.g. "". Language options recognised by Cabal can also be enabled using the LANGUAGE pragma, thus {-# LANGUAGE TemplateHaskell #-} (see >). - All the language options can be introduced with "" as well as "", - but this is a deprecated feature for backward compatibility. Use the "" - or LANGUAGE-pragma form. - Turning on an option that enables special syntax might cause working Haskell 98 code to fail to compile, perhaps because it uses a variable name which has @@ -115,18 +108,18 @@ documentation describes all the libraries that come with GHC. |), {|. Implies these specific language options: - , - , - , - , - . + , + , + , + , + . - and : - + : + This option enables the language extension defined in the @@ -138,7 +131,7 @@ documentation describes all the libraries that come with GHC. - ,: + ,: These two flags control how generalisation is done. @@ -149,8 +142,8 @@ documentation describes all the libraries that come with GHC. - : - + : + Use GHCi's extended default rules in a regular module (). @@ -161,16 +154,16 @@ documentation describes all the libraries that come with GHC. - - + + - - + + - - + + @@ -195,8 +188,8 @@ documentation describes all the libraries that come with GHC. - - + + See . Independent of @@ -214,8 +207,8 @@ documentation describes all the libraries that come with GHC. - - + + See . Independent of @@ -224,13 +217,13 @@ documentation describes all the libraries that come with GHC. - + - -XnoImplicitPrelude + -XNoImplicitPrelude option GHC normally imports Prelude.hi files for you. If you'd rather it didn't, then give it a - option. The idea is + option. The idea is that you can then import a Prelude of your own. (But don't call it Prelude; the Haskell module namespace is flat, and you must not conflict with any @@ -245,14 +238,14 @@ documentation describes all the libraries that come with GHC. translation for list comprehensions continues to use Prelude.map etc. - However, does + However, does change the handling of certain built-in syntax: see . - + Enables implicit parameters (see ). Currently also implied by @@ -265,7 +258,7 @@ documentation describes all the libraries that come with GHC. - + Enables overloaded string literals (see ). @@ -273,7 +266,7 @@ documentation describes all the libraries that come with GHC. - + Enables lexically-scoped type variables (see ). Implied by @@ -282,7 +275,7 @@ documentation describes all the libraries that come with GHC. - , + Enables Template Haskell (see ). This flag must @@ -859,7 +852,7 @@ This name is not supported by GHC. hierarchy. It completely defeats that purpose if the literal "1" means "Prelude.fromInteger 1", which is what the Haskell Report specifies. - So the flag causes + So the flag causes the following pieces of built-in syntax to refer to whatever is in scope, not the Prelude versions: @@ -1847,7 +1840,7 @@ may use different notation to that implemented in GHC. The rest of this section outlines the extensions to GHC that support GADTs. The extension is enabled with -. +. A GADT can only be declared using GADT-style syntax (); @@ -2750,8 +2743,8 @@ makes instance inference go into a loop, because it requires the constraint Nevertheless, GHC allows you to experiment with more liberal rules. If you use -the experimental flag --X=AllowUndecidableInstances, +the experimental flag +-XUndecidableInstances, both the Paterson Conditions and the Coverage Condition (described in ) are lifted. Termination is ensured by having a fixed-depth recursion stack. If you exceed the stack depth you get a @@ -2768,11 +2761,11 @@ with N. In general, GHC requires that that it be unambiguous which instance declaration should be used to resolve a type-class constraint. This behaviour -can be modified by two flags: --X=AllowOverlappingInstances +can be modified by two flags: +-XOverlappingInstances -and --X=AllowIncoherentInstances +and +-XIncoherentInstances , as this section discusses. Both these flags are dynamic flags, and can be set on a per-module basis, using an OPTIONS_GHC pragma if desired (). @@ -2800,7 +2793,7 @@ particular constraint matches more than one. -The flag instructs GHC to allow +The flag instructs GHC to allow more than one instance to match, provided there is a most specific one. For example, the constraint C Int [Int] matches instances (A), (C) and (D), but the last is more specific, and hence is chosen. If there is no @@ -2817,22 +2810,22 @@ Suppose that from the RHS of f we get the constraint GHC does not commit to instance (C), because in a particular call of f, b might be instantiate to Int, in which case instance (D) would be more specific still. -So GHC rejects the program. If you add the flag , +So GHC rejects the program. If you add the flag , GHC will instead pick (C), without complaining about the problem of subsequent instantiations. The willingness to be overlapped or incoherent is a property of the instance declaration itself, controlled by the -presence or otherwise of the -and flags when that mdodule is +presence or otherwise of the +and flags when that mdodule is being defined. Neither flag is required in a module that imports and uses the instance declaration. Specifically, during the lookup process: An instance declaration is ignored during the lookup process if (a) a more specific match is found, and (b) the instance declaration was compiled with -. The flag setting for the +. The flag setting for the more-specific instance does not matter. @@ -2840,7 +2833,7 @@ Suppose an instance declaration does not match the constraint being looked up, b does unify with it, so that it might match when the constraint is further instantiated. Usually GHC will regard this as a reason for not committing to some other constraint. But if the instance declaration was compiled with -, GHC will skip the "does-it-unify?" +, GHC will skip the "does-it-unify?" check for that declaration. @@ -2849,18 +2842,18 @@ overlapping instances without the library client having to know. If an instance declaration is compiled without -, +, then that instance can never be overlapped. This could perhaps be inconvenient. Perhaps the rule should instead say that the overlapping instance declaration should be compiled in this way, rather than the overlapped one. Perhaps overlap at a usage site should be permitted regardless of how the instance declarations -are compiled, if the flag is +are compiled, if the flag is used at the usage site. (Mind you, the exact usage site can occasionally be hard to pin down.) We are interested to receive feedback on these points. -The flag implies the - flag, but not vice versa. +The flag implies the + flag, but not vice versa. @@ -3043,7 +3036,7 @@ Boston, Jan 2000. due to Jeff Lewis.) Implicit parameter support is enabled with the option -. +. A variable is called dynamically bound when it is bound by the calling @@ -4081,7 +4074,7 @@ and all others are monomorphic until the group is generalised Following a suggestion of Mark Jones, in his paper Typing Haskell in Haskell, -GHC implements a more general scheme. If is +GHC implements a more general scheme. If is specified: the dependency analysis ignores references to variables that have an explicit type signature. @@ -4110,7 +4103,7 @@ Now, the defintion for f is typechecked, with this type for The same refined dependency analysis also allows the type signatures of mutually-recursive functions to have different contexts, something that is illegal in Haskell 98 (Section 4.5.2, last sentence). With - + GHC only insists that the type signatures of a refined group have identical type signatures; in practice this means that only variables bound by the same pattern binding must have the same context. For example, this is fine: @@ -4131,7 +4124,7 @@ pattern binding must have the same context. For example, this is fine: GHC supports overloaded string literals. Normally a string literal has type String, but with overloaded string -literals enabled (with -X=OverloadedStrings) +literals enabled (with -XOverloadedStrings) a string literal has type (IsString a) => a. @@ -4157,7 +4150,7 @@ it explicitly (for exmaple, to give an instance declaration for it), you can imp from module GHC.Exts. -Haskell's defaulting mechanism is extended to cover string literals, when is specified. +Haskell's defaulting mechanism is extended to cover string literals, when is specified. Specifically: @@ -4220,7 +4213,7 @@ wiki page on type families. The material will be moved to this user's guide when it has stabilised. -Type families are enabled by the flag . +Type families are enabled by the flag . @@ -4269,10 +4262,10 @@ Tim Sheard is going to expand it.) Template Haskell has the following new syntactic constructions. You need to use the flag - or - + + to switch these syntactic extensions on - ( is no longer implied by + ( is no longer implied by ). @@ -4418,7 +4411,7 @@ pr s = gen (parse s) Now run the compiler (here we are a Cygwin prompt on Windows): -$ ghc --make -X=TemplateHaskell main.hs -o main.exe +$ ghc --make -XTemplateHaskell main.hs -o main.exe Run "main.exe" and here is your output: @@ -4507,7 +4500,7 @@ Palgrave, 2003. and the arrows web page at http://www.haskell.org/arrows/. -With the flag, GHC supports the arrow +With the flag, GHC supports the arrow notation described in the second of these papers. What follows is a brief introduction to the notation; it won't make much sense unless you've read Hughes's paper. @@ -4977,7 +4970,7 @@ prime feature description contains more discussion and examples than the material below. -Bang patterns are enabled by the flag . +Bang patterns are enabled by the flag . @@ -6525,7 +6518,7 @@ where clause and over-ride whichever methods you please. Use the flags (to enable the extra syntax), - (to generate extra per-data-type code), + (to generate extra per-data-type code), and (to make the Generics library available. @@ -6734,21 +6727,21 @@ carried out at let and where bindings. Switching off the dreaded Monomorphism Restriction - + Haskell's monomorphism restriction (see Section 4.5.5 of the Haskell Report) can be completely switched off by -. +. Monomorphic pattern bindings - - + + As an experimental change, we are exploring the possibility of making pattern bindings monomorphic; that is, not generalised at all. @@ -6764,7 +6757,7 @@ can be completely switched off by [x] = e -- A pattern binding Experimentally, GHC now makes pattern bindings monomorphic by -default. Use to recover the +default. Use to recover the standard behaviour. -- 1.7.10.4