Commit aecccd3e authored by simonpj@microsoft.com's avatar simonpj@microsoft.com
Browse files

Documentation for stand-alone deriving (Trac #3012)

parent cab2a4c1
...@@ -2729,16 +2729,22 @@ GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by ...@@ -2729,16 +2729,22 @@ GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by
</programlisting> </programlisting>
The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
<literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part. <literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
You must supply a context (in the example the context is <literal>(Eq a)</literal>), Note the following points:
<itemizedlist>
<listitem><para>
You must supply an explicit context (in the example the context is <literal>(Eq a)</literal>),
exactly as you would in an ordinary instance declaration. exactly as you would in an ordinary instance declaration.
(In contrast the context is inferred in a <literal>deriving</literal> clause (In contrast, in a <literal>deriving</literal> clause
attached to a data type declaration.) attached to a data type declaration, the context is inferred.)
</para></listitem>
<listitem><para>
A <literal>deriving instance</literal> declaration A <literal>deriving instance</literal> declaration
must obey the same rules concerning form and termination as ordinary instance declarations, must obey the same rules concerning form and termination as ordinary instance declarations,
controlled by the same flags; see <xref linkend="instance-decls"/>. controlled by the same flags; see <xref linkend="instance-decls"/>.
</para> </para></listitem>
<para>
<listitem><para>
Unlike a <literal>deriving</literal> Unlike a <literal>deriving</literal>
declaration attached to a <literal>data</literal> declaration, the instance can be more specific declaration attached to a <literal>data</literal> declaration, the instance can be more specific
than the data type (assuming you also use than the data type (assuming you also use
...@@ -2752,8 +2758,31 @@ for example ...@@ -2752,8 +2758,31 @@ for example
</programlisting> </programlisting>
This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>, This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>,
but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>. but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>.
</para></listitem>
<listitem><para>
Unlike a <literal>deriving</literal>
declaration attached to a <literal>data</literal> declaration,
GHC does not restrict the form of the data type. Instead, GHC simply generates the appropriate
boilerplate code for the specified class, and typechecks it. If there is a type error, it is
your problem. (GHC will show you the offending code if it has a type error.)
The merit of this is that you can derive instances for GADTs and other exotic
data types, providing only that the boilerplate code does indeed typecheck. For example:
<programlisting>
data T a where
T1 :: T Int
T2 :: T Bool
deriving instance Show (T a)
</programlisting>
In this example, you cannot say <literal>... deriving( Show )</literal> on the
data type declaration for <literal>T</literal>,
because <literal>T</literal> is a GADT, but you <emphasis>can</emphasis> generate
the instance declaration using stand-alone deriving.
</para> </para>
</listitem>
<listitem>
<para>The stand-alone syntax is generalised for newtypes in exactly the same <para>The stand-alone syntax is generalised for newtypes in exactly the same
way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>). way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
For example: For example:
...@@ -2764,7 +2793,8 @@ For example: ...@@ -2764,7 +2793,8 @@ For example:
</programlisting> </programlisting>
GHC always treats the <emphasis>last</emphasis> parameter of the instance GHC always treats the <emphasis>last</emphasis> parameter of the instance
(<literal>Foo</literal> in this example) as the type whose instance is being derived. (<literal>Foo</literal> in this example) as the type whose instance is being derived.
</para> </para></listitem>
</itemizedlist></para>
</sect2> </sect2>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment