cc85a1dfbae2f804ce320cca067182f41a8c32be
[ghc.git] / libraries / base / GHC / Generics.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE DataKinds #-}
3 {-# LANGUAGE DeriveFunctor #-}
4 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
5 {-# LANGUAGE DeriveGeneric #-}
6 {-# LANGUAGE FlexibleContexts #-}
7 {-# LANGUAGE FlexibleInstances #-}
8 {-# LANGUAGE GADTs #-}
9 {-# LANGUAGE KindSignatures #-}
10 {-# LANGUAGE MagicHash #-}
11 {-# LANGUAGE NoImplicitPrelude #-}
12 {-# LANGUAGE PolyKinds #-}
13 {-# LANGUAGE ScopedTypeVariables #-}
14 {-# LANGUAGE StandaloneDeriving #-}
15 {-# LANGUAGE Trustworthy #-}
16 {-# LANGUAGE TypeFamilies #-}
17 {-# LANGUAGE TypeInType #-}
18 {-# LANGUAGE TypeOperators #-}
19 {-# LANGUAGE TypeSynonymInstances #-}
20 {-# LANGUAGE UndecidableInstances #-}
21
22 -----------------------------------------------------------------------------
23 -- |
24 -- Module : GHC.Generics
25 -- Copyright : (c) Universiteit Utrecht 2010-2011, University of Oxford 2012-2014
26 -- License : see libraries/base/LICENSE
27 --
28 -- Maintainer : libraries@haskell.org
29 -- Stability : internal
30 -- Portability : non-portable
31 --
32 -- @since 4.6.0.0
33 --
34 -- If you're using @GHC.Generics@, you should consider using the
35 -- <http://hackage.haskell.org/package/generic-deriving> package, which
36 -- contains many useful generic functions.
37
38 module GHC.Generics (
39 -- * Introduction
40 --
41 -- |
42 --
43 -- Datatype-generic functions are based on the idea of converting values of
44 -- a datatype @T@ into corresponding values of a (nearly) isomorphic type @'Rep' T@.
45 -- The type @'Rep' T@ is
46 -- built from a limited set of type constructors, all provided by this module. A
47 -- datatype-generic function is then an overloaded function with instances
48 -- for most of these type constructors, together with a wrapper that performs
49 -- the mapping between @T@ and @'Rep' T@. By using this technique, we merely need
50 -- a few generic instances in order to implement functionality that works for any
51 -- representable type.
52 --
53 -- Representable types are collected in the 'Generic' class, which defines the
54 -- associated type 'Rep' as well as conversion functions 'from' and 'to'.
55 -- Typically, you will not define 'Generic' instances by hand, but have the compiler
56 -- derive them for you.
57
58 -- ** Representing datatypes
59 --
60 -- |
61 --
62 -- The key to defining your own datatype-generic functions is to understand how to
63 -- represent datatypes using the given set of type constructors.
64 --
65 -- Let us look at an example first:
66 --
67 -- @
68 -- data Tree a = Leaf a | Node (Tree a) (Tree a)
69 -- deriving 'Generic'
70 -- @
71 --
72 -- The above declaration (which requires the language pragma @DeriveGeneric@)
73 -- causes the following representation to be generated:
74 --
75 -- @
76 -- instance 'Generic' (Tree a) where
77 -- type 'Rep' (Tree a) =
78 -- 'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)
79 -- ('C1' ('MetaCons \"Leaf\" 'PrefixI 'False)
80 -- ('S1' ('MetaSel 'Nothing
81 -- 'NoSourceUnpackedness
82 -- 'NoSourceStrictness
83 -- 'DecidedLazy)
84 -- ('Rec0' a))
85 -- ':+:'
86 -- 'C1' ('MetaCons \"Node\" 'PrefixI 'False)
87 -- ('S1' ('MetaSel 'Nothing
88 -- 'NoSourceUnpackedness
89 -- 'NoSourceStrictness
90 -- 'DecidedLazy)
91 -- ('Rec0' (Tree a))
92 -- ':*:'
93 -- 'S1' ('MetaSel 'Nothing
94 -- 'NoSourceUnpackedness
95 -- 'NoSourceStrictness
96 -- 'DecidedLazy)
97 -- ('Rec0' (Tree a))))
98 -- ...
99 -- @
100 --
101 -- /Hint:/ You can obtain information about the code being generated from GHC by passing
102 -- the @-ddump-deriv@ flag. In GHCi, you can expand a type family such as 'Rep' using
103 -- the @:kind!@ command.
104 --
105 -- This is a lot of information! However, most of it is actually merely meta-information
106 -- that makes names of datatypes and constructors and more available on the type level.
107 --
108 -- Here is a reduced representation for 'Tree' with nearly all meta-information removed,
109 -- for now keeping only the most essential aspects:
110 --
111 -- @
112 -- instance 'Generic' (Tree a) where
113 -- type 'Rep' (Tree a) =
114 -- 'Rec0' a
115 -- ':+:'
116 -- ('Rec0' (Tree a) ':*:' 'Rec0' (Tree a))
117 -- @
118 --
119 -- The @Tree@ datatype has two constructors. The representation of individual constructors
120 -- is combined using the binary type constructor ':+:'.
121 --
122 -- The first constructor consists of a single field, which is the parameter @a@. This is
123 -- represented as @'Rec0' a@.
124 --
125 -- The second constructor consists of two fields. Each is a recursive field of type @Tree a@,
126 -- represented as @'Rec0' (Tree a)@. Representations of individual fields are combined using
127 -- the binary type constructor ':*:'.
128 --
129 -- Now let us explain the additional tags being used in the complete representation:
130 --
131 -- * The @'S1' ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness
132 -- 'DecidedLazy)@ tag indicates several things. The @'Nothing@ indicates
133 -- that there is no record field selector associated with this field of
134 -- the constructor (if there were, it would have been marked @'Just
135 -- \"recordName\"@ instead). The other types contain meta-information on
136 -- the field's strictness:
137 --
138 -- * There is no @{\-\# UNPACK \#-\}@ or @{\-\# NOUNPACK \#-\}@ annotation
139 -- in the source, so it is tagged with @'NoSourceUnpackedness@.
140 --
141 -- * There is no strictness (@!@) or laziness (@~@) annotation in the
142 -- source, so it is tagged with @'NoSourceStrictness@.
143 --
144 -- * The compiler infers that the field is lazy, so it is tagged with
145 -- @'DecidedLazy@. Bear in mind that what the compiler decides may be
146 -- quite different from what is written in the source. See
147 -- 'DecidedStrictness' for a more detailed explanation.
148 --
149 -- The @'MetaSel@ type is also an instance of the type class 'Selector',
150 -- which can be used to obtain information about the field at the value
151 -- level.
152 --
153 -- * The @'C1' ('MetaCons \"Leaf\" 'PrefixI 'False)@ and
154 -- @'C1' ('MetaCons \"Node\" 'PrefixI 'False)@ invocations indicate that the enclosed part is
155 -- the representation of the first and second constructor of datatype @Tree@, respectively.
156 -- Here, the meta-information regarding constructor names, fixity and whether
157 -- it has named fields or not is encoded at the type level. The @'MetaCons@
158 -- type is also an instance of the type class 'Constructor'. This type class can be used
159 -- to obtain information about the constructor at the value level.
160 --
161 -- * The @'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)@ tag
162 -- indicates that the enclosed part is the representation of the
163 -- datatype @Tree@. Again, the meta-information is encoded at the type level.
164 -- The @'MetaData@ type is an instance of class 'Datatype', which
165 -- can be used to obtain the name of a datatype, the module it has been
166 -- defined in, the package it is located under, and whether it has been
167 -- defined using @data@ or @newtype@ at the value level.
168
169 -- ** Derived and fundamental representation types
170 --
171 -- |
172 --
173 -- There are many datatype-generic functions that do not distinguish between positions that
174 -- are parameters or positions that are recursive calls. There are also many datatype-generic
175 -- functions that do not care about the names of datatypes and constructors at all. To keep
176 -- the number of cases to consider in generic functions in such a situation to a minimum,
177 -- it turns out that many of the type constructors introduced above are actually synonyms,
178 -- defining them to be variants of a smaller set of constructors.
179
180 -- *** Individual fields of constructors: 'K1'
181 --
182 -- |
183 --
184 -- The type constructor 'Rec0' is a variant of 'K1':
185 --
186 -- @
187 -- type 'Rec0' = 'K1' 'R'
188 -- @
189 --
190 -- Here, 'R' is a type-level proxy that does not have any associated values.
191 --
192 -- There used to be another variant of 'K1' (namely 'Par0'), but it has since
193 -- been deprecated.
194
195 -- *** Meta information: 'M1'
196 --
197 -- |
198 --
199 -- The type constructors 'S1', 'C1' and 'D1' are all variants of 'M1':
200 --
201 -- @
202 -- type 'S1' = 'M1' 'S'
203 -- type 'C1' = 'M1' 'C'
204 -- type 'D1' = 'M1' 'D'
205 -- @
206 --
207 -- The types 'S', 'C' and 'D' are once again type-level proxies, just used to create
208 -- several variants of 'M1'.
209
210 -- *** Additional generic representation type constructors
211 --
212 -- |
213 --
214 -- Next to 'K1', 'M1', ':+:' and ':*:' there are a few more type constructors that occur
215 -- in the representations of other datatypes.
216
217 -- **** Empty datatypes: 'V1'
218 --
219 -- |
220 --
221 -- For empty datatypes, 'V1' is used as a representation. For example,
222 --
223 -- @
224 -- data Empty deriving 'Generic'
225 -- @
226 --
227 -- yields
228 --
229 -- @
230 -- instance 'Generic' Empty where
231 -- type 'Rep' Empty =
232 -- 'D1' ('MetaData \"Empty\" \"Main\" \"package-name\" 'False) 'V1'
233 -- @
234
235 -- **** Constructors without fields: 'U1'
236 --
237 -- |
238 --
239 -- If a constructor has no arguments, then 'U1' is used as its representation. For example
240 -- the representation of 'Bool' is
241 --
242 -- @
243 -- instance 'Generic' Bool where
244 -- type 'Rep' Bool =
245 -- 'D1' ('MetaData \"Bool\" \"Data.Bool\" \"package-name\" 'False)
246 -- ('C1' ('MetaCons \"False\" 'PrefixI 'False) 'U1' ':+:' 'C1' ('MetaCons \"True\" 'PrefixI 'False) 'U1')
247 -- @
248
249 -- *** Representation of types with many constructors or many fields
250 --
251 -- |
252 --
253 -- As ':+:' and ':*:' are just binary operators, one might ask what happens if the
254 -- datatype has more than two constructors, or a constructor with more than two
255 -- fields. The answer is simple: the operators are used several times, to combine
256 -- all the constructors and fields as needed. However, users /should not rely on
257 -- a specific nesting strategy/ for ':+:' and ':*:' being used. The compiler is
258 -- free to choose any nesting it prefers. (In practice, the current implementation
259 -- tries to produce a more or less balanced nesting, so that the traversal of the
260 -- structure of the datatype from the root to a particular component can be performed
261 -- in logarithmic rather than linear time.)
262
263 -- ** Defining datatype-generic functions
264 --
265 -- |
266 --
267 -- A datatype-generic function comprises two parts:
268 --
269 -- 1. /Generic instances/ for the function, implementing it for most of the representation
270 -- type constructors introduced above.
271 --
272 -- 2. A /wrapper/ that for any datatype that is in `Generic`, performs the conversion
273 -- between the original value and its `Rep`-based representation and then invokes the
274 -- generic instances.
275 --
276 -- As an example, let us look at a function 'encode' that produces a naive, but lossless
277 -- bit encoding of values of various datatypes. So we are aiming to define a function
278 --
279 -- @
280 -- encode :: 'Generic' a => a -> [Bool]
281 -- @
282 --
283 -- where we use 'Bool' as our datatype for bits.
284 --
285 -- For part 1, we define a class @Encode'@. Perhaps surprisingly, this class is parameterized
286 -- over a type constructor @f@ of kind @* -> *@. This is a technicality: all the representation
287 -- type constructors operate with kind @* -> *@ as base kind. But the type argument is never
288 -- being used. This may be changed at some point in the future. The class has a single method,
289 -- and we use the type we want our final function to have, but we replace the occurrences of
290 -- the generic type argument @a@ with @f p@ (where the @p@ is any argument; it will not be used).
291 --
292 -- > class Encode' f where
293 -- > encode' :: f p -> [Bool]
294 --
295 -- With the goal in mind to make @encode@ work on @Tree@ and other datatypes, we now define
296 -- instances for the representation type constructors 'V1', 'U1', ':+:', ':*:', 'K1', and 'M1'.
297
298 -- *** Definition of the generic representation types
299 --
300 -- |
301 --
302 -- In order to be able to do this, we need to know the actual definitions of these types:
303 --
304 -- @
305 -- data 'V1' p -- lifted version of Empty
306 -- data 'U1' p = 'U1' -- lifted version of ()
307 -- data (':+:') f g p = 'L1' (f p) | 'R1' (g p) -- lifted version of 'Either'
308 -- data (':*:') f g p = (f p) ':*:' (g p) -- lifted version of (,)
309 -- newtype 'K1' i c p = 'K1' { 'unK1' :: c } -- a container for a c
310 -- newtype 'M1' i t f p = 'M1' { 'unM1' :: f p } -- a wrapper
311 -- @
312 --
313 -- So, 'U1' is just the unit type, ':+:' is just a binary choice like 'Either',
314 -- ':*:' is a binary pair like the pair constructor @(,)@, and 'K1' is a value
315 -- of a specific type @c@, and 'M1' wraps a value of the generic type argument,
316 -- which in the lifted world is an @f p@ (where we do not care about @p@).
317
318 -- *** Generic instances
319 --
320 -- |
321 --
322 -- The instance for 'V1' is slightly awkward (but also rarely used):
323 --
324 -- @
325 -- instance Encode' 'V1' where
326 -- encode' x = undefined
327 -- @
328 --
329 -- There are no values of type @V1 p@ to pass (except undefined), so this is
330 -- actually impossible. One can ask why it is useful to define an instance for
331 -- 'V1' at all in this case? Well, an empty type can be used as an argument to
332 -- a non-empty type, and you might still want to encode the resulting type.
333 -- As a somewhat contrived example, consider @[Empty]@, which is not an empty
334 -- type, but contains just the empty list. The 'V1' instance ensures that we
335 -- can call the generic function on such types.
336 --
337 -- There is exactly one value of type 'U1', so encoding it requires no
338 -- knowledge, and we can use zero bits:
339 --
340 -- @
341 -- instance Encode' 'U1' where
342 -- encode' 'U1' = []
343 -- @
344 --
345 -- In the case for ':+:', we produce 'False' or 'True' depending on whether
346 -- the constructor of the value provided is located on the left or on the right:
347 --
348 -- @
349 -- instance (Encode' f, Encode' g) => Encode' (f ':+:' g) where
350 -- encode' ('L1' x) = False : encode' x
351 -- encode' ('R1' x) = True : encode' x
352 -- @
353 --
354 -- In the case for ':*:', we append the encodings of the two subcomponents:
355 --
356 -- @
357 -- instance (Encode' f, Encode' g) => Encode' (f ':*:' g) where
358 -- encode' (x ':*:' y) = encode' x ++ encode' y
359 -- @
360 --
361 -- The case for 'K1' is rather interesting. Here, we call the final function
362 -- 'encode' that we yet have to define, recursively. We will use another type
363 -- class 'Encode' for that function:
364 --
365 -- @
366 -- instance (Encode c) => Encode' ('K1' i c) where
367 -- encode' ('K1' x) = encode x
368 -- @
369 --
370 -- Note how 'Par0' and 'Rec0' both being mapped to 'K1' allows us to define
371 -- a uniform instance here.
372 --
373 -- Similarly, we can define a uniform instance for 'M1', because we completely
374 -- disregard all meta-information:
375 --
376 -- @
377 -- instance (Encode' f) => Encode' ('M1' i t f) where
378 -- encode' ('M1' x) = encode' x
379 -- @
380 --
381 -- Unlike in 'K1', the instance for 'M1' refers to 'encode'', not 'encode'.
382
383 -- *** The wrapper and generic default
384 --
385 -- |
386 --
387 -- We now define class 'Encode' for the actual 'encode' function:
388 --
389 -- @
390 -- class Encode a where
391 -- encode :: a -> [Bool]
392 -- default encode :: (Generic a, Encode' (Rep a)) => a -> [Bool]
393 -- encode x = encode' ('from' x)
394 -- @
395 --
396 -- The incoming 'x' is converted using 'from', then we dispatch to the
397 -- generic instances using 'encode''. We use this as a default definition
398 -- for 'encode'. We need the 'default encode' signature because ordinary
399 -- Haskell default methods must not introduce additional class constraints,
400 -- but our generic default does.
401 --
402 -- Defining a particular instance is now as simple as saying
403 --
404 -- @
405 -- instance (Encode a) => Encode (Tree a)
406 -- @
407 --
408 #if 0
409 -- /TODO:/ Add usage example?
410 --
411 #endif
412 -- The generic default is being used. In the future, it will hopefully be
413 -- possible to use @deriving Encode@ as well, but GHC does not yet support
414 -- that syntax for this situation.
415 --
416 -- Having 'Encode' as a class has the advantage that we can define
417 -- non-generic special cases, which is particularly useful for abstract
418 -- datatypes that have no structural representation. For example, given
419 -- a suitable integer encoding function 'encodeInt', we can define
420 --
421 -- @
422 -- instance Encode Int where
423 -- encode = encodeInt
424 -- @
425
426 -- *** Omitting generic instances
427 --
428 -- |
429 --
430 -- It is not always required to provide instances for all the generic
431 -- representation types, but omitting instances restricts the set of
432 -- datatypes the functions will work for:
433 --
434 -- * If no ':+:' instance is given, the function may still work for
435 -- empty datatypes or datatypes that have a single constructor,
436 -- but will fail on datatypes with more than one constructor.
437 --
438 -- * If no ':*:' instance is given, the function may still work for
439 -- datatypes where each constructor has just zero or one field,
440 -- in particular for enumeration types.
441 --
442 -- * If no 'K1' instance is given, the function may still work for
443 -- enumeration types, where no constructor has any fields.
444 --
445 -- * If no 'V1' instance is given, the function may still work for
446 -- any datatype that is not empty.
447 --
448 -- * If no 'U1' instance is given, the function may still work for
449 -- any datatype where each constructor has at least one field.
450 --
451 -- An 'M1' instance is always required (but it can just ignore the
452 -- meta-information, as is the case for 'encode' above).
453 #if 0
454 -- *** Using meta-information
455 --
456 -- |
457 --
458 -- TODO
459 #endif
460 -- ** Generic constructor classes
461 --
462 -- |
463 --
464 -- Datatype-generic functions as defined above work for a large class
465 -- of datatypes, including parameterized datatypes. (We have used 'Tree'
466 -- as our example above, which is of kind @* -> *@.) However, the
467 -- 'Generic' class ranges over types of kind @*@, and therefore, the
468 -- resulting generic functions (such as 'encode') must be parameterized
469 -- by a generic type argument of kind @*@.
470 --
471 -- What if we want to define generic classes that range over type
472 -- constructors (such as 'Functor', 'Traversable', or 'Foldable')?
473
474 -- *** The 'Generic1' class
475 --
476 -- |
477 --
478 -- Like 'Generic', there is a class 'Generic1' that defines a
479 -- representation 'Rep1' and conversion functions 'from1' and 'to1',
480 -- only that 'Generic1' ranges over types of kind @* -> *@. (More generally,
481 -- it can range over types of kind @k -> *@, for any kind @k@, if the
482 -- @PolyKinds@ extension is enabled. More on this later.)
483 -- The 'Generic1' class is also derivable.
484 --
485 -- The representation 'Rep1' is ever so slightly different from 'Rep'.
486 -- Let us look at 'Tree' as an example again:
487 --
488 -- @
489 -- data Tree a = Leaf a | Node (Tree a) (Tree a)
490 -- deriving 'Generic1'
491 -- @
492 --
493 -- The above declaration causes the following representation to be generated:
494 --
495 -- @
496 -- instance 'Generic1' Tree where
497 -- type 'Rep1' Tree =
498 -- 'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)
499 -- ('C1' ('MetaCons \"Leaf\" 'PrefixI 'False)
500 -- ('S1' ('MetaSel 'Nothing
501 -- 'NoSourceUnpackedness
502 -- 'NoSourceStrictness
503 -- 'DecidedLazy)
504 -- 'Par1')
505 -- ':+:'
506 -- 'C1' ('MetaCons \"Node\" 'PrefixI 'False)
507 -- ('S1' ('MetaSel 'Nothing
508 -- 'NoSourceUnpackedness
509 -- 'NoSourceStrictness
510 -- 'DecidedLazy)
511 -- ('Rec1' Tree)
512 -- ':*:'
513 -- 'S1' ('MetaSel 'Nothing
514 -- 'NoSourceUnpackedness
515 -- 'NoSourceStrictness
516 -- 'DecidedLazy)
517 -- ('Rec1' Tree)))
518 -- ...
519 -- @
520 --
521 -- The representation reuses 'D1', 'C1', 'S1' (and thereby 'M1') as well
522 -- as ':+:' and ':*:' from 'Rep'. (This reusability is the reason that we
523 -- carry around the dummy type argument for kind-@*@-types, but there are
524 -- already enough different names involved without duplicating each of
525 -- these.)
526 --
527 -- What's different is that we now use 'Par1' to refer to the parameter
528 -- (and that parameter, which used to be @a@), is not mentioned explicitly
529 -- by name anywhere; and we use 'Rec1' to refer to a recursive use of @Tree a@.
530
531 -- *** Representation of @* -> *@ types
532 --
533 -- |
534 --
535 -- Unlike 'Rec0', the 'Par1' and 'Rec1' type constructors do not
536 -- map to 'K1'. They are defined directly, as follows:
537 --
538 -- @
539 -- newtype 'Par1' p = 'Par1' { 'unPar1' :: p } -- gives access to parameter p
540 -- newtype 'Rec1' f p = 'Rec1' { 'unRec1' :: f p } -- a wrapper
541 -- @
542 --
543 -- In 'Par1', the parameter @p@ is used for the first time, whereas 'Rec1' simply
544 -- wraps an application of @f@ to @p@.
545 --
546 -- Note that 'K1' (in the guise of 'Rec0') can still occur in a 'Rep1' representation,
547 -- namely when the datatype has a field that does not mention the parameter.
548 --
549 -- The declaration
550 --
551 -- @
552 -- data WithInt a = WithInt Int a
553 -- deriving 'Generic1'
554 -- @
555 --
556 -- yields
557 --
558 -- @
559 -- instance 'Generic1' WithInt where
560 -- type 'Rep1' WithInt =
561 -- 'D1' ('MetaData \"WithInt\" \"Main\" \"package-name\" 'False)
562 -- ('C1' ('MetaCons \"WithInt\" 'PrefixI 'False)
563 -- ('S1' ('MetaSel 'Nothing
564 -- 'NoSourceUnpackedness
565 -- 'NoSourceStrictness
566 -- 'DecidedLazy)
567 -- ('Rec0' Int)
568 -- ':*:'
569 -- 'S1' ('MetaSel 'Nothing
570 -- 'NoSourceUnpackedness
571 -- 'NoSourceStrictness
572 -- 'DecidedLazy)
573 -- 'Par1'))
574 -- @
575 --
576 -- If the parameter @a@ appears underneath a composition of other type constructors,
577 -- then the representation involves composition, too:
578 --
579 -- @
580 -- data Rose a = Fork a [Rose a]
581 -- @
582 --
583 -- yields
584 --
585 -- @
586 -- instance 'Generic1' Rose where
587 -- type 'Rep1' Rose =
588 -- 'D1' ('MetaData \"Rose\" \"Main\" \"package-name\" 'False)
589 -- ('C1' ('MetaCons \"Fork\" 'PrefixI 'False)
590 -- ('S1' ('MetaSel 'Nothing
591 -- 'NoSourceUnpackedness
592 -- 'NoSourceStrictness
593 -- 'DecidedLazy)
594 -- 'Par1'
595 -- ':*:'
596 -- 'S1' ('MetaSel 'Nothing
597 -- 'NoSourceUnpackedness
598 -- 'NoSourceStrictness
599 -- 'DecidedLazy)
600 -- ([] ':.:' 'Rec1' Rose)))
601 -- @
602 --
603 -- where
604 --
605 -- @
606 -- newtype (':.:') f g p = 'Comp1' { 'unComp1' :: f (g p) }
607 -- @
608
609 -- *** Representation of @k -> *@ types
610 --
611 -- |
612 --
613 -- The 'Generic1' class can be generalized to range over types of kind
614 -- @k -> *@, for any kind @k@. To do so, derive a 'Generic1' instance with the
615 -- @PolyKinds@ extension enabled. For example, the declaration
616 --
617 -- @
618 -- data Proxy (a :: k) = Proxy deriving 'Generic1'
619 -- @
620 --
621 -- yields a slightly different instance depending on whether @PolyKinds@ is
622 -- enabled. If compiled without @PolyKinds@, then @'Rep1' Proxy :: * -> *@, but
623 -- if compiled with @PolyKinds@, then @'Rep1' Proxy :: k -> *@.
624
625 -- *** Representation of unlifted types
626 --
627 -- |
628 --
629 -- If one were to attempt to derive a Generic instance for a datatype with an
630 -- unlifted argument (for example, 'Int#'), one might expect the occurrence of
631 -- the 'Int#' argument to be marked with @'Rec0' 'Int#'@. This won't work,
632 -- though, since 'Int#' is of an unlifted kind, and 'Rec0' expects a type of
633 -- kind @*@.
634 --
635 -- One solution would be to represent an occurrence of 'Int#' with 'Rec0 Int'
636 -- instead. With this approach, however, the programmer has no way of knowing
637 -- whether the 'Int' is actually an 'Int#' in disguise.
638 --
639 -- Instead of reusing 'Rec0', a separate data family 'URec' is used to mark
640 -- occurrences of common unlifted types:
641 --
642 -- @
643 -- data family URec a p
644 --
645 -- data instance 'URec' ('Ptr' ()) p = 'UAddr' { 'uAddr#' :: 'Addr#' }
646 -- data instance 'URec' 'Char' p = 'UChar' { 'uChar#' :: 'Char#' }
647 -- data instance 'URec' 'Double' p = 'UDouble' { 'uDouble#' :: 'Double#' }
648 -- data instance 'URec' 'Int' p = 'UFloat' { 'uFloat#' :: 'Float#' }
649 -- data instance 'URec' 'Float' p = 'UInt' { 'uInt#' :: 'Int#' }
650 -- data instance 'URec' 'Word' p = 'UWord' { 'uWord#' :: 'Word#' }
651 -- @
652 --
653 -- Several type synonyms are provided for convenience:
654 --
655 -- @
656 -- type 'UAddr' = 'URec' ('Ptr' ())
657 -- type 'UChar' = 'URec' 'Char'
658 -- type 'UDouble' = 'URec' 'Double'
659 -- type 'UFloat' = 'URec' 'Float'
660 -- type 'UInt' = 'URec' 'Int'
661 -- type 'UWord' = 'URec' 'Word'
662 -- @
663 --
664 -- The declaration
665 --
666 -- @
667 -- data IntHash = IntHash Int#
668 -- deriving 'Generic'
669 -- @
670 --
671 -- yields
672 --
673 -- @
674 -- instance 'Generic' IntHash where
675 -- type 'Rep' IntHash =
676 -- 'D1' ('MetaData \"IntHash\" \"Main\" \"package-name\" 'False)
677 -- ('C1' ('MetaCons \"IntHash\" 'PrefixI 'False)
678 -- ('S1' ('MetaSel 'Nothing
679 -- 'NoSourceUnpackedness
680 -- 'NoSourceStrictness
681 -- 'DecidedLazy)
682 -- 'UInt'))
683 -- @
684 --
685 -- Currently, only the six unlifted types listed above are generated, but this
686 -- may be extended to encompass more unlifted types in the future.
687 #if 0
688 -- *** Limitations
689 --
690 -- |
691 --
692 -- /TODO/
693 --
694 -- /TODO:/ Also clear up confusion about 'Rec0' and 'Rec1' not really indicating recursion.
695 --
696 #endif
697 -----------------------------------------------------------------------------
698
699 -- * Generic representation types
700 V1, U1(..), Par1(..), Rec1(..), K1(..), M1(..)
701 , (:+:)(..), (:*:)(..), (:.:)(..)
702
703 -- ** Unboxed representation types
704 , URec(..)
705 , type UAddr, type UChar, type UDouble
706 , type UFloat, type UInt, type UWord
707
708 -- ** Synonyms for convenience
709 , Rec0, R
710 , D1, C1, S1, D, C, S
711
712 -- * Meta-information
713 , Datatype(..), Constructor(..), Selector(..)
714 , Fixity(..), FixityI(..), Associativity(..), prec
715 , SourceUnpackedness(..), SourceStrictness(..), DecidedStrictness(..)
716 , Meta(..)
717
718 -- * Generic type classes
719 , Generic(..), Generic1(..)
720
721 ) where
722
723 -- We use some base types
724 import Data.Either ( Either (..) )
725 import Data.Maybe ( Maybe(..), fromMaybe )
726 import GHC.Integer ( Integer, integerToInt )
727 import GHC.Prim ( Addr#, Char#, Double#, Float#, Int#, Word# )
728 import GHC.Ptr ( Ptr )
729 import GHC.Types
730
731 -- Needed for instances
732 import GHC.Arr ( Ix )
733 import GHC.Base ( Alternative(..), Applicative(..), Functor(..)
734 , Monad(..), MonadPlus(..), String, coerce )
735 import GHC.Classes ( Eq(..), Ord(..) )
736 import GHC.Enum ( Bounded, Enum )
737 import GHC.Read ( Read(..), lex, readParen )
738 import GHC.Show ( Show(..), showString )
739
740 -- Needed for metadata
741 import Data.Proxy ( Proxy(..) )
742 import GHC.TypeLits ( Nat, Symbol, KnownSymbol, KnownNat, symbolVal, natVal )
743
744 --------------------------------------------------------------------------------
745 -- Representation types
746 --------------------------------------------------------------------------------
747
748 -- | Void: used for datatypes without constructors
749 data V1 (p :: k)
750 deriving (Functor, Generic, Generic1)
751
752 deriving instance Eq (V1 p)
753 deriving instance Ord (V1 p)
754 deriving instance Read (V1 p)
755 deriving instance Show (V1 p)
756
757 -- | Unit: used for constructors without arguments
758 data U1 (p :: k) = U1
759 deriving (Generic, Generic1)
760
761 -- | @since 4.9.0.0
762 instance Eq (U1 p) where
763 _ == _ = True
764
765 -- | @since 4.9.0.0
766 instance Ord (U1 p) where
767 compare _ _ = EQ
768
769 -- | @since 4.9.0.0
770 instance Read (U1 p) where
771 readsPrec d = readParen (d > 10) (\r -> [(U1, s) | ("U1",s) <- lex r ])
772
773 -- | @since 4.9.0.0
774 instance Show (U1 p) where
775 showsPrec _ _ = showString "U1"
776
777 -- | @since 4.9.0.0
778 instance Functor U1 where
779 fmap _ _ = U1
780
781 -- | @since 4.9.0.0
782 instance Applicative U1 where
783 pure _ = U1
784 _ <*> _ = U1
785 liftA2 _ _ _ = U1
786
787 -- | @since 4.9.0.0
788 instance Alternative U1 where
789 empty = U1
790 _ <|> _ = U1
791
792 -- | @since 4.9.0.0
793 instance Monad U1 where
794 _ >>= _ = U1
795
796 -- | @since 4.9.0.0
797 instance MonadPlus U1
798
799 -- | Used for marking occurrences of the parameter
800 newtype Par1 p = Par1 { unPar1 :: p }
801 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
802
803 -- | @since 4.9.0.0
804 instance Applicative Par1 where
805 pure = Par1
806 (<*>) = coerce
807 liftA2 = coerce
808
809 -- | @since 4.9.0.0
810 instance Monad Par1 where
811 Par1 x >>= f = f x
812
813 -- | Recursive calls of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
814 -- is enabled)
815 newtype Rec1 (f :: k -> *) (p :: k) = Rec1 { unRec1 :: f p }
816 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
817
818 -- | @since 4.9.0.0
819 deriving instance Applicative f => Applicative (Rec1 f)
820
821 -- | @since 4.9.0.0
822 deriving instance Alternative f => Alternative (Rec1 f)
823
824 -- | @since 4.9.0.0
825 instance Monad f => Monad (Rec1 f) where
826 Rec1 x >>= f = Rec1 (x >>= \a -> unRec1 (f a))
827
828 -- | @since 4.9.0.0
829 deriving instance MonadPlus f => MonadPlus (Rec1 f)
830
831 -- | Constants, additional parameters and recursion of kind @*@
832 newtype K1 (i :: *) c (p :: k) = K1 { unK1 :: c }
833 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
834
835 -- | @since 4.9.0.0
836 deriving instance Applicative f => Applicative (M1 i c f)
837
838 -- | @since 4.9.0.0
839 deriving instance Alternative f => Alternative (M1 i c f)
840
841 -- | @since 4.9.0.0
842 deriving instance Monad f => Monad (M1 i c f)
843
844 -- | @since 4.9.0.0
845 deriving instance MonadPlus f => MonadPlus (M1 i c f)
846
847 -- | Meta-information (constructor names, etc.)
848 newtype M1 (i :: *) (c :: Meta) (f :: k -> *) (p :: k) = M1 { unM1 :: f p }
849 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
850
851 -- | Sums: encode choice between constructors
852 infixr 5 :+:
853 data (:+:) (f :: k -> *) (g :: k -> *) (p :: k) = L1 (f p) | R1 (g p)
854 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
855
856 -- | Products: encode multiple arguments to constructors
857 infixr 6 :*:
858 data (:*:) (f :: k -> *) (g :: k -> *) (p :: k) = f p :*: g p
859 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
860
861 -- | @since 4.9.0.0
862 instance (Applicative f, Applicative g) => Applicative (f :*: g) where
863 pure a = pure a :*: pure a
864 (f :*: g) <*> (x :*: y) = (f <*> x) :*: (g <*> y)
865 liftA2 f (a :*: b) (x :*: y) = liftA2 f a x :*: liftA2 f b y
866
867 -- | @since 4.9.0.0
868 instance (Alternative f, Alternative g) => Alternative (f :*: g) where
869 empty = empty :*: empty
870 (x1 :*: y1) <|> (x2 :*: y2) = (x1 <|> x2) :*: (y1 <|> y2)
871
872 -- | @since 4.9.0.0
873 instance (Monad f, Monad g) => Monad (f :*: g) where
874 (m :*: n) >>= f = (m >>= \a -> fstP (f a)) :*: (n >>= \a -> sndP (f a))
875 where
876 fstP (a :*: _) = a
877 sndP (_ :*: b) = b
878
879 -- | @since 4.9.0.0
880 instance (MonadPlus f, MonadPlus g) => MonadPlus (f :*: g)
881
882 -- | Composition of functors
883 infixr 7 :.:
884 newtype (:.:) (f :: k2 -> *) (g :: k1 -> k2) (p :: k1) =
885 Comp1 { unComp1 :: f (g p) }
886 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
887
888 -- | @since 4.9.0.0
889 instance (Applicative f, Applicative g) => Applicative (f :.: g) where
890 pure x = Comp1 (pure (pure x))
891 Comp1 f <*> Comp1 x = Comp1 (liftA2 (<*>) f x)
892 liftA2 f (Comp1 x) (Comp1 y) = Comp1 (liftA2 (liftA2 f) x y)
893
894 -- | @since 4.9.0.0
895 instance (Alternative f, Applicative g) => Alternative (f :.: g) where
896 empty = Comp1 empty
897 (<|>) = coerce ((<|>) :: f (g a) -> f (g a) -> f (g a)) ::
898 forall a . (f :.: g) a -> (f :.: g) a -> (f :.: g) a
899
900 -- | Constants of unlifted kinds
901 --
902 -- @since 4.9.0.0
903 data family URec (a :: *) (p :: k)
904
905 -- | Used for marking occurrences of 'Addr#'
906 --
907 -- @since 4.9.0.0
908 data instance URec (Ptr ()) (p :: k) = UAddr { uAddr# :: Addr# }
909 deriving (Eq, Ord, Functor, Generic, Generic1)
910
911 -- | Used for marking occurrences of 'Char#'
912 --
913 -- @since 4.9.0.0
914 data instance URec Char (p :: k) = UChar { uChar# :: Char# }
915 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
916
917 -- | Used for marking occurrences of 'Double#'
918 --
919 -- @since 4.9.0.0
920 data instance URec Double (p :: k) = UDouble { uDouble# :: Double# }
921 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
922
923 -- | Used for marking occurrences of 'Float#'
924 --
925 -- @since 4.9.0.0
926 data instance URec Float (p :: k) = UFloat { uFloat# :: Float# }
927 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
928
929 -- | Used for marking occurrences of 'Int#'
930 --
931 -- @since 4.9.0.0
932 data instance URec Int (p :: k) = UInt { uInt# :: Int# }
933 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
934
935 -- | Used for marking occurrences of 'Word#'
936 --
937 -- @since 4.9.0.0
938 data instance URec Word (p :: k) = UWord { uWord# :: Word# }
939 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
940
941 -- | Type synonym for @'URec' 'Addr#'@
942 --
943 -- @since 4.9.0.0
944 type UAddr = URec (Ptr ())
945 -- | Type synonym for @'URec' 'Char#'@
946 --
947 -- @since 4.9.0.0
948 type UChar = URec Char
949
950 -- | Type synonym for @'URec' 'Double#'@
951 --
952 -- @since 4.9.0.0
953 type UDouble = URec Double
954
955 -- | Type synonym for @'URec' 'Float#'@
956 --
957 -- @since 4.9.0.0
958 type UFloat = URec Float
959
960 -- | Type synonym for @'URec' 'Int#'@
961 --
962 -- @since 4.9.0.0
963 type UInt = URec Int
964
965 -- | Type synonym for @'URec' 'Word#'@
966 --
967 -- @since 4.9.0.0
968 type UWord = URec Word
969
970 -- | Tag for K1: recursion (of kind @*@)
971 data R
972
973 -- | Type synonym for encoding recursion (of kind @*@)
974 type Rec0 = K1 R
975
976 -- | Tag for M1: datatype
977 data D
978 -- | Tag for M1: constructor
979 data C
980 -- | Tag for M1: record selector
981 data S
982
983 -- | Type synonym for encoding meta-information for datatypes
984 type D1 = M1 D
985
986 -- | Type synonym for encoding meta-information for constructors
987 type C1 = M1 C
988
989 -- | Type synonym for encoding meta-information for record selectors
990 type S1 = M1 S
991
992 -- | Class for datatypes that represent datatypes
993 class Datatype d where
994 -- | The name of the datatype (unqualified)
995 datatypeName :: t d (f :: k -> *) (a :: k) -> [Char]
996 -- | The fully-qualified name of the module where the type is declared
997 moduleName :: t d (f :: k -> *) (a :: k) -> [Char]
998 -- | The package name of the module where the type is declared
999 --
1000 -- @since 4.9.0.0
1001 packageName :: t d (f :: k -> *) (a :: k) -> [Char]
1002 -- | Marks if the datatype is actually a newtype
1003 --
1004 -- @since 4.7.0.0
1005 isNewtype :: t d (f :: k -> *) (a :: k) -> Bool
1006 isNewtype _ = False
1007
1008 -- | @since 4.9.0.0
1009 instance (KnownSymbol n, KnownSymbol m, KnownSymbol p, SingI nt)
1010 => Datatype ('MetaData n m p nt) where
1011 datatypeName _ = symbolVal (Proxy :: Proxy n)
1012 moduleName _ = symbolVal (Proxy :: Proxy m)
1013 packageName _ = symbolVal (Proxy :: Proxy p)
1014 isNewtype _ = fromSing (sing :: Sing nt)
1015
1016 -- | Class for datatypes that represent data constructors
1017 class Constructor c where
1018 -- | The name of the constructor
1019 conName :: t c (f :: k -> *) (a :: k) -> [Char]
1020
1021 -- | The fixity of the constructor
1022 conFixity :: t c (f :: k -> *) (a :: k) -> Fixity
1023 conFixity _ = Prefix
1024
1025 -- | Marks if this constructor is a record
1026 conIsRecord :: t c (f :: k -> *) (a :: k) -> Bool
1027 conIsRecord _ = False
1028
1029 -- | @since 4.9.0.0
1030 instance (KnownSymbol n, SingI f, SingI r)
1031 => Constructor ('MetaCons n f r) where
1032 conName _ = symbolVal (Proxy :: Proxy n)
1033 conFixity _ = fromSing (sing :: Sing f)
1034 conIsRecord _ = fromSing (sing :: Sing r)
1035
1036 -- | Datatype to represent the fixity of a constructor. An infix
1037 -- | declaration directly corresponds to an application of 'Infix'.
1038 data Fixity = Prefix | Infix Associativity Int
1039 deriving (Eq, Show, Ord, Read, Generic)
1040
1041 -- | This variant of 'Fixity' appears at the type level.
1042 --
1043 -- @since 4.9.0.0
1044 data FixityI = PrefixI | InfixI Associativity Nat
1045
1046 -- | Get the precedence of a fixity value.
1047 prec :: Fixity -> Int
1048 prec Prefix = 10
1049 prec (Infix _ n) = n
1050
1051 -- | Datatype to represent the associativity of a constructor
1052 data Associativity = LeftAssociative
1053 | RightAssociative
1054 | NotAssociative
1055 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1056
1057 -- | The unpackedness of a field as the user wrote it in the source code. For
1058 -- example, in the following data type:
1059 --
1060 -- @
1061 -- data E = ExampleConstructor Int
1062 -- {\-\# NOUNPACK \#-\} Int
1063 -- {\-\# UNPACK \#-\} Int
1064 -- @
1065 --
1066 -- The fields of @ExampleConstructor@ have 'NoSourceUnpackedness',
1067 -- 'SourceNoUnpack', and 'SourceUnpack', respectively.
1068 --
1069 -- @since 4.9.0.0
1070 data SourceUnpackedness = NoSourceUnpackedness
1071 | SourceNoUnpack
1072 | SourceUnpack
1073 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1074
1075 -- | The strictness of a field as the user wrote it in the source code. For
1076 -- example, in the following data type:
1077 --
1078 -- @
1079 -- data E = ExampleConstructor Int ~Int !Int
1080 -- @
1081 --
1082 -- The fields of @ExampleConstructor@ have 'NoSourceStrictness',
1083 -- 'SourceLazy', and 'SourceStrict', respectively.
1084 --
1085 -- @since 4.9.0.0
1086 data SourceStrictness = NoSourceStrictness
1087 | SourceLazy
1088 | SourceStrict
1089 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1090
1091 -- | The strictness that GHC infers for a field during compilation. Whereas
1092 -- there are nine different combinations of 'SourceUnpackedness' and
1093 -- 'SourceStrictness', the strictness that GHC decides will ultimately be one
1094 -- of lazy, strict, or unpacked. What GHC decides is affected both by what the
1095 -- user writes in the source code and by GHC flags. As an example, consider
1096 -- this data type:
1097 --
1098 -- @
1099 -- data E = ExampleConstructor {\-\# UNPACK \#-\} !Int !Int Int
1100 -- @
1101 --
1102 -- * If compiled without optimization or other language extensions, then the
1103 -- fields of @ExampleConstructor@ will have 'DecidedStrict', 'DecidedStrict',
1104 -- and 'DecidedLazy', respectively.
1105 --
1106 -- * If compiled with @-XStrictData@ enabled, then the fields will have
1107 -- 'DecidedStrict', 'DecidedStrict', and 'DecidedStrict', respectively.
1108 --
1109 -- * If compiled with @-O2@ enabled, then the fields will have 'DecidedUnpack',
1110 -- 'DecidedStrict', and 'DecidedLazy', respectively.
1111 --
1112 -- @since 4.9.0.0
1113 data DecidedStrictness = DecidedLazy
1114 | DecidedStrict
1115 | DecidedUnpack
1116 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1117
1118 -- | Class for datatypes that represent records
1119 class Selector s where
1120 -- | The name of the selector
1121 selName :: t s (f :: k -> *) (a :: k) -> [Char]
1122 -- | The selector's unpackedness annotation (if any)
1123 --
1124 -- @since 4.9.0.0
1125 selSourceUnpackedness :: t s (f :: k -> *) (a :: k) -> SourceUnpackedness
1126 -- | The selector's strictness annotation (if any)
1127 --
1128 -- @since 4.9.0.0
1129 selSourceStrictness :: t s (f :: k -> *) (a :: k) -> SourceStrictness
1130 -- | The strictness that the compiler inferred for the selector
1131 --
1132 -- @since 4.9.0.0
1133 selDecidedStrictness :: t s (f :: k -> *) (a :: k) -> DecidedStrictness
1134
1135 -- | @since 4.9.0.0
1136 instance (SingI mn, SingI su, SingI ss, SingI ds)
1137 => Selector ('MetaSel mn su ss ds) where
1138 selName _ = fromMaybe "" (fromSing (sing :: Sing mn))
1139 selSourceUnpackedness _ = fromSing (sing :: Sing su)
1140 selSourceStrictness _ = fromSing (sing :: Sing ss)
1141 selDecidedStrictness _ = fromSing (sing :: Sing ds)
1142
1143 -- | Representable types of kind *.
1144 -- This class is derivable in GHC with the DeriveGeneric flag on.
1145 class Generic a where
1146 -- | Generic representation type
1147 type Rep a :: * -> *
1148 -- | Convert from the datatype to its representation
1149 from :: a -> (Rep a) x
1150 -- | Convert from the representation to the datatype
1151 to :: (Rep a) x -> a
1152
1153
1154 -- | Representable types of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
1155 -- is enabled).
1156 -- This class is derivable in GHC with the @DeriveGeneric@ flag on.
1157 class Generic1 (f :: k -> *) where
1158 -- | Generic representation type
1159 type Rep1 f :: k -> *
1160 -- | Convert from the datatype to its representation
1161 from1 :: f a -> (Rep1 f) a
1162 -- | Convert from the representation to the datatype
1163 to1 :: (Rep1 f) a -> f a
1164
1165 --------------------------------------------------------------------------------
1166 -- Meta-data
1167 --------------------------------------------------------------------------------
1168
1169 -- | Datatype to represent metadata associated with a datatype (@MetaData@),
1170 -- constructor (@MetaCons@), or field selector (@MetaSel@).
1171 --
1172 -- * In @MetaData n m p nt@, @n@ is the datatype's name, @m@ is the module in
1173 -- which the datatype is defined, @p@ is the package in which the datatype
1174 -- is defined, and @nt@ is @'True@ if the datatype is a @newtype@.
1175 --
1176 -- * In @MetaCons n f s@, @n@ is the constructor's name, @f@ is its fixity,
1177 -- and @s@ is @'True@ if the constructor contains record selectors.
1178 --
1179 -- * In @MetaSel mn su ss ds@, if the field uses record syntax, then @mn@ is
1180 -- 'Just' the record name. Otherwise, @mn@ is 'Nothing'. @su@ and @ss@ are
1181 -- the field's unpackedness and strictness annotations, and @ds@ is the
1182 -- strictness that GHC infers for the field.
1183 --
1184 -- @since 4.9.0.0
1185 data Meta = MetaData Symbol Symbol Symbol Bool
1186 | MetaCons Symbol FixityI Bool
1187 | MetaSel (Maybe Symbol)
1188 SourceUnpackedness SourceStrictness DecidedStrictness
1189
1190 --------------------------------------------------------------------------------
1191 -- Derived instances
1192 --------------------------------------------------------------------------------
1193
1194 deriving instance Generic [a]
1195 deriving instance Generic (Maybe a)
1196 deriving instance Generic (Either a b)
1197 deriving instance Generic Bool
1198 deriving instance Generic Ordering
1199 deriving instance Generic (Proxy t)
1200 deriving instance Generic ()
1201 deriving instance Generic ((,) a b)
1202 deriving instance Generic ((,,) a b c)
1203 deriving instance Generic ((,,,) a b c d)
1204 deriving instance Generic ((,,,,) a b c d e)
1205 deriving instance Generic ((,,,,,) a b c d e f)
1206 deriving instance Generic ((,,,,,,) a b c d e f g)
1207
1208 deriving instance Generic1 []
1209 deriving instance Generic1 Maybe
1210 deriving instance Generic1 (Either a)
1211 deriving instance Generic1 Proxy
1212 deriving instance Generic1 ((,) a)
1213 deriving instance Generic1 ((,,) a b)
1214 deriving instance Generic1 ((,,,) a b c)
1215 deriving instance Generic1 ((,,,,) a b c d)
1216 deriving instance Generic1 ((,,,,,) a b c d e)
1217 deriving instance Generic1 ((,,,,,,) a b c d e f)
1218
1219 --------------------------------------------------------------------------------
1220 -- Copied from the singletons package
1221 --------------------------------------------------------------------------------
1222
1223 -- | The singleton kind-indexed data family.
1224 data family Sing (a :: k)
1225
1226 -- | A 'SingI' constraint is essentially an implicitly-passed singleton.
1227 -- If you need to satisfy this constraint with an explicit singleton, please
1228 -- see 'withSingI'.
1229 class SingI (a :: k) where
1230 -- | Produce the singleton explicitly. You will likely need the @ScopedTypeVariables@
1231 -- extension to use this method the way you want.
1232 sing :: Sing a
1233
1234 -- | The 'SingKind' class is essentially a /kind/ class. It classifies all kinds
1235 -- for which singletons are defined. The class supports converting between a singleton
1236 -- type and the base (unrefined) type which it is built from.
1237 class SingKind k where
1238 -- | Get a base type from a proxy for the promoted kind. For example,
1239 -- @DemoteRep Bool@ will be the type @Bool@.
1240 type DemoteRep k :: *
1241
1242 -- | Convert a singleton to its unrefined version.
1243 fromSing :: Sing (a :: k) -> DemoteRep k
1244
1245 -- Singleton symbols
1246 data instance Sing (s :: Symbol) where
1247 SSym :: KnownSymbol s => Sing s
1248
1249 -- | @since 4.9.0.0
1250 instance KnownSymbol a => SingI a where sing = SSym
1251
1252 -- | @since 4.9.0.0
1253 instance SingKind Symbol where
1254 type DemoteRep Symbol = String
1255 fromSing (SSym :: Sing s) = symbolVal (Proxy :: Proxy s)
1256
1257 -- Singleton booleans
1258 data instance Sing (a :: Bool) where
1259 STrue :: Sing 'True
1260 SFalse :: Sing 'False
1261
1262 -- | @since 4.9.0.0
1263 instance SingI 'True where sing = STrue
1264
1265 -- | @since 4.9.0.0
1266 instance SingI 'False where sing = SFalse
1267
1268 -- | @since 4.9.0.0
1269 instance SingKind Bool where
1270 type DemoteRep Bool = Bool
1271 fromSing STrue = True
1272 fromSing SFalse = False
1273
1274 -- Singleton Maybe
1275 data instance Sing (b :: Maybe a) where
1276 SNothing :: Sing 'Nothing
1277 SJust :: Sing a -> Sing ('Just a)
1278
1279 -- | @since 4.9.0.0
1280 instance SingI 'Nothing where sing = SNothing
1281
1282 -- | @since 4.9.0.0
1283 instance SingI a => SingI ('Just a) where sing = SJust sing
1284
1285 -- | @since 4.9.0.0
1286 instance SingKind a => SingKind (Maybe a) where
1287 type DemoteRep (Maybe a) = Maybe (DemoteRep a)
1288 fromSing SNothing = Nothing
1289 fromSing (SJust a) = Just (fromSing a)
1290
1291 -- Singleton Fixity
1292 data instance Sing (a :: FixityI) where
1293 SPrefix :: Sing 'PrefixI
1294 SInfix :: Sing a -> Integer -> Sing ('InfixI a n)
1295
1296 -- | @since 4.9.0.0
1297 instance SingI 'PrefixI where sing = SPrefix
1298
1299 -- | @since 4.9.0.0
1300 instance (SingI a, KnownNat n) => SingI ('InfixI a n) where
1301 sing = SInfix (sing :: Sing a) (natVal (Proxy :: Proxy n))
1302
1303 -- | @since 4.9.0.0
1304 instance SingKind FixityI where
1305 type DemoteRep FixityI = Fixity
1306 fromSing SPrefix = Prefix
1307 fromSing (SInfix a n) = Infix (fromSing a) (I# (integerToInt n))
1308
1309 -- Singleton Associativity
1310 data instance Sing (a :: Associativity) where
1311 SLeftAssociative :: Sing 'LeftAssociative
1312 SRightAssociative :: Sing 'RightAssociative
1313 SNotAssociative :: Sing 'NotAssociative
1314
1315 -- | @since 4.9.0.0
1316 instance SingI 'LeftAssociative where sing = SLeftAssociative
1317
1318 -- | @since 4.9.0.0
1319 instance SingI 'RightAssociative where sing = SRightAssociative
1320
1321 -- | @since 4.9.0.0
1322 instance SingI 'NotAssociative where sing = SNotAssociative
1323
1324 -- | @since 4.0.0.0
1325 instance SingKind Associativity where
1326 type DemoteRep Associativity = Associativity
1327 fromSing SLeftAssociative = LeftAssociative
1328 fromSing SRightAssociative = RightAssociative
1329 fromSing SNotAssociative = NotAssociative
1330
1331 -- Singleton SourceUnpackedness
1332 data instance Sing (a :: SourceUnpackedness) where
1333 SNoSourceUnpackedness :: Sing 'NoSourceUnpackedness
1334 SSourceNoUnpack :: Sing 'SourceNoUnpack
1335 SSourceUnpack :: Sing 'SourceUnpack
1336
1337 -- | @since 4.9.0.0
1338 instance SingI 'NoSourceUnpackedness where sing = SNoSourceUnpackedness
1339
1340 -- | @since 4.9.0.0
1341 instance SingI 'SourceNoUnpack where sing = SSourceNoUnpack
1342
1343 -- | @since 4.9.0.0
1344 instance SingI 'SourceUnpack where sing = SSourceUnpack
1345
1346 -- | @since 4.9.0.0
1347 instance SingKind SourceUnpackedness where
1348 type DemoteRep SourceUnpackedness = SourceUnpackedness
1349 fromSing SNoSourceUnpackedness = NoSourceUnpackedness
1350 fromSing SSourceNoUnpack = SourceNoUnpack
1351 fromSing SSourceUnpack = SourceUnpack
1352
1353 -- Singleton SourceStrictness
1354 data instance Sing (a :: SourceStrictness) where
1355 SNoSourceStrictness :: Sing 'NoSourceStrictness
1356 SSourceLazy :: Sing 'SourceLazy
1357 SSourceStrict :: Sing 'SourceStrict
1358
1359 -- | @since 4.9.0.0
1360 instance SingI 'NoSourceStrictness where sing = SNoSourceStrictness
1361
1362 -- | @since 4.9.0.0
1363 instance SingI 'SourceLazy where sing = SSourceLazy
1364
1365 -- | @since 4.9.0.0
1366 instance SingI 'SourceStrict where sing = SSourceStrict
1367
1368 -- | @since 4.9.0.0
1369 instance SingKind SourceStrictness where
1370 type DemoteRep SourceStrictness = SourceStrictness
1371 fromSing SNoSourceStrictness = NoSourceStrictness
1372 fromSing SSourceLazy = SourceLazy
1373 fromSing SSourceStrict = SourceStrict
1374
1375 -- Singleton DecidedStrictness
1376 data instance Sing (a :: DecidedStrictness) where
1377 SDecidedLazy :: Sing 'DecidedLazy
1378 SDecidedStrict :: Sing 'DecidedStrict
1379 SDecidedUnpack :: Sing 'DecidedUnpack
1380
1381 -- | @since 4.9.0.0
1382 instance SingI 'DecidedLazy where sing = SDecidedLazy
1383
1384 -- | @since 4.9.0.0
1385 instance SingI 'DecidedStrict where sing = SDecidedStrict
1386
1387 -- | @since 4.9.0.0
1388 instance SingI 'DecidedUnpack where sing = SDecidedUnpack
1389
1390 -- | @since 4.9.0.0
1391 instance SingKind DecidedStrictness where
1392 type DemoteRep DecidedStrictness = DecidedStrictness
1393 fromSing SDecidedLazy = DecidedLazy
1394 fromSing SDecidedStrict = DecidedStrict
1395 fromSing SDecidedUnpack = DecidedUnpack