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