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