Add a caveat to the GHC.Generics examples about :+: nesting
[ghc.git] / libraries / base / GHC / Generics.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE DataKinds #-}
3 {-# LANGUAGE DeriveFunctor #-}
4 {-# LANGUAGE DeriveGeneric #-}
5 {-# LANGUAGE FlexibleContexts #-}
6 {-# LANGUAGE FlexibleInstances #-}
7 {-# LANGUAGE GADTs #-}
8 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
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
260 -- the structure of the datatype from the root to a particular component can be
261 -- performed 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 -- (Note that this encoding strategy may not be reliable across different
355 -- versions of GHC. Recall that the compiler is free to choose any nesting
356 -- of ':+:' it chooses, so if GHC chooses @(a ':+:' b) ':+:' c@, then the
357 -- encoding for @a@ would be @[False, False]@, @b@ would be @[False, True]@,
358 -- and @c@ would be @[True]@. However, if GHC chooses @a ':+:' (b ':+:' c)@,
359 -- then the encoding for @a@ would be @[False]@, @b@ would be @[True, False]@,
360 -- and @c@ would be @[True, True]@.)
361 --
362 -- In the case for ':*:', we append the encodings of the two subcomponents:
363 --
364 -- @
365 -- instance (Encode' f, Encode' g) => Encode' (f ':*:' g) where
366 -- encode' (x ':*:' y) = encode' x ++ encode' y
367 -- @
368 --
369 -- The case for 'K1' is rather interesting. Here, we call the final function
370 -- 'encode' that we yet have to define, recursively. We will use another type
371 -- class 'Encode' for that function:
372 --
373 -- @
374 -- instance (Encode c) => Encode' ('K1' i c) where
375 -- encode' ('K1' x) = encode x
376 -- @
377 --
378 -- Note how 'Par0' and 'Rec0' both being mapped to 'K1' allows us to define
379 -- a uniform instance here.
380 --
381 -- Similarly, we can define a uniform instance for 'M1', because we completely
382 -- disregard all meta-information:
383 --
384 -- @
385 -- instance (Encode' f) => Encode' ('M1' i t f) where
386 -- encode' ('M1' x) = encode' x
387 -- @
388 --
389 -- Unlike in 'K1', the instance for 'M1' refers to 'encode'', not 'encode'.
390
391 -- *** The wrapper and generic default
392 --
393 -- |
394 --
395 -- We now define class 'Encode' for the actual 'encode' function:
396 --
397 -- @
398 -- class Encode a where
399 -- encode :: a -> [Bool]
400 -- default encode :: (Generic a, Encode' (Rep a)) => a -> [Bool]
401 -- encode x = encode' ('from' x)
402 -- @
403 --
404 -- The incoming 'x' is converted using 'from', then we dispatch to the
405 -- generic instances using 'encode''. We use this as a default definition
406 -- for 'encode'. We need the 'default encode' signature because ordinary
407 -- Haskell default methods must not introduce additional class constraints,
408 -- but our generic default does.
409 --
410 -- Defining a particular instance is now as simple as saying
411 --
412 -- @
413 -- instance (Encode a) => Encode (Tree a)
414 -- @
415 --
416 #if 0
417 -- /TODO:/ Add usage example?
418 --
419 #endif
420 -- The generic default is being used. In the future, it will hopefully be
421 -- possible to use @deriving Encode@ as well, but GHC does not yet support
422 -- that syntax for this situation.
423 --
424 -- Having 'Encode' as a class has the advantage that we can define
425 -- non-generic special cases, which is particularly useful for abstract
426 -- datatypes that have no structural representation. For example, given
427 -- a suitable integer encoding function 'encodeInt', we can define
428 --
429 -- @
430 -- instance Encode Int where
431 -- encode = encodeInt
432 -- @
433
434 -- *** Omitting generic instances
435 --
436 -- |
437 --
438 -- It is not always required to provide instances for all the generic
439 -- representation types, but omitting instances restricts the set of
440 -- datatypes the functions will work for:
441 --
442 -- * If no ':+:' instance is given, the function may still work for
443 -- empty datatypes or datatypes that have a single constructor,
444 -- but will fail on datatypes with more than one constructor.
445 --
446 -- * If no ':*:' instance is given, the function may still work for
447 -- datatypes where each constructor has just zero or one field,
448 -- in particular for enumeration types.
449 --
450 -- * If no 'K1' instance is given, the function may still work for
451 -- enumeration types, where no constructor has any fields.
452 --
453 -- * If no 'V1' instance is given, the function may still work for
454 -- any datatype that is not empty.
455 --
456 -- * If no 'U1' instance is given, the function may still work for
457 -- any datatype where each constructor has at least one field.
458 --
459 -- An 'M1' instance is always required (but it can just ignore the
460 -- meta-information, as is the case for 'encode' above).
461 #if 0
462 -- *** Using meta-information
463 --
464 -- |
465 --
466 -- TODO
467 #endif
468 -- ** Generic constructor classes
469 --
470 -- |
471 --
472 -- Datatype-generic functions as defined above work for a large class
473 -- of datatypes, including parameterized datatypes. (We have used 'Tree'
474 -- as our example above, which is of kind @* -> *@.) However, the
475 -- 'Generic' class ranges over types of kind @*@, and therefore, the
476 -- resulting generic functions (such as 'encode') must be parameterized
477 -- by a generic type argument of kind @*@.
478 --
479 -- What if we want to define generic classes that range over type
480 -- constructors (such as 'Functor', 'Traversable', or 'Foldable')?
481
482 -- *** The 'Generic1' class
483 --
484 -- |
485 --
486 -- Like 'Generic', there is a class 'Generic1' that defines a
487 -- representation 'Rep1' and conversion functions 'from1' and 'to1',
488 -- only that 'Generic1' ranges over types of kind @* -> *@. (More generally,
489 -- it can range over types of kind @k -> *@, for any kind @k@, if the
490 -- @PolyKinds@ extension is enabled. More on this later.)
491 -- The 'Generic1' class is also derivable.
492 --
493 -- The representation 'Rep1' is ever so slightly different from 'Rep'.
494 -- Let us look at 'Tree' as an example again:
495 --
496 -- @
497 -- data Tree a = Leaf a | Node (Tree a) (Tree a)
498 -- deriving 'Generic1'
499 -- @
500 --
501 -- The above declaration causes the following representation to be generated:
502 --
503 -- @
504 -- instance 'Generic1' Tree where
505 -- type 'Rep1' Tree =
506 -- 'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)
507 -- ('C1' ('MetaCons \"Leaf\" 'PrefixI 'False)
508 -- ('S1' ('MetaSel 'Nothing
509 -- 'NoSourceUnpackedness
510 -- 'NoSourceStrictness
511 -- 'DecidedLazy)
512 -- 'Par1')
513 -- ':+:'
514 -- 'C1' ('MetaCons \"Node\" 'PrefixI 'False)
515 -- ('S1' ('MetaSel 'Nothing
516 -- 'NoSourceUnpackedness
517 -- 'NoSourceStrictness
518 -- 'DecidedLazy)
519 -- ('Rec1' Tree)
520 -- ':*:'
521 -- 'S1' ('MetaSel 'Nothing
522 -- 'NoSourceUnpackedness
523 -- 'NoSourceStrictness
524 -- 'DecidedLazy)
525 -- ('Rec1' Tree)))
526 -- ...
527 -- @
528 --
529 -- The representation reuses 'D1', 'C1', 'S1' (and thereby 'M1') as well
530 -- as ':+:' and ':*:' from 'Rep'. (This reusability is the reason that we
531 -- carry around the dummy type argument for kind-@*@-types, but there are
532 -- already enough different names involved without duplicating each of
533 -- these.)
534 --
535 -- What's different is that we now use 'Par1' to refer to the parameter
536 -- (and that parameter, which used to be @a@), is not mentioned explicitly
537 -- by name anywhere; and we use 'Rec1' to refer to a recursive use of @Tree a@.
538
539 -- *** Representation of @* -> *@ types
540 --
541 -- |
542 --
543 -- Unlike 'Rec0', the 'Par1' and 'Rec1' type constructors do not
544 -- map to 'K1'. They are defined directly, as follows:
545 --
546 -- @
547 -- newtype 'Par1' p = 'Par1' { 'unPar1' :: p } -- gives access to parameter p
548 -- newtype 'Rec1' f p = 'Rec1' { 'unRec1' :: f p } -- a wrapper
549 -- @
550 --
551 -- In 'Par1', the parameter @p@ is used for the first time, whereas 'Rec1' simply
552 -- wraps an application of @f@ to @p@.
553 --
554 -- Note that 'K1' (in the guise of 'Rec0') can still occur in a 'Rep1' representation,
555 -- namely when the datatype has a field that does not mention the parameter.
556 --
557 -- The declaration
558 --
559 -- @
560 -- data WithInt a = WithInt Int a
561 -- deriving 'Generic1'
562 -- @
563 --
564 -- yields
565 --
566 -- @
567 -- instance 'Generic1' WithInt where
568 -- type 'Rep1' WithInt =
569 -- 'D1' ('MetaData \"WithInt\" \"Main\" \"package-name\" 'False)
570 -- ('C1' ('MetaCons \"WithInt\" 'PrefixI 'False)
571 -- ('S1' ('MetaSel 'Nothing
572 -- 'NoSourceUnpackedness
573 -- 'NoSourceStrictness
574 -- 'DecidedLazy)
575 -- ('Rec0' Int)
576 -- ':*:'
577 -- 'S1' ('MetaSel 'Nothing
578 -- 'NoSourceUnpackedness
579 -- 'NoSourceStrictness
580 -- 'DecidedLazy)
581 -- 'Par1'))
582 -- @
583 --
584 -- If the parameter @a@ appears underneath a composition of other type constructors,
585 -- then the representation involves composition, too:
586 --
587 -- @
588 -- data Rose a = Fork a [Rose a]
589 -- @
590 --
591 -- yields
592 --
593 -- @
594 -- instance 'Generic1' Rose where
595 -- type 'Rep1' Rose =
596 -- 'D1' ('MetaData \"Rose\" \"Main\" \"package-name\" 'False)
597 -- ('C1' ('MetaCons \"Fork\" 'PrefixI 'False)
598 -- ('S1' ('MetaSel 'Nothing
599 -- 'NoSourceUnpackedness
600 -- 'NoSourceStrictness
601 -- 'DecidedLazy)
602 -- 'Par1'
603 -- ':*:'
604 -- 'S1' ('MetaSel 'Nothing
605 -- 'NoSourceUnpackedness
606 -- 'NoSourceStrictness
607 -- 'DecidedLazy)
608 -- ([] ':.:' 'Rec1' Rose)))
609 -- @
610 --
611 -- where
612 --
613 -- @
614 -- newtype (':.:') f g p = 'Comp1' { 'unComp1' :: f (g p) }
615 -- @
616
617 -- *** Representation of @k -> *@ types
618 --
619 -- |
620 --
621 -- The 'Generic1' class can be generalized to range over types of kind
622 -- @k -> *@, for any kind @k@. To do so, derive a 'Generic1' instance with the
623 -- @PolyKinds@ extension enabled. For example, the declaration
624 --
625 -- @
626 -- data Proxy (a :: k) = Proxy deriving 'Generic1'
627 -- @
628 --
629 -- yields a slightly different instance depending on whether @PolyKinds@ is
630 -- enabled. If compiled without @PolyKinds@, then @'Rep1' Proxy :: * -> *@, but
631 -- if compiled with @PolyKinds@, then @'Rep1' Proxy :: k -> *@.
632
633 -- *** Representation of unlifted types
634 --
635 -- |
636 --
637 -- If one were to attempt to derive a Generic instance for a datatype with an
638 -- unlifted argument (for example, 'Int#'), one might expect the occurrence of
639 -- the 'Int#' argument to be marked with @'Rec0' 'Int#'@. This won't work,
640 -- though, since 'Int#' is of an unlifted kind, and 'Rec0' expects a type of
641 -- kind @*@.
642 --
643 -- One solution would be to represent an occurrence of 'Int#' with 'Rec0 Int'
644 -- instead. With this approach, however, the programmer has no way of knowing
645 -- whether the 'Int' is actually an 'Int#' in disguise.
646 --
647 -- Instead of reusing 'Rec0', a separate data family 'URec' is used to mark
648 -- occurrences of common unlifted types:
649 --
650 -- @
651 -- data family URec a p
652 --
653 -- data instance 'URec' ('Ptr' ()) p = 'UAddr' { 'uAddr#' :: 'Addr#' }
654 -- data instance 'URec' 'Char' p = 'UChar' { 'uChar#' :: 'Char#' }
655 -- data instance 'URec' 'Double' p = 'UDouble' { 'uDouble#' :: 'Double#' }
656 -- data instance 'URec' 'Int' p = 'UFloat' { 'uFloat#' :: 'Float#' }
657 -- data instance 'URec' 'Float' p = 'UInt' { 'uInt#' :: 'Int#' }
658 -- data instance 'URec' 'Word' p = 'UWord' { 'uWord#' :: 'Word#' }
659 -- @
660 --
661 -- Several type synonyms are provided for convenience:
662 --
663 -- @
664 -- type 'UAddr' = 'URec' ('Ptr' ())
665 -- type 'UChar' = 'URec' 'Char'
666 -- type 'UDouble' = 'URec' 'Double'
667 -- type 'UFloat' = 'URec' 'Float'
668 -- type 'UInt' = 'URec' 'Int'
669 -- type 'UWord' = 'URec' 'Word'
670 -- @
671 --
672 -- The declaration
673 --
674 -- @
675 -- data IntHash = IntHash Int#
676 -- deriving 'Generic'
677 -- @
678 --
679 -- yields
680 --
681 -- @
682 -- instance 'Generic' IntHash where
683 -- type 'Rep' IntHash =
684 -- 'D1' ('MetaData \"IntHash\" \"Main\" \"package-name\" 'False)
685 -- ('C1' ('MetaCons \"IntHash\" 'PrefixI 'False)
686 -- ('S1' ('MetaSel 'Nothing
687 -- 'NoSourceUnpackedness
688 -- 'NoSourceStrictness
689 -- 'DecidedLazy)
690 -- 'UInt'))
691 -- @
692 --
693 -- Currently, only the six unlifted types listed above are generated, but this
694 -- may be extended to encompass more unlifted types in the future.
695 #if 0
696 -- *** Limitations
697 --
698 -- |
699 --
700 -- /TODO/
701 --
702 -- /TODO:/ Also clear up confusion about 'Rec0' and 'Rec1' not really indicating recursion.
703 --
704 #endif
705 -----------------------------------------------------------------------------
706
707 -- * Generic representation types
708 V1, U1(..), Par1(..), Rec1(..), K1(..), M1(..)
709 , (:+:)(..), (:*:)(..), (:.:)(..)
710
711 -- ** Unboxed representation types
712 , URec(..)
713 , type UAddr, type UChar, type UDouble
714 , type UFloat, type UInt, type UWord
715
716 -- ** Synonyms for convenience
717 , Rec0, R
718 , D1, C1, S1, D, C, S
719
720 -- * Meta-information
721 , Datatype(..), Constructor(..), Selector(..)
722 , Fixity(..), FixityI(..), Associativity(..), prec
723 , SourceUnpackedness(..), SourceStrictness(..), DecidedStrictness(..)
724 , Meta(..)
725
726 -- * Generic type classes
727 , Generic(..), Generic1(..)
728
729 ) where
730
731 -- We use some base types
732 import Data.Either ( Either (..) )
733 import Data.Maybe ( Maybe(..), fromMaybe )
734 import GHC.Integer ( Integer, integerToInt )
735 import GHC.Prim ( Addr#, Char#, Double#, Float#, Int#, Word# )
736 import GHC.Ptr ( Ptr )
737 import GHC.Types
738
739 -- Needed for instances
740 import GHC.Arr ( Ix )
741 import GHC.Base ( Alternative(..), Applicative(..), Functor(..)
742 , Monad(..), MonadPlus(..), String, coerce )
743 import GHC.Classes ( Eq(..), Ord(..) )
744 import GHC.Enum ( Bounded, Enum )
745 import GHC.Read ( Read(..), lex, readParen )
746 import GHC.Show ( Show(..), showString )
747
748 -- Needed for metadata
749 import Data.Proxy ( Proxy(..) )
750 import GHC.TypeLits ( Nat, Symbol, KnownSymbol, KnownNat, symbolVal, natVal )
751
752 --------------------------------------------------------------------------------
753 -- Representation types
754 --------------------------------------------------------------------------------
755
756 -- | Void: used for datatypes without constructors
757 data V1 (p :: k)
758 deriving (Functor, Generic, Generic1)
759
760 deriving instance Eq (V1 p)
761 deriving instance Ord (V1 p)
762 deriving instance Read (V1 p)
763 deriving instance Show (V1 p)
764
765 -- | Unit: used for constructors without arguments
766 data U1 (p :: k) = U1
767 deriving (Generic, Generic1)
768
769 -- | @since 4.9.0.0
770 instance Eq (U1 p) where
771 _ == _ = True
772
773 -- | @since 4.9.0.0
774 instance Ord (U1 p) where
775 compare _ _ = EQ
776
777 -- | @since 4.9.0.0
778 instance Read (U1 p) where
779 readsPrec d = readParen (d > 10) (\r -> [(U1, s) | ("U1",s) <- lex r ])
780
781 -- | @since 4.9.0.0
782 instance Show (U1 p) where
783 showsPrec _ _ = showString "U1"
784
785 -- | @since 4.9.0.0
786 instance Functor U1 where
787 fmap _ _ = U1
788
789 -- | @since 4.9.0.0
790 instance Applicative U1 where
791 pure _ = U1
792 _ <*> _ = U1
793 liftA2 _ _ _ = U1
794
795 -- | @since 4.9.0.0
796 instance Alternative U1 where
797 empty = U1
798 _ <|> _ = U1
799
800 -- | @since 4.9.0.0
801 instance Monad U1 where
802 _ >>= _ = U1
803
804 -- | @since 4.9.0.0
805 instance MonadPlus U1
806
807 -- | Used for marking occurrences of the parameter
808 newtype Par1 p = Par1 { unPar1 :: p }
809 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
810
811 -- | @since 4.9.0.0
812 instance Applicative Par1 where
813 pure = Par1
814 (<*>) = coerce
815 liftA2 = coerce
816
817 -- | @since 4.9.0.0
818 instance Monad Par1 where
819 Par1 x >>= f = f x
820
821 -- | Recursive calls of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
822 -- is enabled)
823 newtype Rec1 (f :: k -> *) (p :: k) = Rec1 { unRec1 :: f p }
824 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
825
826 -- | @since 4.9.0.0
827 deriving instance Applicative f => Applicative (Rec1 f)
828
829 -- | @since 4.9.0.0
830 deriving instance Alternative f => Alternative (Rec1 f)
831
832 -- | @since 4.9.0.0
833 instance Monad f => Monad (Rec1 f) where
834 Rec1 x >>= f = Rec1 (x >>= \a -> unRec1 (f a))
835
836 -- | @since 4.9.0.0
837 deriving instance MonadPlus f => MonadPlus (Rec1 f)
838
839 -- | Constants, additional parameters and recursion of kind @*@
840 newtype K1 (i :: *) c (p :: k) = K1 { unK1 :: c }
841 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
842
843 -- | @since 4.9.0.0
844 deriving instance Applicative f => Applicative (M1 i c f)
845
846 -- | @since 4.9.0.0
847 deriving instance Alternative f => Alternative (M1 i c f)
848
849 -- | @since 4.9.0.0
850 deriving instance Monad f => Monad (M1 i c f)
851
852 -- | @since 4.9.0.0
853 deriving instance MonadPlus f => MonadPlus (M1 i c f)
854
855 -- | Meta-information (constructor names, etc.)
856 newtype M1 (i :: *) (c :: Meta) (f :: k -> *) (p :: k) = M1 { unM1 :: f p }
857 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
858
859 -- | Sums: encode choice between constructors
860 infixr 5 :+:
861 data (:+:) (f :: k -> *) (g :: k -> *) (p :: k) = L1 (f p) | R1 (g p)
862 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
863
864 -- | Products: encode multiple arguments to constructors
865 infixr 6 :*:
866 data (:*:) (f :: k -> *) (g :: k -> *) (p :: k) = f p :*: g p
867 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
868
869 -- | @since 4.9.0.0
870 instance (Applicative f, Applicative g) => Applicative (f :*: g) where
871 pure a = pure a :*: pure a
872 (f :*: g) <*> (x :*: y) = (f <*> x) :*: (g <*> y)
873 liftA2 f (a :*: b) (x :*: y) = liftA2 f a x :*: liftA2 f b y
874
875 -- | @since 4.9.0.0
876 instance (Alternative f, Alternative g) => Alternative (f :*: g) where
877 empty = empty :*: empty
878 (x1 :*: y1) <|> (x2 :*: y2) = (x1 <|> x2) :*: (y1 <|> y2)
879
880 -- | @since 4.9.0.0
881 instance (Monad f, Monad g) => Monad (f :*: g) where
882 (m :*: n) >>= f = (m >>= \a -> fstP (f a)) :*: (n >>= \a -> sndP (f a))
883 where
884 fstP (a :*: _) = a
885 sndP (_ :*: b) = b
886
887 -- | @since 4.9.0.0
888 instance (MonadPlus f, MonadPlus g) => MonadPlus (f :*: g)
889
890 -- | Composition of functors
891 infixr 7 :.:
892 newtype (:.:) (f :: k2 -> *) (g :: k1 -> k2) (p :: k1) =
893 Comp1 { unComp1 :: f (g p) }
894 deriving (Eq, Ord, Read, Show, Functor, Generic, Generic1)
895
896 -- | @since 4.9.0.0
897 instance (Applicative f, Applicative g) => Applicative (f :.: g) where
898 pure x = Comp1 (pure (pure x))
899 Comp1 f <*> Comp1 x = Comp1 (liftA2 (<*>) f x)
900 liftA2 f (Comp1 x) (Comp1 y) = Comp1 (liftA2 (liftA2 f) x y)
901
902 -- | @since 4.9.0.0
903 instance (Alternative f, Applicative g) => Alternative (f :.: g) where
904 empty = Comp1 empty
905 (<|>) = coerce ((<|>) :: f (g a) -> f (g a) -> f (g a)) ::
906 forall a . (f :.: g) a -> (f :.: g) a -> (f :.: g) a
907
908 -- | Constants of unlifted kinds
909 --
910 -- @since 4.9.0.0
911 data family URec (a :: *) (p :: k)
912
913 -- | Used for marking occurrences of 'Addr#'
914 --
915 -- @since 4.9.0.0
916 data instance URec (Ptr ()) (p :: k) = UAddr { uAddr# :: Addr# }
917 deriving (Eq, Ord, Functor, Generic, Generic1)
918
919 -- | Used for marking occurrences of 'Char#'
920 --
921 -- @since 4.9.0.0
922 data instance URec Char (p :: k) = UChar { uChar# :: Char# }
923 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
924
925 -- | Used for marking occurrences of 'Double#'
926 --
927 -- @since 4.9.0.0
928 data instance URec Double (p :: k) = UDouble { uDouble# :: Double# }
929 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
930
931 -- | Used for marking occurrences of 'Float#'
932 --
933 -- @since 4.9.0.0
934 data instance URec Float (p :: k) = UFloat { uFloat# :: Float# }
935 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
936
937 -- | Used for marking occurrences of 'Int#'
938 --
939 -- @since 4.9.0.0
940 data instance URec Int (p :: k) = UInt { uInt# :: Int# }
941 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
942
943 -- | Used for marking occurrences of 'Word#'
944 --
945 -- @since 4.9.0.0
946 data instance URec Word (p :: k) = UWord { uWord# :: Word# }
947 deriving (Eq, Ord, Show, Functor, Generic, Generic1)
948
949 -- | Type synonym for @'URec' 'Addr#'@
950 --
951 -- @since 4.9.0.0
952 type UAddr = URec (Ptr ())
953 -- | Type synonym for @'URec' 'Char#'@
954 --
955 -- @since 4.9.0.0
956 type UChar = URec Char
957
958 -- | Type synonym for @'URec' 'Double#'@
959 --
960 -- @since 4.9.0.0
961 type UDouble = URec Double
962
963 -- | Type synonym for @'URec' 'Float#'@
964 --
965 -- @since 4.9.0.0
966 type UFloat = URec Float
967
968 -- | Type synonym for @'URec' 'Int#'@
969 --
970 -- @since 4.9.0.0
971 type UInt = URec Int
972
973 -- | Type synonym for @'URec' 'Word#'@
974 --
975 -- @since 4.9.0.0
976 type UWord = URec Word
977
978 -- | Tag for K1: recursion (of kind @*@)
979 data R
980
981 -- | Type synonym for encoding recursion (of kind @*@)
982 type Rec0 = K1 R
983
984 -- | Tag for M1: datatype
985 data D
986 -- | Tag for M1: constructor
987 data C
988 -- | Tag for M1: record selector
989 data S
990
991 -- | Type synonym for encoding meta-information for datatypes
992 type D1 = M1 D
993
994 -- | Type synonym for encoding meta-information for constructors
995 type C1 = M1 C
996
997 -- | Type synonym for encoding meta-information for record selectors
998 type S1 = M1 S
999
1000 -- | Class for datatypes that represent datatypes
1001 class Datatype d where
1002 -- | The name of the datatype (unqualified)
1003 datatypeName :: t d (f :: k -> *) (a :: k) -> [Char]
1004 -- | The fully-qualified name of the module where the type is declared
1005 moduleName :: t d (f :: k -> *) (a :: k) -> [Char]
1006 -- | The package name of the module where the type is declared
1007 --
1008 -- @since 4.9.0.0
1009 packageName :: t d (f :: k -> *) (a :: k) -> [Char]
1010 -- | Marks if the datatype is actually a newtype
1011 --
1012 -- @since 4.7.0.0
1013 isNewtype :: t d (f :: k -> *) (a :: k) -> Bool
1014 isNewtype _ = False
1015
1016 -- | @since 4.9.0.0
1017 instance (KnownSymbol n, KnownSymbol m, KnownSymbol p, SingI nt)
1018 => Datatype ('MetaData n m p nt) where
1019 datatypeName _ = symbolVal (Proxy :: Proxy n)
1020 moduleName _ = symbolVal (Proxy :: Proxy m)
1021 packageName _ = symbolVal (Proxy :: Proxy p)
1022 isNewtype _ = fromSing (sing :: Sing nt)
1023
1024 -- | Class for datatypes that represent data constructors
1025 class Constructor c where
1026 -- | The name of the constructor
1027 conName :: t c (f :: k -> *) (a :: k) -> [Char]
1028
1029 -- | The fixity of the constructor
1030 conFixity :: t c (f :: k -> *) (a :: k) -> Fixity
1031 conFixity _ = Prefix
1032
1033 -- | Marks if this constructor is a record
1034 conIsRecord :: t c (f :: k -> *) (a :: k) -> Bool
1035 conIsRecord _ = False
1036
1037 -- | @since 4.9.0.0
1038 instance (KnownSymbol n, SingI f, SingI r)
1039 => Constructor ('MetaCons n f r) where
1040 conName _ = symbolVal (Proxy :: Proxy n)
1041 conFixity _ = fromSing (sing :: Sing f)
1042 conIsRecord _ = fromSing (sing :: Sing r)
1043
1044 -- | Datatype to represent the fixity of a constructor. An infix
1045 -- | declaration directly corresponds to an application of 'Infix'.
1046 data Fixity = Prefix | Infix Associativity Int
1047 deriving (Eq, Show, Ord, Read, Generic)
1048
1049 -- | This variant of 'Fixity' appears at the type level.
1050 --
1051 -- @since 4.9.0.0
1052 data FixityI = PrefixI | InfixI Associativity Nat
1053
1054 -- | Get the precedence of a fixity value.
1055 prec :: Fixity -> Int
1056 prec Prefix = 10
1057 prec (Infix _ n) = n
1058
1059 -- | Datatype to represent the associativity of a constructor
1060 data Associativity = LeftAssociative
1061 | RightAssociative
1062 | NotAssociative
1063 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1064
1065 -- | The unpackedness of a field as the user wrote it in the source code. For
1066 -- example, in the following data type:
1067 --
1068 -- @
1069 -- data E = ExampleConstructor Int
1070 -- {\-\# NOUNPACK \#-\} Int
1071 -- {\-\# UNPACK \#-\} Int
1072 -- @
1073 --
1074 -- The fields of @ExampleConstructor@ have 'NoSourceUnpackedness',
1075 -- 'SourceNoUnpack', and 'SourceUnpack', respectively.
1076 --
1077 -- @since 4.9.0.0
1078 data SourceUnpackedness = NoSourceUnpackedness
1079 | SourceNoUnpack
1080 | SourceUnpack
1081 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1082
1083 -- | The strictness of a field as the user wrote it in the source code. For
1084 -- example, in the following data type:
1085 --
1086 -- @
1087 -- data E = ExampleConstructor Int ~Int !Int
1088 -- @
1089 --
1090 -- The fields of @ExampleConstructor@ have 'NoSourceStrictness',
1091 -- 'SourceLazy', and 'SourceStrict', respectively.
1092 --
1093 -- @since 4.9.0.0
1094 data SourceStrictness = NoSourceStrictness
1095 | SourceLazy
1096 | SourceStrict
1097 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1098
1099 -- | The strictness that GHC infers for a field during compilation. Whereas
1100 -- there are nine different combinations of 'SourceUnpackedness' and
1101 -- 'SourceStrictness', the strictness that GHC decides will ultimately be one
1102 -- of lazy, strict, or unpacked. What GHC decides is affected both by what the
1103 -- user writes in the source code and by GHC flags. As an example, consider
1104 -- this data type:
1105 --
1106 -- @
1107 -- data E = ExampleConstructor {\-\# UNPACK \#-\} !Int !Int Int
1108 -- @
1109 --
1110 -- * If compiled without optimization or other language extensions, then the
1111 -- fields of @ExampleConstructor@ will have 'DecidedStrict', 'DecidedStrict',
1112 -- and 'DecidedLazy', respectively.
1113 --
1114 -- * If compiled with @-XStrictData@ enabled, then the fields will have
1115 -- 'DecidedStrict', 'DecidedStrict', and 'DecidedStrict', respectively.
1116 --
1117 -- * If compiled with @-O2@ enabled, then the fields will have 'DecidedUnpack',
1118 -- 'DecidedStrict', and 'DecidedLazy', respectively.
1119 --
1120 -- @since 4.9.0.0
1121 data DecidedStrictness = DecidedLazy
1122 | DecidedStrict
1123 | DecidedUnpack
1124 deriving (Eq, Show, Ord, Read, Enum, Bounded, Ix, Generic)
1125
1126 -- | Class for datatypes that represent records
1127 class Selector s where
1128 -- | The name of the selector
1129 selName :: t s (f :: k -> *) (a :: k) -> [Char]
1130 -- | The selector's unpackedness annotation (if any)
1131 --
1132 -- @since 4.9.0.0
1133 selSourceUnpackedness :: t s (f :: k -> *) (a :: k) -> SourceUnpackedness
1134 -- | The selector's strictness annotation (if any)
1135 --
1136 -- @since 4.9.0.0
1137 selSourceStrictness :: t s (f :: k -> *) (a :: k) -> SourceStrictness
1138 -- | The strictness that the compiler inferred for the selector
1139 --
1140 -- @since 4.9.0.0
1141 selDecidedStrictness :: t s (f :: k -> *) (a :: k) -> DecidedStrictness
1142
1143 -- | @since 4.9.0.0
1144 instance (SingI mn, SingI su, SingI ss, SingI ds)
1145 => Selector ('MetaSel mn su ss ds) where
1146 selName _ = fromMaybe "" (fromSing (sing :: Sing mn))
1147 selSourceUnpackedness _ = fromSing (sing :: Sing su)
1148 selSourceStrictness _ = fromSing (sing :: Sing ss)
1149 selDecidedStrictness _ = fromSing (sing :: Sing ds)
1150
1151 -- | Representable types of kind *.
1152 -- This class is derivable in GHC with the DeriveGeneric flag on.
1153 class Generic a where
1154 -- | Generic representation type
1155 type Rep a :: * -> *
1156 -- | Convert from the datatype to its representation
1157 from :: a -> (Rep a) x
1158 -- | Convert from the representation to the datatype
1159 to :: (Rep a) x -> a
1160
1161
1162 -- | Representable types of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
1163 -- is enabled).
1164 -- This class is derivable in GHC with the @DeriveGeneric@ flag on.
1165 class Generic1 (f :: k -> *) where
1166 -- | Generic representation type
1167 type Rep1 f :: k -> *
1168 -- | Convert from the datatype to its representation
1169 from1 :: f a -> (Rep1 f) a
1170 -- | Convert from the representation to the datatype
1171 to1 :: (Rep1 f) a -> f a
1172
1173 --------------------------------------------------------------------------------
1174 -- Meta-data
1175 --------------------------------------------------------------------------------
1176
1177 -- | Datatype to represent metadata associated with a datatype (@MetaData@),
1178 -- constructor (@MetaCons@), or field selector (@MetaSel@).
1179 --
1180 -- * In @MetaData n m p nt@, @n@ is the datatype's name, @m@ is the module in
1181 -- which the datatype is defined, @p@ is the package in which the datatype
1182 -- is defined, and @nt@ is @'True@ if the datatype is a @newtype@.
1183 --
1184 -- * In @MetaCons n f s@, @n@ is the constructor's name, @f@ is its fixity,
1185 -- and @s@ is @'True@ if the constructor contains record selectors.
1186 --
1187 -- * In @MetaSel mn su ss ds@, if the field uses record syntax, then @mn@ is
1188 -- 'Just' the record name. Otherwise, @mn@ is 'Nothing'. @su@ and @ss@ are
1189 -- the field's unpackedness and strictness annotations, and @ds@ is the
1190 -- strictness that GHC infers for the field.
1191 --
1192 -- @since 4.9.0.0
1193 data Meta = MetaData Symbol Symbol Symbol Bool
1194 | MetaCons Symbol FixityI Bool
1195 | MetaSel (Maybe Symbol)
1196 SourceUnpackedness SourceStrictness DecidedStrictness
1197
1198 --------------------------------------------------------------------------------
1199 -- Derived instances
1200 --------------------------------------------------------------------------------
1201
1202 deriving instance Generic [a]
1203 deriving instance Generic (Maybe a)
1204 deriving instance Generic (Either a b)
1205 deriving instance Generic Bool
1206 deriving instance Generic Ordering
1207 deriving instance Generic (Proxy t)
1208 deriving instance Generic ()
1209 deriving instance Generic ((,) a b)
1210 deriving instance Generic ((,,) a b c)
1211 deriving instance Generic ((,,,) a b c d)
1212 deriving instance Generic ((,,,,) a b c d e)
1213 deriving instance Generic ((,,,,,) a b c d e f)
1214 deriving instance Generic ((,,,,,,) a b c d e f g)
1215
1216 deriving instance Generic1 []
1217 deriving instance Generic1 Maybe
1218 deriving instance Generic1 (Either a)
1219 deriving instance Generic1 Proxy
1220 deriving instance Generic1 ((,) a)
1221 deriving instance Generic1 ((,,) a b)
1222 deriving instance Generic1 ((,,,) a b c)
1223 deriving instance Generic1 ((,,,,) a b c d)
1224 deriving instance Generic1 ((,,,,,) a b c d e)
1225 deriving instance Generic1 ((,,,,,,) a b c d e f)
1226
1227 --------------------------------------------------------------------------------
1228 -- Copied from the singletons package
1229 --------------------------------------------------------------------------------
1230
1231 -- | The singleton kind-indexed data family.
1232 data family Sing (a :: k)
1233
1234 -- | A 'SingI' constraint is essentially an implicitly-passed singleton.
1235 -- If you need to satisfy this constraint with an explicit singleton, please
1236 -- see 'withSingI'.
1237 class SingI (a :: k) where
1238 -- | Produce the singleton explicitly. You will likely need the @ScopedTypeVariables@
1239 -- extension to use this method the way you want.
1240 sing :: Sing a
1241
1242 -- | The 'SingKind' class is essentially a /kind/ class. It classifies all kinds
1243 -- for which singletons are defined. The class supports converting between a singleton
1244 -- type and the base (unrefined) type which it is built from.
1245 class SingKind k where
1246 -- | Get a base type from a proxy for the promoted kind. For example,
1247 -- @DemoteRep Bool@ will be the type @Bool@.
1248 type DemoteRep k :: *
1249
1250 -- | Convert a singleton to its unrefined version.
1251 fromSing :: Sing (a :: k) -> DemoteRep k
1252
1253 -- Singleton symbols
1254 data instance Sing (s :: Symbol) where
1255 SSym :: KnownSymbol s => Sing s
1256
1257 -- | @since 4.9.0.0
1258 instance KnownSymbol a => SingI a where sing = SSym
1259
1260 -- | @since 4.9.0.0
1261 instance SingKind Symbol where
1262 type DemoteRep Symbol = String
1263 fromSing (SSym :: Sing s) = symbolVal (Proxy :: Proxy s)
1264
1265 -- Singleton booleans
1266 data instance Sing (a :: Bool) where
1267 STrue :: Sing 'True
1268 SFalse :: Sing 'False
1269
1270 -- | @since 4.9.0.0
1271 instance SingI 'True where sing = STrue
1272
1273 -- | @since 4.9.0.0
1274 instance SingI 'False where sing = SFalse
1275
1276 -- | @since 4.9.0.0
1277 instance SingKind Bool where
1278 type DemoteRep Bool = Bool
1279 fromSing STrue = True
1280 fromSing SFalse = False
1281
1282 -- Singleton Maybe
1283 data instance Sing (b :: Maybe a) where
1284 SNothing :: Sing 'Nothing
1285 SJust :: Sing a -> Sing ('Just a)
1286
1287 -- | @since 4.9.0.0
1288 instance SingI 'Nothing where sing = SNothing
1289
1290 -- | @since 4.9.0.0
1291 instance SingI a => SingI ('Just a) where sing = SJust sing
1292
1293 -- | @since 4.9.0.0
1294 instance SingKind a => SingKind (Maybe a) where
1295 type DemoteRep (Maybe a) = Maybe (DemoteRep a)
1296 fromSing SNothing = Nothing
1297 fromSing (SJust a) = Just (fromSing a)
1298
1299 -- Singleton Fixity
1300 data instance Sing (a :: FixityI) where
1301 SPrefix :: Sing 'PrefixI
1302 SInfix :: Sing a -> Integer -> Sing ('InfixI a n)
1303
1304 -- | @since 4.9.0.0
1305 instance SingI 'PrefixI where sing = SPrefix
1306
1307 -- | @since 4.9.0.0
1308 instance (SingI a, KnownNat n) => SingI ('InfixI a n) where
1309 sing = SInfix (sing :: Sing a) (natVal (Proxy :: Proxy n))
1310
1311 -- | @since 4.9.0.0
1312 instance SingKind FixityI where
1313 type DemoteRep FixityI = Fixity
1314 fromSing SPrefix = Prefix
1315 fromSing (SInfix a n) = Infix (fromSing a) (I# (integerToInt n))
1316
1317 -- Singleton Associativity
1318 data instance Sing (a :: Associativity) where
1319 SLeftAssociative :: Sing 'LeftAssociative
1320 SRightAssociative :: Sing 'RightAssociative
1321 SNotAssociative :: Sing 'NotAssociative
1322
1323 -- | @since 4.9.0.0
1324 instance SingI 'LeftAssociative where sing = SLeftAssociative
1325
1326 -- | @since 4.9.0.0
1327 instance SingI 'RightAssociative where sing = SRightAssociative
1328
1329 -- | @since 4.9.0.0
1330 instance SingI 'NotAssociative where sing = SNotAssociative
1331
1332 -- | @since 4.0.0.0
1333 instance SingKind Associativity where
1334 type DemoteRep Associativity = Associativity
1335 fromSing SLeftAssociative = LeftAssociative
1336 fromSing SRightAssociative = RightAssociative
1337 fromSing SNotAssociative = NotAssociative
1338
1339 -- Singleton SourceUnpackedness
1340 data instance Sing (a :: SourceUnpackedness) where
1341 SNoSourceUnpackedness :: Sing 'NoSourceUnpackedness
1342 SSourceNoUnpack :: Sing 'SourceNoUnpack
1343 SSourceUnpack :: Sing 'SourceUnpack
1344
1345 -- | @since 4.9.0.0
1346 instance SingI 'NoSourceUnpackedness where sing = SNoSourceUnpackedness
1347
1348 -- | @since 4.9.0.0
1349 instance SingI 'SourceNoUnpack where sing = SSourceNoUnpack
1350
1351 -- | @since 4.9.0.0
1352 instance SingI 'SourceUnpack where sing = SSourceUnpack
1353
1354 -- | @since 4.9.0.0
1355 instance SingKind SourceUnpackedness where
1356 type DemoteRep SourceUnpackedness = SourceUnpackedness
1357 fromSing SNoSourceUnpackedness = NoSourceUnpackedness
1358 fromSing SSourceNoUnpack = SourceNoUnpack
1359 fromSing SSourceUnpack = SourceUnpack
1360
1361 -- Singleton SourceStrictness
1362 data instance Sing (a :: SourceStrictness) where
1363 SNoSourceStrictness :: Sing 'NoSourceStrictness
1364 SSourceLazy :: Sing 'SourceLazy
1365 SSourceStrict :: Sing 'SourceStrict
1366
1367 -- | @since 4.9.0.0
1368 instance SingI 'NoSourceStrictness where sing = SNoSourceStrictness
1369
1370 -- | @since 4.9.0.0
1371 instance SingI 'SourceLazy where sing = SSourceLazy
1372
1373 -- | @since 4.9.0.0
1374 instance SingI 'SourceStrict where sing = SSourceStrict
1375
1376 -- | @since 4.9.0.0
1377 instance SingKind SourceStrictness where
1378 type DemoteRep SourceStrictness = SourceStrictness
1379 fromSing SNoSourceStrictness = NoSourceStrictness
1380 fromSing SSourceLazy = SourceLazy
1381 fromSing SSourceStrict = SourceStrict
1382
1383 -- Singleton DecidedStrictness
1384 data instance Sing (a :: DecidedStrictness) where
1385 SDecidedLazy :: Sing 'DecidedLazy
1386 SDecidedStrict :: Sing 'DecidedStrict
1387 SDecidedUnpack :: Sing 'DecidedUnpack
1388
1389 -- | @since 4.9.0.0
1390 instance SingI 'DecidedLazy where sing = SDecidedLazy
1391
1392 -- | @since 4.9.0.0
1393 instance SingI 'DecidedStrict where sing = SDecidedStrict
1394
1395 -- | @since 4.9.0.0
1396 instance SingI 'DecidedUnpack where sing = SDecidedUnpack
1397
1398 -- | @since 4.9.0.0
1399 instance SingKind DecidedStrictness where
1400 type DemoteRep DecidedStrictness = DecidedStrictness
1401 fromSing SDecidedLazy = DecidedLazy
1402 fromSing SDecidedStrict = DecidedStrict
1403 fromSing SDecidedUnpack = DecidedUnpack