summaryrefslogtreecommitdiff
path: root/docs/users_guide/exts/deriving.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/users_guide/exts/deriving.rst')
-rw-r--r--docs/users_guide/exts/deriving.rst41
1 files changed, 41 insertions, 0 deletions
diff --git a/docs/users_guide/exts/deriving.rst b/docs/users_guide/exts/deriving.rst
new file mode 100644
index 0000000000..d10260b21f
--- /dev/null
+++ b/docs/users_guide/exts/deriving.rst
@@ -0,0 +1,41 @@
+.. _deriving:
+
+Deriving mechanism
+==================
+
+Haskell 98 allows the programmer to add a deriving clause to a data type
+declaration, to generate a standard instance declaration for specified class.
+GHC extends this mechanism along several axes:
+
+* The derivation mechanism can be used separately from the data type
+ declaration, using the :ref:`standalone deriving mechanism
+ <stand-alone-deriving>`.
+
+* In Haskell 98, the only derivable classes are ``Eq``,
+ ``Ord``, ``Enum``, ``Ix``, ``Bounded``, ``Read``, and ``Show``. :ref:`Various
+ language extensions <deriving-extra>` extend this list.
+
+* Besides the stock approach to deriving instances by generating all method
+ definitions, GHC supports two additional deriving strategies, which can
+ derive arbitrary classes:
+
+ * :ref:`Generalised newtype deriving <newtype-deriving>` for newtypes and
+ * :ref:`deriving any class <derive-any-class>` using an empty instance
+ declaration.
+
+ The user can optionally declare the desired :ref:`deriving strategy
+ <deriving-strategies>`, especially if the compiler chooses the wrong
+ one :ref:`by default <default-deriving-strategy>`.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ empty_data_deriving
+ deriving_inferred
+ standalone_deriving
+ deriving_extra
+ newtype_deriving
+ derive_any_class
+ deriving_strategies
+ deriving_via