9ac05286ab957c0dc0fcca058ed7429adc3e687f
[ghc.git] / libraries / base / GHC / Generics.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE DataKinds #-}
3 {-# LANGUAGE DeriveFunctor #-}
4 {-# LANGUAGE DeriveGeneric #-}
5 {-# LANGUAGE EmptyDataDeriving #-}
6 {-# LANGUAGE FlexibleContexts #-}
7 {-# LANGUAGE FlexibleInstances #-}
8 {-# LANGUAGE GADTs #-}
9 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
10 {-# LANGUAGE KindSignatures #-}
11 {-# LANGUAGE MagicHash #-}
12 {-# LANGUAGE NoImplicitPrelude #-}
13 {-# LANGUAGE PolyKinds #-}
14 {-# LANGUAGE ScopedTypeVariables #-}
15 {-# LANGUAGE StandaloneDeriving #-}
16 {-# LANGUAGE Trustworthy #-}
17 {-# LANGUAGE TypeFamilies #-}
18 {-# LANGUAGE TypeInType #-}
19 {-# LANGUAGE TypeOperators #-}
20 {-# LANGUAGE TypeSynonymInstances #-}
21 {-# LANGUAGE UndecidableInstances #-}
22
23 -----------------------------------------------------------------------------
24 -- |
25 -- Module : GHC.Generics
26 -- Copyright : (c) Universiteit Utrecht 2010-2011, University of Oxford 2012-2014
27 -- License : see libraries/base/LICENSE
28 --
29 -- Maintainer : libraries@haskell.org
30 -- Stability : internal
31 -- Portability : non-portable
32 --
33 -- @since 4.6.0.0
34 --
35 -- If you're using @GHC.Generics@, you should consider using the
36 -- <http://hackage.haskell.org/package/generic-deriving> package, which
37 -- contains many useful generic functions.
38
39 module GHC.Generics (
40 -- * Introduction
41 --
42 -- |
43 --
44 -- Datatype-generic functions are based on the idea of converting values of
45 -- a datatype @T@ into corresponding values of a (nearly) isomorphic type @'Rep' T@.
46 -- The type @'Rep' T@ is
47 -- built from a limited set of type constructors, all provided by this module. A
48 -- datatype-generic function is then an overloaded function with instances
49 -- for most of these type constructors, together with a wrapper that performs
50 -- the mapping between @T@ and @'Rep' T@. By using this technique, we merely need
51 -- a few generic instances in order to implement functionality that works for any
52 -- representable type.
53 --
54 -- Representable types are collected in the 'Generic' class, which defines the
55 -- associated type 'Rep' as well as conversion functions 'from' and 'to'.
56 -- Typically, you will not define 'Generic' instances by hand, but have the compiler
57 -- derive them for you.
58
59 -- ** Representing datatypes
60 --
61 -- |
62 --
63 -- The key to defining your own datatype-generic functions is to understand how to
64 -- represent datatypes using the given set of type constructors.
65 --
66 -- Let us look at an example first:
67 --
68 -- @
69 -- data Tree a = Leaf a | Node (Tree a) (Tree a)
70 -- deriving 'Generic'
71 -- @
72 --
73 -- The above declaration (which requires the language pragma @DeriveGeneric@)
74 -- causes the following representation to be generated:
75 --
76 -- @
77 -- instance 'Generic' (Tree a) where
78 -- type 'Rep' (Tree a) =
79 -- 'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)
80 -- ('C1' ('MetaCons \"Leaf\" 'PrefixI 'False)
81 -- ('S1' ('MetaSel 'Nothing
82 -- 'NoSourceUnpackedness
83 -- 'NoSourceStrictness
84 -- 'DecidedLazy)
85 -- ('Rec0' a))
86 -- ':+:'
87 -- 'C1' ('MetaCons \"Node\" 'PrefixI 'False)
88 -- ('S1' ('MetaSel 'Nothing
89 -- 'NoSourceUnpackedness
90 -- 'NoSourceStrictness
91 -- 'DecidedLazy)
92 -- ('Rec0' (Tree a))
93 -- ':*:'
94 -- 'S1' ('MetaSel 'Nothing
95 -- 'NoSourceUnpackedness
96 -- 'NoSourceStrictness
97 -- 'DecidedLazy)
98 -- ('Rec0' (Tree a))))
99 -- ...
100 -- @
101 --
102 -- /Hint:/ You can obtain information about the code being generated from GHC by passing
103 -- the @-ddump-deriv@ flag. In GHCi, you can expand a type family such as 'Rep' using
104 -- the @:kind!@ command.
105 --
106 -- This is a lot of information! However, most of it is actually merely meta-information
107 -- that makes names of datatypes and constructors and more available on the type level.
108 --
109 -- Here is a reduced representation for 'Tree' with nearly all meta-information removed,
110 -- for now keeping only the most essential aspects:
111 --
112 -- @
113 -- instance 'Generic' (Tree a) where
114 -- type 'Rep' (Tree a) =
115 -- 'Rec0' a
116 -- ':+:'
117 -- ('Rec0' (Tree a) ':*:' 'Rec0' (Tree a))
118 -- @
119 --
120 -- The @Tree@ datatype has two constructors. The representation of individual constructors
121 -- is combined using the binary type constructor ':+:'.
122 --
123 -- The first constructor consists of a single field, which is the parameter @a@. This is
124 -- represented as @'Rec0' a@.
125 --
126 -- The second constructor consists of two fields. Each is a recursive field of type @Tree a@,
127 -- represented as @'Rec0' (Tree a)@. Representations of individual fields are combined using
128 -- the binary type constructor ':*:'.
129 --
130 -- Now let us explain the additional tags being used in the complete representation:
131 --
132 -- * The @'S1' ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness
133 -- 'DecidedLazy)@ tag indicates several things. The @'Nothing@ indicates
134 -- that there is no record field selector associated with this field of
135 -- the constructor (if there were, it would have been marked @'Just
136 -- \"recordName\"@ instead). The other types contain meta-information on
137 -- the field's strictness:
138 --
139 -- * There is no @{\-\# UNPACK \#-\}@ or @{\-\# NOUNPACK \#-\}@ annotation
140 -- in the source, so it is tagged with @'NoSourceUnpackedness@.
141 --
142 -- * There is no strictness (@!@) or laziness (@~@) annotation in the
143 -- source, so it is tagged with @'NoSourceStrictness@.
144 --
145 -- * The compiler infers that the field is lazy, so it is tagged with
146 -- @'DecidedLazy@. Bear in mind that what the compiler decides may be
147 -- quite different from what is written in the source. See
148 -- 'DecidedStrictness' for a more detailed explanation.
149 --
150 -- The @'MetaSel@ type is also an instance of the type class 'Selector',
151 -- which can be used to obtain information about the field at the value
152 -- level.
153 --
154 -- * The @'C1' ('MetaCons \"Leaf\" 'PrefixI 'False)@ and
155 -- @'C1' ('MetaCons \"Node\" 'PrefixI 'False)@ invocations indicate that the enclosed part is
156 -- the representation of the first and second constructor of datatype @Tree@, respectively.
157 -- Here, the meta-information regarding constructor names, fixity and whether
158 -- it has named fields or not is encoded at the type level. The @'MetaCons@
159 -- type is also an instance of the type class 'Constructor'. This type class can be used
160 -- to obtain information about the constructor at the value level.
161 --
162 -- * The @'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)@ tag
163 -- indicates that the enclosed part is the representation of the
164 -- datatype @Tree@. Again, the meta-information is encoded at the type level.
165 -- The @'MetaData@ type is an instance of class 'Datatype', which
166 -- can be used to obtain the name of a datatype, the module it has been
167 -- defined in, the package it is located under, and whether it has been
168 -- defined using @data@ or @newtype@ at the value level.
169
170 -- ** Derived and fundamental representation types
171 --
172 -- |
173 --
174 -- There are many datatype-generic functions that do not distinguish between positions that
175 -- are parameters or positions that are recursive calls. There are also many datatype-generic
176 -- functions that do not care about the names of datatypes and constructors at all. To keep
177 -- the number of cases to consider in generic functions in such a situation to a minimum,
178 -- it turns out that many of the type constructors introduced above are actually synonyms,
179 -- defining them to be variants of a smaller set of constructors.
180
181 -- *** Individual fields of constructors: 'K1'
182 --
183 -- |
184 --
185 -- The type constructor 'Rec0' is a variant of 'K1':
186 --
187 -- @
188 -- type 'Rec0' = 'K1' 'R'
189 -- @
190 --
191 -- Here, 'R' is a type-level proxy that does not have any associated values.
192 --
193 -- There used to be another variant of 'K1' (namely 'Par0'), but it has since
194 -- been deprecated.
195
196 -- *** Meta information: 'M1'
197 --
198 -- |
199 --
200 -- The type constructors 'S1', 'C1' and 'D1' are all variants of 'M1':
201 --
202 -- @
203 -- type 'S1' = 'M1' 'S'
204 -- type 'C1' = 'M1' 'C'
205 -- type 'D1' = 'M1' 'D'
206 -- @
207 --
208 -- The types 'S', 'C' and 'D' are once again type-level proxies, just used to create
209 -- several variants of 'M1'.
210
211 -- *** Additional generic representation type constructors
212 --
213 -- |
214 --
215 -- Next to 'K1', 'M1', ':+:' and ':*:' there are a few more type constructors that occur
216 -- in the representations of other datatypes.
217
218 -- **** Empty datatypes: 'V1'
219 --
220 -- |
221 --
222 -- For empty datatypes, 'V1' is used as a representation. For example,
223 --
224 -- @
225 -- data Empty deriving 'Generic'
226 -- @
227 --
228 -- yields
229 --
230 -- @
231 -- instance 'Generic' Empty where
232 -- type 'Rep' Empty =
233 -- 'D1' ('MetaData \"Empty\" \"Main\" \"package-name\" 'False) 'V1'
234 -- @
235
236 -- **** Constructors without fields: 'U1'
237 --
238 -- |
239 --
240 -- If a constructor has no arguments, then 'U1' is used as its representation. For example
241 -- the representation of 'Bool' is
242 --
243 -- @
244 -- instance 'Generic' Bool where
245 -- type 'Rep' Bool =
246 -- 'D1' ('MetaData \"Bool\" \"Data.Bool\" \"package-name\" 'False)
247 -- ('C1' ('MetaCons \"False\" 'PrefixI 'False) 'U1' ':+:' 'C1' ('MetaCons \"True\" 'PrefixI 'False) 'U1')
248 -- @
249
250 -- *** Representation of types with many constructors or many fields
251 --
252 -- |
253 --
254 -- As ':+:' and ':*:' are just binary operators, one might ask what happens if the
255 -- datatype has more than two constructors, or a constructor with more than two
256 -- fields. The answer is simple: the operators are used several times, to combine
257 -- all the constructors and fields as needed. However, users /should not rely on
258 -- a specific nesting strategy/ for ':+:' and ':*:' being used. The compiler is
259 -- free to choose any nesting it prefers. (In practice, the current implementation
260 -- tries to produce a more-or-less balanced nesting, so that the traversal of
261 -- the structure of the datatype from the root to a particular component can be
262 -- performed in logarithmic rather than linear time.)
263
264 -- ** Defining datatype-generic functions
265 --
266 -- |
267 --
268 -- A datatype-generic function comprises two parts:
269 --
270 -- 1. /Generic instances/ for the function, implementing it for most of the representation
271 -- type constructors introduced above.
272 --
273 -- 2. A /wrapper/ that for any datatype that is in `Generic`, performs the conversion
274 -- between the original value and its `Rep`-based representation and then invokes the
275 -- generic instances.
276 --
277 -- As an example, let us look at a function 'encode' that produces a naive, but lossless
278 -- bit encoding of values of various datatypes. So we are aiming to define a function
279 --
280 -- @
281 -- encode :: 'Generic' a => a -> [Bool]
282 -- @
283 --
284 -- where we use 'Bool' as our datatype for bits.
285 --
286 -- For part 1, we define a class @Encode'@. Perhaps surprisingly, this class is parameterized
287 -- over a type constructor @f@ of kind @* -> *@. This is a technicality: all the representation
288 -- type constructors operate with kind @* -> *@ as base kind. But the type argument is never
289 -- being used. This may be changed at some point in the future. The class has a single method,
290 -- and we use the type we want our final function to have, but we replace the occurrences of
291 -- the generic type argument @a@ with @f p@ (where the @p@ is any argument; it will not be used).
292 --
293 -- > class Encode' f where
294 -- > encode' :: f p -> [Bool]
295 --
296 -- With the goal in mind to make @encode@ work on @Tree@ and other datatypes, we now define
297 -- instances for the representation type constructors 'V1', 'U1', ':+:', ':*:', 'K1', and 'M1'.
298
299 -- *** Definition of the generic representation types
300 --
301 -- |
302 --
303 -- In order to be able to do this, we need to know the actual definitions of these types:
304 --
305 -- @
306 -- data 'V1' p -- lifted version of Empty
307 -- data 'U1' p = 'U1' -- lifted version of ()
308 -- data (':+:') f g p = 'L1' (f p) | 'R1' (g p) -- lifted version of 'Either'
309 -- data (':*:') f g p = (f p) ':*:' (g p) -- lifted version of (,)
310 -- newtype 'K1' i c p = 'K1' { 'unK1' :: c } -- a container for a c
311 -- newtype 'M1' i t f p = 'M1' { 'unM1' :: f p } -- a wrapper
312 -- @
313 --
314 -- So, 'U1' is just the unit type, ':+:' is just a binary choice like 'Either',
315 -- ':*:' is a binary pair like the pair constructor @(,)@, and 'K1' is a value
316 -- of a specific type @c@, and 'M1' wraps a value of the generic type argument,
317 -- which in the lifted world is an @f p@ (where we do not care about @p@).
318
319 -- *** Generic instances
320 --
321 -- |
322 --
323 -- The instance for 'V1' is slightly awkward (but also rarely used):
324 --
325 -- @
326 -- instance Encode' 'V1' where
327 -- encode' x = undefined
328 -- @
329 --
330 -- There are no values of type @V1 p@ to pass (except undefined), so this is
331 -- actually impossible. One can ask why it is useful to define an instance for
332 -- 'V1' at all in this case? Well, an empty type can be used as an argument to
333 -- a non-empty type, and you might still want to encode the resulting type.
334 -- As a somewhat contrived example, consider @[Empty]@, which is not an empty
335 -- type, but contains just the empty list. The 'V1' instance ensures that we
336 -- can call the generic function on such types.
337 --
338 -- There is exactly one value of type 'U1', so encoding it requires no
339 -- knowledge, and we can use zero bits:
340 --
341 -- @
342 -- instance Encode' 'U1' where
343 -- encode' 'U1' = []
344 -- @
345 --
346 -- In the case for ':+:', we produce 'False' or 'True' depending on whether
347 -- the constructor of the value provided is located on the left or on the right:
348 --
349 -- @
350 -- instance (Encode' f, Encode' g) => Encode' (f ':+:' g) where
351 -- encode' ('L1' x) = False : encode' x
352 -- encode' ('R1' x) = True : encode' x
353 -- @
354 --
355 -- (Note that this encoding strategy may not be reliable across different
356 -- versions of GHC. Recall that the compiler is free to choose any nesting
357 -- of ':+:' it chooses, so if GHC chooses @(a ':+:' b) ':+:' c@, then the
358 -- encoding for @a@ would be @[False, False]@, @b@ would be @[False, True]@,
359 -- and @c@ would be @[True]@. However, if GHC chooses @a ':+:' (b ':+:' c)@,
360 -- then the encoding for @a@ would be @[False]@, @b@ would be @[True, False]@,
361 -- and @c@ would be @[True, True]@.)
362 --
363 -- In the case for ':*:', we append the encodings of the two subcomponents:
364 --
365 -- @
366 -- instance (Encode' f, Encode' g) => Encode' (f ':*:' g) where
367 -- encode' (x ':*:' y) = encode' x ++ encode' y
368 -- @
369 --
370 -- The case for 'K1' is rather interesting. Here, we call the final function
371 -- 'encode' that we yet have to define, recursively. We will use another type
372 -- class 'Encode' for that function:
373 --
374 -- @
375 -- instance (Encode c) => Encode' ('K1' i c) where
376 -- encode' ('K1' x) = encode x
377 -- @
378 --
379 -- Note how 'Par0' and 'Rec0' both being mapped to 'K1' allows us to define
380 -- a uniform instance here.
381 --
382 -- Similarly, we can define a uniform instance for 'M1', because we completely
383 -- disregard all meta-information:
384 --
385 -- @
386 -- instance (Encode' f) => Encode' ('M1' i t f) where
387 -- encode' ('M1' x) = encode' x
388 -- @
389 --
390 -- Unlike in 'K1', the instance for 'M1' refers to 'encode'', not 'encode'.
391
392 -- *** The wrapper and generic default
393 --
394 -- |
395 --
396 -- We now define class 'Encode' for the actual 'encode' function:
397 --
398 -- @
399 -- class Encode a where
400 -- encode :: a -> [Bool]
401 -- default encode :: (Generic a, Encode' (Rep a)) => a -> [Bool]
402 -- encode x = encode' ('from' x)
403 -- @
404 --
405 -- The incoming 'x' is converted using 'from', then we dispatch to the
406 -- generic instances using 'encode''. We use this as a default definition
407 -- for 'encode'. We need the 'default encode' signature because ordinary
408 -- Haskell default methods must not introduce additional class constraints,
409 -- but our generic default does.
410 --
411 -- Defining a particular instance is now as simple as saying
412 --
413 -- @
414 -- instance (Encode a) => Encode (Tree a)
415 -- @
416 --
417 #if 0
418 -- /TODO:/ Add usage example?
419 --
420 #endif
421 -- The generic default is being used. In the future, it will hopefully be
422 -- possible to use @deriving Encode@ as well, but GHC does not yet support
423 -- that syntax for this situation.
424 --
425 -- Having 'Encode' as a class has the advantage that we can define
426 -- non-generic special cases, which is particularly useful for abstract
427 -- datatypes that have no structural representation. For example, given
428 -- a suitable integer encoding function 'encodeInt', we can define
429 --
430 -- @
431 -- instance Encode Int where
432 -- encode = encodeInt
433 -- @
434
435 -- *** Omitting generic instances
436 --
437 -- |
438 --
439 -- It is not always required to provide instances for all the generic
440 -- representation types, but omitting instances restricts the set of
441 -- datatypes the functions will work for:
442 --
443 -- * If no ':+:' instance is given, the function may still work for
444 -- empty datatypes or datatypes that have a single constructor,
445 -- but will fail on datatypes with more than one constructor.
446 --
447 -- * If no ':*:' instance is given, the function may still work for
448 -- datatypes where each constructor has just zero or one field,
449 -- in particular for enumeration types.
450 --
451 -- * If no 'K1' instance is given, the function may still work for
452 -- enumeration types, where no constructor has any fields.
453 --
454 -- * If no 'V1' instance is given, the function may still work for
455 -- any datatype that is not empty.
456 --
457 -- * If no 'U1' instance is given, the function may still work for
458 -- any datatype where each constructor has at least one field.
459 --
460 -- An 'M1' instance is always required (but it can just ignore the
461 -- meta-information, as is the case for 'encode' above).
462 #if 0
463 -- *** Using meta-information
464 --
465 -- |
466 --
467 -- TODO
468 #endif
469 -- ** Generic constructor classes
470 --
471 -- |
472 --
473 -- Datatype-generic functions as defined above work for a large class
474 -- of datatypes, including parameterized datatypes. (We have used 'Tree'
475 -- as our example above, which is of kind @* -> *@.) However, the
476 -- 'Generic' class ranges over types of kind @*@, and therefore, the
477 -- resulting generic functions (such as 'encode') must be parameterized
478 -- by a generic type argument of kind @*@.
479 --
480 -- What if we want to define generic classes that range over type
481 -- constructors (such as 'Functor', 'Traversable', or 'Foldable')?
482
483 -- *** The 'Generic1' class
484 --
485 -- |
486 --
487 -- Like 'Generic', there is a class 'Generic1' that defines a
488 -- representation 'Rep1' and conversion functions 'from1' and 'to1',
489 -- only that 'Generic1' ranges over types of kind @* -> *@. (More generally,
490 -- it can range over types of kind @k -> *@, for any kind @k@, if the
491 -- @PolyKinds@ extension is enabled. More on this later.)
492 -- The 'Generic1' class is also derivable.
493 --
494 -- The representation 'Rep1' is ever so slightly different from 'Rep'.
495 -- Let us look at 'Tree' as an example again:
496 --
497 -- @
498 -- data Tree a = Leaf a | Node (Tree a) (Tree a)
499 -- deriving 'Generic1'
500 -- @
501 --
502 -- The above declaration causes the following representation to be generated:
503 --
504 -- @
505 -- instance 'Generic1' Tree where
506 -- type 'Rep1' Tree =
507 -- 'D1' ('MetaData \"Tree\" \"Main\" \"package-name\" 'False)
508 -- ('C1' ('MetaCons \"Leaf\" 'PrefixI 'False)
509 -- ('S1' ('MetaSel 'Nothing
510 -- 'NoSourceUnpackedness
511 -- 'NoSourceStrictness
512 -- 'DecidedLazy)
513 -- 'Par1')
514 -- ':+:'
515 -- 'C1' ('MetaCons \"Node\" 'PrefixI 'False)
516 -- ('S1' ('MetaSel 'Nothing
517 -- 'NoSourceUnpackedness
518 -- 'NoSourceStrictness
519 -- 'DecidedLazy)
520 -- ('Rec1' Tree)
521 -- ':*:'
522 -- 'S1' ('MetaSel 'Nothing
523 -- 'NoSourceUnpackedness
524 -- 'NoSourceStrictness
525 -- 'DecidedLazy)
526 -- ('Rec1' Tree)))
527 -- ...
528 -- @
529 --
530 -- The representation reuses 'D1', 'C1', 'S1' (and thereby 'M1') as well
531 -- as ':+:' and ':*:' from 'Rep'. (This reusability is the reason that we
532 -- carry around the dummy type argument for kind-@*@-types, but there are
533 -- already enough different names involved without duplicating each of
534 -- these.)
535 --
536 -- What's different is that we now use 'Par1' to refer to the parameter
537 -- (and that parameter, which used to be @a@), is not mentioned explicitly
538 -- by name anywhere; and we use 'Rec1' to refer to a recursive use of @Tree a@.
539
540 -- *** Representation of @* -> *@ types
541 --
542 -- |
543 --
544 -- Unlike 'Rec0', the 'Par1' and 'Rec1' type constructors do not
545 -- map to 'K1'. They are defined directly, as follows:
546 --
547 -- @
548 -- newtype 'Par1' p = 'Par1' { 'unPar1' :: p } -- gives access to parameter p
549 -- newtype 'Rec1' f p = 'Rec1' { 'unRec1' :: f p } -- a wrapper
550 -- @
551 --
552 -- In 'Par1', the parameter @p@ is used for the first time, whereas 'Rec1' simply
553 -- wraps an application of @f@ to @p@.
554 --
555 -- Note that 'K1' (in the guise of 'Rec0') can still occur in a 'Rep1' representation,
556 -- namely when the datatype has a field that does not mention the parameter.
557 --
558 -- The declaration
559 --
560 -- @
561 -- data WithInt a = WithInt Int a
562 -- deriving 'Generic1'
563 -- @
564 --
565 -- yields
566 --
567 -- @
568 -- instance 'Generic1' WithInt where
569 -- type 'Rep1' WithInt =
570 -- 'D1' ('MetaData \"WithInt\" \"Main\" \"package-name\" 'False)
571 -- ('C1' ('MetaCons \"WithInt\" 'PrefixI 'False)
572 -- ('S1' ('MetaSel 'Nothing
573 -- 'NoSourceUnpackedness
574 -- 'NoSourceStrictness
575 -- 'DecidedLazy)
576 -- ('Rec0' Int)
577 -- ':*:'
578 -- 'S1' ('MetaSel 'Nothing
579 -- 'NoSourceUnpackedness
580 -- 'NoSourceStrictness
581 -- 'DecidedLazy)
582 -- 'Par1'))
583 -- @
584 --
585 -- If the parameter @a@ appears underneath a composition of other type constructors,
586 -- then the representation involves composition, too:
587 --
588 -- @
589 -- data Rose a = Fork a [Rose a]
590 -- @
591 --
592 -- yields
593 --
594 -- @
595 -- instance 'Generic1' Rose where
596 -- type 'Rep1' Rose =
597 -- 'D1' ('MetaData \"Rose\" \"Main\" \"package-name\" 'False)
598 -- ('C1' ('MetaCons \"Fork\" 'PrefixI 'False)
599 -- ('S1' ('MetaSel 'Nothing
600 -- 'NoSourceUnpackedness
601 -- 'NoSourceStrictness
602 -- 'DecidedLazy)
603 -- 'Par1'
604 -- ':*:'
605 -- 'S1' ('MetaSel 'Nothing
606 -- 'NoSourceUnpackedness
607 -- 'NoSourceStrictness
608 -- 'DecidedLazy)
609 -- ([] ':.:' 'Rec1' Rose)))
610 -- @
611 --
612 -- where
613 --
614 -- @
615 -- newtype (':.:') f g p = 'Comp1' { 'unComp1' :: f (g p) }
616 -- @
617
618 -- *** Representation of @k -> *@ types
619 --
620 -- |
621 --
622 -- The 'Generic1' class can be generalized to range over types of kind
623 -- @k -> *@, for any kind @k@. To do so, derive a 'Generic1' instance with the
624 -- @PolyKinds@ extension enabled. For example, the declaration
625 --
626 -- @
627 -- data Proxy (a :: k) = Proxy deriving 'Generic1'
628 -- @
629 --
630 -- yields a slightly different instance depending on whether @PolyKinds@ is
631 -- enabled. If compiled without @PolyKinds@, then @'Rep1' Proxy :: * -> *@, but
632 -- if compiled with @PolyKinds@, then @'Rep1' Proxy :: k -> *@.
633
634 -- *** Representation of unlifted types
635 --
636 -- |
637 --
638 -- If one were to attempt to derive a Generic instance for a datatype with an
639 -- unlifted argument (for example, 'Int#'), one might expect the occurrence of
640 -- the 'Int#' argument to be marked with @'Rec0' 'Int#'@. This won't work,
641 -- though, since 'Int#' is of an unlifted kind, and 'Rec0' expects a type of
642 -- kind @*@.
643 --
644 -- One solution would be to represent an occurrence of 'Int#' with 'Rec0 Int'
645 -- instead. With this approach, however, the programmer has no way of knowing
646 -- whether the 'Int' is actually an 'Int#' in disguise.
647 --
648 -- Instead of reusing 'Rec0', a separate data family 'URec' is used to mark
649 -- occurrences of common unlifted types:
650 --
651 -- @
652 -- data family URec a p
653 --
654 -- data instance 'URec' ('Ptr' ()) p = 'UAddr' { 'uAddr#' :: 'Addr#' }
655 -- data instance 'URec' 'Char' p = 'UChar' { 'uChar#' :: 'Char#' }
656 -- data instance 'URec' 'Double' p = 'UDouble' { 'uDouble#' :: 'Double#' }
657 -- data instance 'URec' 'Int' p = 'UFloat' { 'uFloat#' :: 'Float#' }
658 -- data instance 'URec' 'Float' p = 'UInt' { 'uInt#' :: 'Int#' }
659 -- data instance 'URec' 'Word' p = 'UWord' { 'uWord#' :: 'Word#' }
660 -- @
661 --
662 -- Several type synonyms are provided for convenience:
663 --
664 -- @
665 -- type 'UAddr' = 'URec' ('Ptr' ())
666 -- type 'UChar' = 'URec' 'Char'
667 -- type 'UDouble' = 'URec' 'Double'
668 -- type 'UFloat' = 'URec' 'Float'
669 -- type 'UInt' = 'URec' 'Int'
670 -- type 'UWord' = 'URec' 'Word'
671 -- @
672 --
673 -- The declaration
674 --
675 -- @
676 -- data IntHash = IntHash Int#
677 -- deriving 'Generic'
678 -- @
679 --
680 -- yields
681 --
682 -- @
683 -- instance 'Generic' IntHash where
684 -- type 'Rep' IntHash =
685 -- 'D1' ('MetaData \"IntHash\" \"Main\" \"package-name\" 'False)
686 -- ('C1' ('MetaCons \"IntHash\" 'PrefixI 'False)
687 -- ('S1' ('MetaSel 'Nothing
688 -- 'NoSourceUnpackedness
689 -- 'NoSourceStrictness
690 -- 'DecidedLazy)
691 -- 'UInt'))
692 -- @
693 --
694 -- Currently, only the six unlifted types listed above are generated, but this
695 -- may be extended to encompass more unlifted types in the future.
696 #if 0
697 -- *** Limitations
698 --
699 -- |
700 --
701 -- /TODO/
702 --
703 -- /TODO:/ Also clear up confusion about 'Rec0' and 'Rec1' not really indicating recursion.
704 --
705 #endif
706 -----------------------------------------------------------------------------
707
708 -- * Generic representation types
709 V1, U1(..), Par1(..), Rec1(..), K1(..), M1(..)
710 , (:+:)(..), (:*:)(..), (:.:)(..)
711
712 -- ** Unboxed representation types
713 , URec(..)
714 , type UAddr, type UChar, type UDouble
715 , type UFloat, type UInt, type UWord
716
717 -- ** Synonyms for convenience
718 , Rec0, R
719 , D1, C1, S1, D, C, S
720
721 -- * Meta-information
722 , Datatype(..), Constructor(..), Selector(..)
723 , Fixity(..), FixityI(..), Associativity(..), prec
724 , SourceUnpackedness(..), SourceStrictness(..), DecidedStrictness(..)
725 , Meta(..)
726
727 -- * Generic type classes
728 , Generic(..), Generic1(..)
729
730 ) where
731
732 -- We use some base types
733 import Data.Either ( Either (..) )
734 import Data.Maybe ( Maybe(..), fromMaybe )
735 import GHC.Integer ( Integer, integerToInt )
736 import GHC.Prim ( Addr#, Char#, Double#, Float#, Int#, Word# )
737 import GHC.Ptr ( Ptr )
738 import GHC.Types
739
740 -- Needed for instances
741 import GHC.Arr ( Ix )
742 import GHC.Base ( Alternative(..), Applicative(..), Functor(..)
743 , Monad(..), MonadPlus(..), NonEmpty(..), String, coerce
744 , Semigroup(..), Monoid(..) )
745 import GHC.Classes ( Eq(..), Ord(..) )
746 import GHC.Enum ( Bounded, Enum )
747 import GHC.Read ( Read(..) )
748 import GHC.Show ( Show(..), showString )
749
750 -- Needed for metadata
751 import Data.Proxy ( Proxy(..) )
752 import GHC.TypeLits ( Nat, Symbol, KnownSymbol, KnownNat, symbolVal, natVal )
753
754 --------------------------------------------------------------------------------
755 -- Representation types
756 --------------------------------------------------------------------------------
757
758 -- | Void: used for datatypes without constructors
759 data V1 (p :: k)
760 deriving ( Eq -- ^ @since 4.9.0.0
761 , Ord -- ^ @since 4.9.0.0
762 , Read -- ^ @since 4.9.0.0
763 , Show -- ^ @since 4.9.0.0
764 , Functor -- ^ @since 4.9.0.0
765 , Generic -- ^ @since 4.9.0.0
766 , Generic1 -- ^ @since 4.9.0.0
767 )
768
769 -- | @since 4.12.0.0
770 instance Semigroup (V1 p) where
771 v <> _ = v
772
773 -- | Unit: used for constructors without arguments
774 data U1 (p :: k) = U1
775 deriving ( Generic -- ^ @since 4.7.0.0
776 , Generic1 -- ^ @since 4.9.0.0
777 )
778
779 -- | @since 4.9.0.0
780 instance Eq (U1 p) where
781 _ == _ = True
782
783 -- | @since 4.7.0.0
784 instance Ord (U1 p) where
785 compare _ _ = EQ
786
787 -- | @since 4.9.0.0
788 deriving instance Read (U1 p)
789
790 -- | @since 4.9.0.0
791 instance Show (U1 p) where
792 showsPrec _ _ = showString "U1"
793
794 -- | @since 4.9.0.0
795 instance Functor U1 where
796 fmap _ _ = U1
797
798 -- | @since 4.9.0.0
799 instance Applicative U1 where
800 pure _ = U1
801 _ <*> _ = U1
802 liftA2 _ _ _ = U1
803
804 -- | @since 4.9.0.0
805 instance Alternative U1 where
806 empty = U1
807 _ <|> _ = U1
808
809 -- | @since 4.9.0.0
810 instance Monad U1 where
811 _ >>= _ = U1
812
813 -- | @since 4.9.0.0
814 instance MonadPlus U1
815
816 -- | @since 4.12.0.0
817 instance Semigroup (U1 p) where
818 _ <> _ = U1
819
820 -- | @since 4.12.0.0
821 instance Monoid (U1 p) where
822 mempty = U1
823
824 -- | Used for marking occurrences of the parameter
825 newtype Par1 p = Par1 { unPar1 :: p }
826 deriving ( Eq -- ^ @since 4.7.0.0
827 , Ord -- ^ @since 4.7.0.0
828 , Read -- ^ @since 4.7.0.0
829 , Show -- ^ @since 4.7.0.0
830 , Functor -- ^ @since 4.9.0.0
831 , Generic -- ^ @since 4.7.0.0
832 , Generic1 -- ^ @since 4.9.0.0
833 )
834
835 -- | @since 4.9.0.0
836 instance Applicative Par1 where
837 pure = Par1
838 (<*>) = coerce
839 liftA2 = coerce
840
841 -- | @since 4.9.0.0
842 instance Monad Par1 where
843 Par1 x >>= f = f x
844
845 -- | @since 4.12.0.0
846 deriving instance Semigroup p => Semigroup (Par1 p)
847
848 -- | @since 4.12.0.0
849 deriving instance Monoid p => Monoid (Par1 p)
850
851 -- | Recursive calls of kind @* -> *@ (or kind @k -> *@, when @PolyKinds@
852 -- is enabled)
853 newtype Rec1 (f :: k -> *) (p :: k) = Rec1 { unRec1 :: f p }
854 deriving ( Eq -- ^ @since 4.7.0.0
855 , Ord -- ^ @since 4.7.0.0
856 , Read -- ^ @since 4.7.0.0
857 , Show -- ^ @since 4.7.0.0
858 , Functor -- ^ @since 4.9.0.0
859 , Generic -- ^ @since 4.7.0.0
860 , Generic1 -- ^ @since 4.9.0.0
861 )
862
863 -- | @since 4.9.0.0
864 deriving instance Applicative f => Applicative (Rec1 f)
865
866 -- | @since 4.9.0.0
867 deriving instance Alternative f => Alternative (Rec1 f)
868
869 -- | @since 4.9.0.0
870 instance Monad f => Monad (Rec1 f) where
871 Rec1 x >>= f = Rec1 (x >>= \a -> unRec1 (f a))
872
873 -- | @since 4.9.0.0
874 deriving instance MonadPlus f => MonadPlus (Rec1 f)
875
876 -- | @since 4.12.0.0
877 deriving instance Semigroup (f p) => Semigroup (Rec1 f p)
878
879 -- | @since 4.12.0.0
880 deriving instance Monoid (f p) => Monoid (Rec1 f p)
881
882 -- | Constants, additional parameters and recursion of kind @*@
883 newtype K1 (i :: *) c (p :: k) = K1 { unK1 :: c }
884 deriving ( Eq -- ^ @since 4.7.0.0
885 , Ord -- ^ @since 4.7.0.0
886 , Read -- ^ @since 4.7.0.0
887 , Show -- ^ @since 4.7.0.0
888 , Functor -- ^ @since 4.9.0.0
889 , Generic -- ^ @since 4.7.0.0
890 , Generic1 -- ^ @since 4.9.0.0
891 )
892
893 -- | @since 4.12.0.0
894 instance Monoid c => Applicative (K1 i c) where
895 pure _ = K1 mempty
896 liftA2 = \_ -> coerce (mappend :: c -> c -> c)
897 (<*>) = coerce (mappend :: c -> c -> c)
898
899 -- | @since 4.12.0.0
900 deriving instance Semigroup c => Semigroup (K1 i c p)
901
902 -- | @since 4.12.0.0
903 deriving instance Monoid c => Monoid (K1 i c p)
904
905 -- | @since 4.9.0.0
906 deriving instance Applicative f => Applicative (M1 i c f)
907
908 -- | @since 4.9.0.0
909 deriving instance Alternative f => Alternative (M1 i c f)
910
911 -- | @since 4.9.0.0
912 deriving instance Monad f => Monad (M1 i c f)
913
914 -- | @since 4.9.0.0
915 deriving instance MonadPlus f => MonadPlus (M1 i c f)
916
917 -- | @since 4.12.0.0
918 deriving instance Semigroup (f p) => Semigroup (M1 i c f p)
919
920 -- | @since 4.12.0.0
921 deriving instance Monoid (f p) => Monoid (M1 i c f p)
922
923 -- | Meta-information (constructor names, etc.)
924 newtype M1 (i :: *) (c :: Meta) (f :: k -> *) (p :: k) = 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 -> *) (g :: k -> *) (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 -> *) (g :: k -> *) (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 -> *) (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 :: *) (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 @*@)
1122 data R
1123
1124 -- | Type synonym for encoding recursion (of kind @*@)
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 -> *) (a :: k) -> [Char]
1147 -- | The fully-qualified name of the module where the type is declared
1148 moduleName :: t d (f :: k -> *) (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 -> *) (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 -> *) (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 -> *) (a :: k) -> [Char]
1171
1172 -- | The fixity of the constructor
1173 conFixity :: t c (f :: k -> *) (a :: k) -> Fixity
1174 conFixity _ = Prefix
1175
1176 -- | Marks if this constructor is a record
1177 conIsRecord :: t c (f :: k -> *) (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 -> *) (a :: k) -> [Char]
1310 -- | The selector's unpackedness annotation (if any)
1311 --
1312 -- @since 4.9.0.0
1313 selSourceUnpackedness :: t s (f :: k -> *) (a :: k) -> SourceUnpackedness
1314 -- | The selector's strictness annotation (if any)
1315 --
1316 -- @since 4.9.0.0
1317 selSourceStrictness :: t s (f :: k -> *) (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 -> *) (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 :: * -> *
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 -> *) where
1360 -- | Generic representation type
1361 type Rep1 f :: k -> *
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 :: *
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