Embrace -XTypeInType, add -XStarIsType
[ghc.git] / libraries / base / GHC / Generics.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE DataKinds #-}
3 {-# LANGUAGE DeriveFunctor #-}
4 {-# LANGUAGE DeriveGeneric #-}
5 {-# LANGUAGE EmptyDataDeriving #-}
6 {-# LANGUAGE FlexibleContexts #-}
7 {-# LANGUAGE FlexibleInstances #-}
8 {-# LANGUAGE GADTs #-}
9 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
10 {-# LANGUAGE KindSignatures #-}
11 {-# LANGUAGE MagicHash #-}
12 {-# LANGUAGE NoImplicitPrelude #-}
13 {-# LANGUAGE PolyKinds #-}
14 {-# LANGUAGE ScopedTypeVariables #-}
15 {-# LANGUAGE StandaloneDeriving #-}
16 {-# LANGUAGE Trustworthy #-}
17 {-# LANGUAGE TypeFamilies #-}
18 {-# LANGUAGE 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(..), NonEmpty(..), String, coerce
743 , Semigroup(..), Monoid(..) )
744 import GHC.Classes ( Eq(..), Ord(..) )
745 import GHC.Enum ( Bounded, Enum )
746 import GHC.Read ( Read(..) )
747 import GHC.Show ( Show(..), showString )
748
749 -- Needed for metadata
750 import Data.Proxy ( Proxy(..) )
751 import GHC.TypeLits ( Nat, Symbol, KnownSymbol, KnownNat, symbolVal, natVal )
752
753 --------------------------------------------------------------------------------
754 -- Representation types
755 --------------------------------------------------------------------------------
756
757 -- | Void: used for datatypes without constructors
758 data V1 (p :: k)
759 deriving ( Eq -- ^ @since 4.9.0.0
760 , Ord -- ^ @since 4.9.0.0
761 , Read -- ^ @since 4.9.0.0
762 , Show -- ^ @since 4.9.0.0
763 , Functor -- ^ @since 4.9.0.0
764 , Generic -- ^ @since 4.9.0.0
765 , Generic1 -- ^ @since 4.9.0.0
766 )
767
768 -- | @since 4.12.0.0
769 instance Semigroup (V1 p) where
770 v <> _ = v
771
772 -- | Unit: used for constructors without arguments
773 data U1 (p :: k) = U1
774 deriving ( Generic -- ^ @since 4.7.0.0
775 , Generic1 -- ^ @since 4.9.0.0
776 )
777
778 -- | @since 4.9.0.0
779 instance Eq (U1 p) where
780 _ == _ = True
781
782 -- | @since 4.7.0.0
783 instance Ord (U1 p) where
784 compare _ _ = EQ
785
786 -- | @since 4.9.0.0
787 deriving instance Read (U1 p)
788
789 -- | @since 4.9.0.0
790 instance Show (U1 p) where
791 showsPrec _ _ = showString "U1"
792
793 -- | @since 4.9.0.0
794 instance Functor U1 where
795 fmap _ _ = U1
796
797 -- | @since 4.9.0.0
798 instance Applicative U1 where
799 pure _ = U1
800 _ <*> _ = U1
801 liftA2 _ _ _ = U1
802
803 -- | @since 4.9.0.0
804 instance Alternative U1 where
805 empty = U1
806 _ <|> _ = U1
807
808 -- | @since 4.9.0.0
809 instance Monad U1 where
810 _ >>= _ = U1
811
812 -- | @since 4.9.0.0
813 instance MonadPlus U1
814
815 -- | @since 4.12.0.0
816 instance Semigroup (U1 p) where
817 _ <> _ = U1
818
819 -- | @since 4.12.0.0
820 instance Monoid (U1 p) where
821 mempty = U1
822
823 -- | Used for marking occurrences of the parameter
824 newtype Par1 p = Par1 { unPar1 :: p }
825 deriving ( Eq -- ^ @since 4.7.0.0
826 , Ord -- ^ @since 4.7.0.0
827 , Read -- ^ @since 4.7.0.0
828 , Show -- ^ @since 4.7.0.0
829 , Functor -- ^ @since 4.9.0.0
830 , Generic -- ^ @since 4.7.0.0
831 , Generic1 -- ^ @since 4.9.0.0
832 )
833
834 -- | @since 4.9.0.0
835 instance Applicative Par1 where
836 pure = Par1
837 (<*>) = coerce
838 liftA2 = coerce
839
840 -- | @since 4.9.0.0
841 instance Monad Par1 where
842 Par1 x >>= f = f x
843
844 -- | @since 4.12.0.0
845 deriving instance Semigroup p => Semigroup (Par1 p)
846
847 -- | @since 4.12.0.0
848 deriving instance Monoid p => Monoid (Par1 p)
849
850 -- | Recursive calls of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
851 -- is enabled)
852 newtype Rec1 (f :: k -> Type) (p :: k) = Rec1 { unRec1 :: f p }
853 deriving ( Eq -- ^ @since 4.7.0.0
854 , Ord -- ^ @since 4.7.0.0
855 , Read -- ^ @since 4.7.0.0
856 , Show -- ^ @since 4.7.0.0
857 , Functor -- ^ @since 4.9.0.0
858 , Generic -- ^ @since 4.7.0.0
859 , Generic1 -- ^ @since 4.9.0.0
860 )
861
862 -- | @since 4.9.0.0
863 deriving instance Applicative f => Applicative (Rec1 f)
864
865 -- | @since 4.9.0.0
866 deriving instance Alternative f => Alternative (Rec1 f)
867
868 -- | @since 4.9.0.0
869 instance Monad f => Monad (Rec1 f) where
870 Rec1 x >>= f = Rec1 (x >>= \a -> unRec1 (f a))
871
872 -- | @since 4.9.0.0
873 deriving instance MonadPlus f => MonadPlus (Rec1 f)
874
875 -- | @since 4.12.0.0
876 deriving instance Semigroup (f p) => Semigroup (Rec1 f p)
877
878 -- | @since 4.12.0.0
879 deriving instance Monoid (f p) => Monoid (Rec1 f p)
880
881 -- | Constants, additional parameters and recursion of kind @*@
882 newtype K1 (i :: Type) c (p :: k) = K1 { unK1 :: c }
883 deriving ( Eq -- ^ @since 4.7.0.0
884 , Ord -- ^ @since 4.7.0.0
885 , Read -- ^ @since 4.7.0.0
886 , Show -- ^ @since 4.7.0.0
887 , Functor -- ^ @since 4.9.0.0
888 , Generic -- ^ @since 4.7.0.0
889 , Generic1 -- ^ @since 4.9.0.0
890 )
891
892 -- | @since 4.12.0.0
893 instance Monoid c => Applicative (K1 i c) where
894 pure _ = K1 mempty
895 liftA2 = \_ -> coerce (mappend :: c -> c -> c)
896 (<*>) = coerce (mappend :: c -> c -> c)
897
898 -- | @since 4.12.0.0
899 deriving instance Semigroup c => Semigroup (K1 i c p)
900
901 -- | @since 4.12.0.0
902 deriving instance Monoid c => Monoid (K1 i c p)
903
904 -- | @since 4.9.0.0
905 deriving instance Applicative f => Applicative (M1 i c f)
906
907 -- | @since 4.9.0.0
908 deriving instance Alternative f => Alternative (M1 i c f)
909
910 -- | @since 4.9.0.0
911 deriving instance Monad f => Monad (M1 i c f)
912
913 -- | @since 4.9.0.0
914 deriving instance MonadPlus f => MonadPlus (M1 i c f)
915
916 -- | @since 4.12.0.0
917 deriving instance Semigroup (f p) => Semigroup (M1 i c f p)
918
919 -- | @since 4.12.0.0
920 deriving instance Monoid (f p) => Monoid (M1 i c f p)
921
922 -- | Meta-information (constructor names, etc.)
923 newtype M1 (i :: Type) (c :: Meta) (f :: k -> Type) (p :: k) =
924 M1 { unM1 :: f p }
925 deriving ( Eq -- ^ @since 4.7.0.0
926 , Ord -- ^ @since 4.7.0.0
927 , Read -- ^ @since 4.7.0.0
928 , Show -- ^ @since 4.7.0.0
929 , Functor -- ^ @since 4.9.0.0
930 , Generic -- ^ @since 4.7.0.0
931 , Generic1 -- ^ @since 4.9.0.0
932 )
933
934 -- | Sums: encode choice between constructors
935 infixr 5 :+:
936 data (:+:) (f :: k -> Type) (g :: k -> Type) (p :: k) = L1 (f p) | R1 (g p)
937 deriving ( Eq -- ^ @since 4.7.0.0
938 , Ord -- ^ @since 4.7.0.0
939 , Read -- ^ @since 4.7.0.0
940 , Show -- ^ @since 4.7.0.0
941 , Functor -- ^ @since 4.9.0.0
942 , Generic -- ^ @since 4.7.0.0
943 , Generic1 -- ^ @since 4.9.0.0
944 )
945
946 -- | Products: encode multiple arguments to constructors
947 infixr 6 :*:
948 data (:*:) (f :: k -> Type) (g :: k -> Type) (p :: k) = f p :*: g p
949 deriving ( Eq -- ^ @since 4.7.0.0
950 , Ord -- ^ @since 4.7.0.0
951 , Read -- ^ @since 4.7.0.0
952 , Show -- ^ @since 4.7.0.0
953 , Functor -- ^ @since 4.9.0.0
954 , Generic -- ^ @since 4.7.0.0
955 , Generic1 -- ^ @since 4.9.0.0
956 )
957
958 -- | @since 4.9.0.0
959 instance (Applicative f, Applicative g) => Applicative (f :*: g) where
960 pure a = pure a :*: pure a
961 (f :*: g) <*> (x :*: y) = (f <*> x) :*: (g <*> y)
962 liftA2 f (a :*: b) (x :*: y) = liftA2 f a x :*: liftA2 f b y
963
964 -- | @since 4.9.0.0
965 instance (Alternative f, Alternative g) => Alternative (f :*: g) where
966 empty = empty :*: empty
967 (x1 :*: y1) <|> (x2 :*: y2) = (x1 <|> x2) :*: (y1 <|> y2)
968
969 -- | @since 4.9.0.0
970 instance (Monad f, Monad g) => Monad (f :*: g) where
971 (m :*: n) >>= f = (m >>= \a -> fstP (f a)) :*: (n >>= \a -> sndP (f a))
972 where
973 fstP (a :*: _) = a
974 sndP (_ :*: b) = b
975
976 -- | @since 4.9.0.0
977 instance (MonadPlus f, MonadPlus g) => MonadPlus (f :*: g)
978
979 -- | @since 4.12.0.0
980 instance (Semigroup (f p), Semigroup (g p)) => Semigroup ((f :*: g) p) where
981 (x1 :*: y1) <> (x2 :*: y2) = (x1 <> x2) :*: (y1 <> y2)
982
983 -- | @since 4.12.0.0
984 instance (Monoid (f p), Monoid (g p)) => Monoid ((f :*: g) p) where
985 mempty = mempty :*: mempty
986
987 -- | Composition of functors
988 infixr 7 :.:
989 newtype (:.:) (f :: k2 -> Type) (g :: k1 -> k2) (p :: k1) =
990 Comp1 { unComp1 :: f (g p) }
991 deriving ( Eq -- ^ @since 4.7.0.0
992 , Ord -- ^ @since 4.7.0.0
993 , Read -- ^ @since 4.7.0.0
994 , Show -- ^ @since 4.7.0.0
995 , Functor -- ^ @since 4.9.0.0
996 , Generic -- ^ @since 4.7.0.0
997 , Generic1 -- ^ @since 4.9.0.0
998 )
999
1000 -- | @since 4.9.0.0
1001 instance (Applicative f, Applicative g) => Applicative (f :.: g) where
1002 pure x = Comp1 (pure (pure x))
1003 Comp1 f <*> Comp1 x = Comp1 (liftA2 (<*>) f x)
1004 liftA2 f (Comp1 x) (Comp1 y) = Comp1 (liftA2 (liftA2 f) x y)
1005
1006 -- | @since 4.9.0.0
1007 instance (Alternative f, Applicative g) => Alternative (f :.: g) where
1008 empty = Comp1 empty
1009 (<|>) = coerce ((<|>) :: f (g a) -> f (g a) -> f (g a)) ::
1010 forall a . (f :.: g) a -> (f :.: g) a -> (f :.: g) a
1011
1012 -- | @since 4.12.0.0
1013 deriving instance Semigroup (f (g p)) => Semigroup ((f :.: g) p)
1014
1015 -- | @since 4.12.0.0
1016 deriving instance Monoid (f (g p)) => Monoid ((f :.: g) p)
1017
1018 -- | Constants of unlifted kinds
1019 --
1020 -- @since 4.9.0.0
1021 data family URec (a :: Type) (p :: k)
1022
1023 -- | Used for marking occurrences of 'Addr#'
1024 --
1025 -- @since 4.9.0.0
1026 data instance URec (Ptr ()) (p :: k) = UAddr { uAddr# :: Addr# }
1027 deriving ( Eq -- ^ @since 4.9.0.0
1028 , Ord -- ^ @since 4.9.0.0
1029 , Functor -- ^ @since 4.9.0.0
1030 , Generic -- ^ @since 4.9.0.0
1031 , Generic1 -- ^ @since 4.9.0.0
1032 )
1033
1034 -- | Used for marking occurrences of 'Char#'
1035 --
1036 -- @since 4.9.0.0
1037 data instance URec Char (p :: k) = UChar { uChar# :: Char# }
1038 deriving ( Eq -- ^ @since 4.9.0.0
1039 , Ord -- ^ @since 4.9.0.0
1040 , Show -- ^ @since 4.9.0.0
1041 , Functor -- ^ @since 4.9.0.0
1042 , Generic -- ^ @since 4.9.0.0
1043 , Generic1 -- ^ @since 4.9.0.0
1044 )
1045
1046 -- | Used for marking occurrences of 'Double#'
1047 --
1048 -- @since 4.9.0.0
1049 data instance URec Double (p :: k) = UDouble { uDouble# :: Double# }
1050 deriving ( Eq -- ^ @since 4.9.0.0
1051 , Ord -- ^ @since 4.9.0.0
1052 , Show -- ^ @since 4.9.0.0
1053 , Functor -- ^ @since 4.9.0.0
1054 , Generic -- ^ @since 4.9.0.0
1055 , Generic1 -- ^ @since 4.9.0.0
1056 )
1057
1058 -- | Used for marking occurrences of 'Float#'
1059 --
1060 -- @since 4.9.0.0
1061 data instance URec Float (p :: k) = UFloat { uFloat# :: Float# }
1062 deriving ( Eq, Ord, Show
1063 , Functor -- ^ @since 4.9.0.0
1064 , Generic
1065 , Generic1 -- ^ @since 4.9.0.0
1066 )
1067
1068 -- | Used for marking occurrences of 'Int#'
1069 --
1070 -- @since 4.9.0.0
1071 data instance URec Int (p :: k) = UInt { uInt# :: Int# }
1072 deriving ( Eq -- ^ @since 4.9.0.0
1073 , Ord -- ^ @since 4.9.0.0
1074 , Show -- ^ @since 4.9.0.0
1075 , Functor -- ^ @since 4.9.0.0
1076 , Generic -- ^ @since 4.9.0.0
1077 , Generic1 -- ^ @since 4.9.0.0
1078 )
1079
1080 -- | Used for marking occurrences of 'Word#'
1081 --
1082 -- @since 4.9.0.0
1083 data instance URec Word (p :: k) = UWord { uWord# :: Word# }
1084 deriving ( Eq -- ^ @since 4.9.0.0
1085 , Ord -- ^ @since 4.9.0.0
1086 , Show -- ^ @since 4.9.0.0
1087 , Functor -- ^ @since 4.9.0.0
1088 , Generic -- ^ @since 4.9.0.0
1089 , Generic1 -- ^ @since 4.9.0.0
1090 )
1091
1092 -- | Type synonym for @'URec' 'Addr#'@
1093 --
1094 -- @since 4.9.0.0
1095 type UAddr = URec (Ptr ())
1096 -- | Type synonym for @'URec' 'Char#'@
1097 --
1098 -- @since 4.9.0.0
1099 type UChar = URec Char
1100
1101 -- | Type synonym for @'URec' 'Double#'@
1102 --
1103 -- @since 4.9.0.0
1104 type UDouble = URec Double
1105
1106 -- | Type synonym for @'URec' 'Float#'@
1107 --
1108 -- @since 4.9.0.0
1109 type UFloat = URec Float
1110
1111 -- | Type synonym for @'URec' 'Int#'@
1112 --
1113 -- @since 4.9.0.0
1114 type UInt = URec Int
1115
1116 -- | Type synonym for @'URec' 'Word#'@
1117 --
1118 -- @since 4.9.0.0
1119 type UWord = URec Word
1120
1121 -- | Tag for K1: recursion (of kind @Type@)
1122 data R
1123
1124 -- | Type synonym for encoding recursion (of kind @Type@)
1125 type Rec0 = K1 R
1126
1127 -- | Tag for M1: datatype
1128 data D
1129 -- | Tag for M1: constructor
1130 data C
1131 -- | Tag for M1: record selector
1132 data S
1133
1134 -- | Type synonym for encoding meta-information for datatypes
1135 type D1 = M1 D
1136
1137 -- | Type synonym for encoding meta-information for constructors
1138 type C1 = M1 C
1139
1140 -- | Type synonym for encoding meta-information for record selectors
1141 type S1 = M1 S
1142
1143 -- | Class for datatypes that represent datatypes
1144 class Datatype d where
1145 -- | The name of the datatype (unqualified)
1146 datatypeName :: t d (f :: k -> Type) (a :: k) -> [Char]
1147 -- | The fully-qualified name of the module where the type is declared
1148 moduleName :: t d (f :: k -> Type) (a :: k) -> [Char]
1149 -- | The package name of the module where the type is declared
1150 --
1151 -- @since 4.9.0.0
1152 packageName :: t d (f :: k -> Type) (a :: k) -> [Char]
1153 -- | Marks if the datatype is actually a newtype
1154 --
1155 -- @since 4.7.0.0
1156 isNewtype :: t d (f :: k -> Type) (a :: k) -> Bool
1157 isNewtype _ = False
1158
1159 -- | @since 4.9.0.0
1160 instance (KnownSymbol n, KnownSymbol m, KnownSymbol p, SingI nt)
1161 => Datatype ('MetaData n m p nt) where
1162 datatypeName _ = symbolVal (Proxy :: Proxy n)
1163 moduleName _ = symbolVal (Proxy :: Proxy m)
1164 packageName _ = symbolVal (Proxy :: Proxy p)
1165 isNewtype _ = fromSing (sing :: Sing nt)
1166
1167 -- | Class for datatypes that represent data constructors
1168 class Constructor c where
1169 -- | The name of the constructor
1170 conName :: t c (f :: k -> Type) (a :: k) -> [Char]
1171
1172 -- | The fixity of the constructor
1173 conFixity :: t c (f :: k -> Type) (a :: k) -> Fixity
1174 conFixity _ = Prefix
1175
1176 -- | Marks if this constructor is a record
1177 conIsRecord :: t c (f :: k -> Type) (a :: k) -> Bool
1178 conIsRecord _ = False
1179
1180 -- | @since 4.9.0.0
1181 instance (KnownSymbol n, SingI f, SingI r)
1182 => Constructor ('MetaCons n f r) where
1183 conName _ = symbolVal (Proxy :: Proxy n)
1184 conFixity _ = fromSing (sing :: Sing f)
1185 conIsRecord _ = fromSing (sing :: Sing r)
1186
1187 -- | Datatype to represent the fixity of a constructor. An infix
1188 -- | declaration directly corresponds to an application of 'Infix'.
1189 data Fixity = Prefix | Infix Associativity Int
1190 deriving ( Eq -- ^ @since 4.6.0.0
1191 , Show -- ^ @since 4.6.0.0
1192 , Ord -- ^ @since 4.6.0.0
1193 , Read -- ^ @since 4.6.0.0
1194 , Generic -- ^ @since 4.7.0.0
1195 )
1196
1197 -- | This variant of 'Fixity' appears at the type level.
1198 --
1199 -- @since 4.9.0.0
1200 data FixityI = PrefixI | InfixI Associativity Nat
1201
1202 -- | Get the precedence of a fixity value.
1203 prec :: Fixity -> Int
1204 prec Prefix = 10
1205 prec (Infix _ n) = n
1206
1207 -- | Datatype to represent the associativity of a constructor
1208 data Associativity = LeftAssociative
1209 | RightAssociative
1210 | NotAssociative
1211 deriving ( Eq -- ^ @since 4.6.0.0
1212 , Show -- ^ @since 4.6.0.0
1213 , Ord -- ^ @since 4.6.0.0
1214 , Read -- ^ @since 4.6.0.0
1215 , Enum -- ^ @since 4.9.0.0
1216 , Bounded -- ^ @since 4.9.0.0
1217 , Ix -- ^ @since 4.9.0.0
1218 , Generic -- ^ @since 4.7.0.0
1219 )
1220
1221 -- | The unpackedness of a field as the user wrote it in the source code. For
1222 -- example, in the following data type:
1223 --
1224 -- @
1225 -- data E = ExampleConstructor Int
1226 -- {\-\# NOUNPACK \#-\} Int
1227 -- {\-\# UNPACK \#-\} Int
1228 -- @
1229 --
1230 -- The fields of @ExampleConstructor@ have 'NoSourceUnpackedness',
1231 -- 'SourceNoUnpack', and 'SourceUnpack', respectively.
1232 --
1233 -- @since 4.9.0.0
1234 data SourceUnpackedness = NoSourceUnpackedness
1235 | SourceNoUnpack
1236 | SourceUnpack
1237 deriving ( Eq -- ^ @since 4.9.0.0
1238 , Show -- ^ @since 4.9.0.0
1239 , Ord -- ^ @since 4.9.0.0
1240 , Read -- ^ @since 4.9.0.0
1241 , Enum -- ^ @since 4.9.0.0
1242 , Bounded -- ^ @since 4.9.0.0
1243 , Ix -- ^ @since 4.9.0.0
1244 , Generic -- ^ @since 4.9.0.0
1245 )
1246
1247 -- | The strictness of a field as the user wrote it in the source code. For
1248 -- example, in the following data type:
1249 --
1250 -- @
1251 -- data E = ExampleConstructor Int ~Int !Int
1252 -- @
1253 --
1254 -- The fields of @ExampleConstructor@ have 'NoSourceStrictness',
1255 -- 'SourceLazy', and 'SourceStrict', respectively.
1256 --
1257 -- @since 4.9.0.0
1258 data SourceStrictness = NoSourceStrictness
1259 | SourceLazy
1260 | SourceStrict
1261 deriving ( Eq -- ^ @since 4.9.0.0
1262 , Show -- ^ @since 4.9.0.0
1263 , Ord -- ^ @since 4.9.0.0
1264 , Read -- ^ @since 4.9.0.0
1265 , Enum -- ^ @since 4.9.0.0
1266 , Bounded -- ^ @since 4.9.0.0
1267 , Ix -- ^ @since 4.9.0.0
1268 , Generic -- ^ @since 4.9.0.0
1269 )
1270
1271 -- | The strictness that GHC infers for a field during compilation. Whereas
1272 -- there are nine different combinations of 'SourceUnpackedness' and
1273 -- 'SourceStrictness', the strictness that GHC decides will ultimately be one
1274 -- of lazy, strict, or unpacked. What GHC decides is affected both by what the
1275 -- user writes in the source code and by GHC flags. As an example, consider
1276 -- this data type:
1277 --
1278 -- @
1279 -- data E = ExampleConstructor {\-\# UNPACK \#-\} !Int !Int Int
1280 -- @
1281 --
1282 -- * If compiled without optimization or other language extensions, then the
1283 -- fields of @ExampleConstructor@ will have 'DecidedStrict', 'DecidedStrict',
1284 -- and 'DecidedLazy', respectively.
1285 --
1286 -- * If compiled with @-XStrictData@ enabled, then the fields will have
1287 -- 'DecidedStrict', 'DecidedStrict', and 'DecidedStrict', respectively.
1288 --
1289 -- * If compiled with @-O2@ enabled, then the fields will have 'DecidedUnpack',
1290 -- 'DecidedStrict', and 'DecidedLazy', respectively.
1291 --
1292 -- @since 4.9.0.0
1293 data DecidedStrictness = DecidedLazy
1294 | DecidedStrict
1295 | DecidedUnpack
1296 deriving ( Eq -- ^ @since 4.9.0.0
1297 , Show -- ^ @since 4.9.0.0
1298 , Ord -- ^ @since 4.9.0.0
1299 , Read -- ^ @since 4.9.0.0
1300 , Enum -- ^ @since 4.9.0.0
1301 , Bounded -- ^ @since 4.9.0.0
1302 , Ix -- ^ @since 4.9.0.0
1303 , Generic -- ^ @since 4.9.0.0
1304 )
1305
1306 -- | Class for datatypes that represent records
1307 class Selector s where
1308 -- | The name of the selector
1309 selName :: t s (f :: k -> Type) (a :: k) -> [Char]
1310 -- | The selector's unpackedness annotation (if any)
1311 --
1312 -- @since 4.9.0.0
1313 selSourceUnpackedness :: t s (f :: k -> Type) (a :: k) -> SourceUnpackedness
1314 -- | The selector's strictness annotation (if any)
1315 --
1316 -- @since 4.9.0.0
1317 selSourceStrictness :: t s (f :: k -> Type) (a :: k) -> SourceStrictness
1318 -- | The strictness that the compiler inferred for the selector
1319 --
1320 -- @since 4.9.0.0
1321 selDecidedStrictness :: t s (f :: k -> Type) (a :: k) -> DecidedStrictness
1322
1323 -- | @since 4.9.0.0
1324 instance (SingI mn, SingI su, SingI ss, SingI ds)
1325 => Selector ('MetaSel mn su ss ds) where
1326 selName _ = fromMaybe "" (fromSing (sing :: Sing mn))
1327 selSourceUnpackedness _ = fromSing (sing :: Sing su)
1328 selSourceStrictness _ = fromSing (sing :: Sing ss)
1329 selDecidedStrictness _ = fromSing (sing :: Sing ds)
1330
1331 -- | Representable types of kind @*@.
1332 -- This class is derivable in GHC with the @DeriveGeneric@ flag on.
1333 --
1334 -- A 'Generic' instance must satisfy the following laws:
1335 --
1336 -- @
1337 -- 'from' . 'to' ≡ 'id'
1338 -- 'to' . 'from' ≡ 'id'
1339 -- @
1340 class Generic a where
1341 -- | Generic representation type
1342 type Rep a :: Type -> Type
1343 -- | Convert from the datatype to its representation
1344 from :: a -> (Rep a) x
1345 -- | Convert from the representation to the datatype
1346 to :: (Rep a) x -> a
1347
1348
1349 -- | Representable types of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
1350 -- is enabled).
1351 -- This class is derivable in GHC with the @DeriveGeneric@ flag on.
1352 --
1353 -- A 'Generic1' instance must satisfy the following laws:
1354 --
1355 -- @
1356 -- 'from1' . 'to1' ≡ 'id'
1357 -- 'to1' . 'from1' ≡ 'id'
1358 -- @
1359 class Generic1 (f :: k -> Type) where
1360 -- | Generic representation type
1361 type Rep1 f :: k -> Type
1362 -- | Convert from the datatype to its representation
1363 from1 :: f a -> (Rep1 f) a
1364 -- | Convert from the representation to the datatype
1365 to1 :: (Rep1 f) a -> f a
1366
1367 --------------------------------------------------------------------------------
1368 -- Meta-data
1369 --------------------------------------------------------------------------------
1370
1371 -- | Datatype to represent metadata associated with a datatype (@MetaData@),
1372 -- constructor (@MetaCons@), or field selector (@MetaSel@).
1373 --
1374 -- * In @MetaData n m p nt@, @n@ is the datatype's name, @m@ is the module in
1375 -- which the datatype is defined, @p@ is the package in which the datatype
1376 -- is defined, and @nt@ is @'True@ if the datatype is a @newtype@.
1377 --
1378 -- * In @MetaCons n f s@, @n@ is the constructor's name, @f@ is its fixity,
1379 -- and @s@ is @'True@ if the constructor contains record selectors.
1380 --
1381 -- * In @MetaSel mn su ss ds@, if the field uses record syntax, then @mn@ is
1382 -- 'Just' the record name. Otherwise, @mn@ is 'Nothing'. @su@ and @ss@ are
1383 -- the field's unpackedness and strictness annotations, and @ds@ is the
1384 -- strictness that GHC infers for the field.
1385 --
1386 -- @since 4.9.0.0
1387 data Meta = MetaData Symbol Symbol Symbol Bool
1388 | MetaCons Symbol FixityI Bool
1389 | MetaSel (Maybe Symbol)
1390 SourceUnpackedness SourceStrictness DecidedStrictness
1391
1392 --------------------------------------------------------------------------------
1393 -- Derived instances
1394 --------------------------------------------------------------------------------
1395
1396 -- | @since 4.6.0.0
1397 deriving instance Generic [a]
1398
1399 -- | @since 4.6.0.0
1400 deriving instance Generic (NonEmpty a)
1401
1402 -- | @since 4.6.0.0
1403 deriving instance Generic (Maybe a)
1404
1405 -- | @since 4.6.0.0
1406 deriving instance Generic (Either a b)
1407
1408 -- | @since 4.6.0.0
1409 deriving instance Generic Bool
1410
1411 -- | @since 4.6.0.0
1412 deriving instance Generic Ordering
1413
1414 -- | @since 4.6.0.0
1415 deriving instance Generic (Proxy t)
1416
1417 -- | @since 4.6.0.0
1418 deriving instance Generic ()
1419
1420 -- | @since 4.6.0.0
1421 deriving instance Generic ((,) a b)
1422
1423 -- | @since 4.6.0.0
1424 deriving instance Generic ((,,) a b c)
1425
1426 -- | @since 4.6.0.0
1427 deriving instance Generic ((,,,) a b c d)
1428
1429 -- | @since 4.6.0.0
1430 deriving instance Generic ((,,,,) a b c d e)
1431
1432 -- | @since 4.6.0.0
1433 deriving instance Generic ((,,,,,) a b c d e f)
1434
1435 -- | @since 4.6.0.0
1436 deriving instance Generic ((,,,,,,) a b c d e f g)
1437
1438
1439 -- | @since 4.6.0.0
1440 deriving instance Generic1 []
1441
1442 -- | @since 4.6.0.0
1443 deriving instance Generic1 NonEmpty
1444
1445 -- | @since 4.6.0.0
1446 deriving instance Generic1 Maybe
1447
1448 -- | @since 4.6.0.0
1449 deriving instance Generic1 (Either a)
1450
1451 -- | @since 4.6.0.0
1452 deriving instance Generic1 Proxy
1453
1454 -- | @since 4.6.0.0
1455 deriving instance Generic1 ((,) a)
1456
1457 -- | @since 4.6.0.0
1458 deriving instance Generic1 ((,,) a b)
1459
1460 -- | @since 4.6.0.0
1461 deriving instance Generic1 ((,,,) a b c)
1462
1463 -- | @since 4.6.0.0
1464 deriving instance Generic1 ((,,,,) a b c d)
1465
1466 -- | @since 4.6.0.0
1467 deriving instance Generic1 ((,,,,,) a b c d e)
1468
1469 -- | @since 4.6.0.0
1470 deriving instance Generic1 ((,,,,,,) a b c d e f)
1471
1472 --------------------------------------------------------------------------------
1473 -- Copied from the singletons package
1474 --------------------------------------------------------------------------------
1475
1476 -- | The singleton kind-indexed data family.
1477 data family Sing (a :: k)
1478
1479 -- | A 'SingI' constraint is essentially an implicitly-passed singleton.
1480 -- If you need to satisfy this constraint with an explicit singleton, please
1481 -- see 'withSingI'.
1482 class SingI (a :: k) where
1483 -- | Produce the singleton explicitly. You will likely need the @ScopedTypeVariables@
1484 -- extension to use this method the way you want.
1485 sing :: Sing a
1486
1487 -- | The 'SingKind' class is essentially a /kind/ class. It classifies all kinds
1488 -- for which singletons are defined. The class supports converting between a singleton
1489 -- type and the base (unrefined) type which it is built from.
1490 class SingKind k where
1491 -- | Get a base type from a proxy for the promoted kind. For example,
1492 -- @DemoteRep Bool@ will be the type @Bool@.
1493 type DemoteRep k :: Type
1494
1495 -- | Convert a singleton to its unrefined version.
1496 fromSing :: Sing (a :: k) -> DemoteRep k
1497
1498 -- Singleton symbols
1499 data instance Sing (s :: Symbol) where
1500 SSym :: KnownSymbol s => Sing s
1501
1502 -- | @since 4.9.0.0
1503 instance KnownSymbol a => SingI a where sing = SSym
1504
1505 -- | @since 4.9.0.0
1506 instance SingKind Symbol where
1507 type DemoteRep Symbol = String
1508 fromSing (SSym :: Sing s) = symbolVal (Proxy :: Proxy s)
1509
1510 -- Singleton booleans
1511 data instance Sing (a :: Bool) where
1512 STrue :: Sing 'True
1513 SFalse :: Sing 'False
1514
1515 -- | @since 4.9.0.0
1516 instance SingI 'True where sing = STrue
1517
1518 -- | @since 4.9.0.0
1519 instance SingI 'False where sing = SFalse
1520
1521 -- | @since 4.9.0.0
1522 instance SingKind Bool where
1523 type DemoteRep Bool = Bool
1524 fromSing STrue = True
1525 fromSing SFalse = False
1526
1527 -- Singleton Maybe
1528 data instance Sing (b :: Maybe a) where
1529 SNothing :: Sing 'Nothing
1530 SJust :: Sing a -> Sing ('Just a)
1531
1532 -- | @since 4.9.0.0
1533 instance SingI 'Nothing where sing = SNothing
1534
1535 -- | @since 4.9.0.0
1536 instance SingI a => SingI ('Just a) where sing = SJust sing
1537
1538 -- | @since 4.9.0.0
1539 instance SingKind a => SingKind (Maybe a) where
1540 type DemoteRep (Maybe a) = Maybe (DemoteRep a)
1541 fromSing SNothing = Nothing
1542 fromSing (SJust a) = Just (fromSing a)
1543
1544 -- Singleton Fixity
1545 data instance Sing (a :: FixityI) where
1546 SPrefix :: Sing 'PrefixI
1547 SInfix :: Sing a -> Integer -> Sing ('InfixI a n)
1548
1549 -- | @since 4.9.0.0
1550 instance SingI 'PrefixI where sing = SPrefix
1551
1552 -- | @since 4.9.0.0
1553 instance (SingI a, KnownNat n) => SingI ('InfixI a n) where
1554 sing = SInfix (sing :: Sing a) (natVal (Proxy :: Proxy n))
1555
1556 -- | @since 4.9.0.0
1557 instance SingKind FixityI where
1558 type DemoteRep FixityI = Fixity
1559 fromSing SPrefix = Prefix
1560 fromSing (SInfix a n) = Infix (fromSing a) (I# (integerToInt n))
1561
1562 -- Singleton Associativity
1563 data instance Sing (a :: Associativity) where
1564 SLeftAssociative :: Sing 'LeftAssociative
1565 SRightAssociative :: Sing 'RightAssociative
1566 SNotAssociative :: Sing 'NotAssociative
1567
1568 -- | @since 4.9.0.0
1569 instance SingI 'LeftAssociative where sing = SLeftAssociative
1570
1571 -- | @since 4.9.0.0
1572 instance SingI 'RightAssociative where sing = SRightAssociative
1573
1574 -- | @since 4.9.0.0
1575 instance SingI 'NotAssociative where sing = SNotAssociative
1576
1577 -- | @since 4.0.0.0
1578 instance SingKind Associativity where
1579 type DemoteRep Associativity = Associativity
1580 fromSing SLeftAssociative = LeftAssociative
1581 fromSing SRightAssociative = RightAssociative
1582 fromSing SNotAssociative = NotAssociative
1583
1584 -- Singleton SourceUnpackedness
1585 data instance Sing (a :: SourceUnpackedness) where
1586 SNoSourceUnpackedness :: Sing 'NoSourceUnpackedness
1587 SSourceNoUnpack :: Sing 'SourceNoUnpack
1588 SSourceUnpack :: Sing 'SourceUnpack
1589
1590 -- | @since 4.9.0.0
1591 instance SingI 'NoSourceUnpackedness where sing = SNoSourceUnpackedness
1592
1593 -- | @since 4.9.0.0
1594 instance SingI 'SourceNoUnpack where sing = SSourceNoUnpack
1595
1596 -- | @since 4.9.0.0
1597 instance SingI 'SourceUnpack where sing = SSourceUnpack
1598
1599 -- | @since 4.9.0.0
1600 instance SingKind SourceUnpackedness where
1601 type DemoteRep SourceUnpackedness = SourceUnpackedness
1602 fromSing SNoSourceUnpackedness = NoSourceUnpackedness
1603 fromSing SSourceNoUnpack = SourceNoUnpack
1604 fromSing SSourceUnpack = SourceUnpack
1605
1606 -- Singleton SourceStrictness
1607 data instance Sing (a :: SourceStrictness) where
1608 SNoSourceStrictness :: Sing 'NoSourceStrictness
1609 SSourceLazy :: Sing 'SourceLazy
1610 SSourceStrict :: Sing 'SourceStrict
1611
1612 -- | @since 4.9.0.0
1613 instance SingI 'NoSourceStrictness where sing = SNoSourceStrictness
1614
1615 -- | @since 4.9.0.0
1616 instance SingI 'SourceLazy where sing = SSourceLazy
1617
1618 -- | @since 4.9.0.0
1619 instance SingI 'SourceStrict where sing = SSourceStrict
1620
1621 -- | @since 4.9.0.0
1622 instance SingKind SourceStrictness where
1623 type DemoteRep SourceStrictness = SourceStrictness
1624 fromSing SNoSourceStrictness = NoSourceStrictness
1625 fromSing SSourceLazy = SourceLazy
1626 fromSing SSourceStrict = SourceStrict
1627
1628 -- Singleton DecidedStrictness
1629 data instance Sing (a :: DecidedStrictness) where
1630 SDecidedLazy :: Sing 'DecidedLazy
1631 SDecidedStrict :: Sing 'DecidedStrict
1632 SDecidedUnpack :: Sing 'DecidedUnpack
1633
1634 -- | @since 4.9.0.0
1635 instance SingI 'DecidedLazy where sing = SDecidedLazy
1636
1637 -- | @since 4.9.0.0
1638 instance SingI 'DecidedStrict where sing = SDecidedStrict
1639
1640 -- | @since 4.9.0.0
1641 instance SingI 'DecidedUnpack where sing = SDecidedUnpack
1642
1643 -- | @since 4.9.0.0
1644 instance SingKind DecidedStrictness where
1645 type DemoteRep DecidedStrictness = DecidedStrictness
1646 fromSing SDecidedLazy = DecidedLazy
1647 fromSing SDecidedStrict = DecidedStrict
1648 fromSing SDecidedUnpack = DecidedUnpack