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