Add GHCi :instances command
[ghc.git] / docs / users_guide / ghci.rst
index 4b01724..5f4b26e 100644 (file)
@@ -2539,6 +2539,38 @@ commonly used commands.
 
     The ``:loc-at`` command requires :ghci-cmd:`:set +c` to be set.
 
+.. ghci-cmd:: :instances ⟨type⟩
+
+    Displays all the class instances available to the argument ⟨type⟩.
+    The command will match ⟨type⟩ with the first parameter of every
+    instance and then check that all constraints are satisfiable.
+
+    When combined with ``-XPartialTypeSignatures``, a user can insert
+    wildcards into a query and learn the constraints required of each
+    wildcard for ⟨type⟩ match with an instance.
+
+    The output is a listing of all matching instances, simplified and
+    instantiated as much as possible.
+
+    For example:
+
+    .. code-block:: none
+      >:instances Maybe (Maybe Int)
+      instance Eq (Maybe (Maybe Int)) -- Defined in ‘GHC.Maybe’
+      instance Ord (Maybe (Maybe Int)) -- Defined in ‘GHC.Maybe’
+      instance Show (Maybe (Maybe Int)) -- Defined in ‘GHC.Show’
+      instance Read (Maybe (Maybe Int)) -- Defined in ‘GHC.Read’
+
+      >:set -XPartialTypeSignatures -fno-warn-partial-type-signatures
+
+      >:instances Maybe _
+      instance Eq _ => Eq (Maybe _) -- Defined in ‘GHC.Maybe’
+      instance Semigroup _ => Monoid (Maybe _) -- Defined in ‘GHC.Base’
+      instance Ord _ => Ord (Maybe _) -- Defined in ‘GHC.Maybe’
+      instance Semigroup _ => Semigroup (Maybe _) -- Defined in ‘GHC.Base’
+      instance Show _ => Show (Maybe _) -- Defined in ‘GHC.Show’
+      instance Read _ => Read (Maybe _) -- Defined in ‘GHC.Read’
+
 .. ghci-cmd:: :main; ⟨arg1⟩ ... ⟨argn⟩
 
     When a program is compiled and executed, it can use the ``getArgs``