Module documentation for 0.3.0.3

typelits-witnesses

Provides witnesses for KnownNat and KnownSymbol instances for various
operations on GHC TypeLits — in particular, the arithmetic operations
defined in GHC.TypeLits, and also for type-level lists of KnownNat and
KnownSymbol instances.

This is useful for situations where you have KnownNat n, and you want to
prove to GHC KnownNat (n + 3), or KnownNat (2*n + 4).

It’s also useful for when you want to work with type level lists of
KnownNat/KnownSymbol instances and singletons for traversing them, and be
able to apply analogies of natVal/symbolVal to lists with analogies for
SomeNat and SomeSymbol.

Note that most of the functionality in this library can be reproduced in a more
generic way using the great singletons library. The versions here are
provided as a “plumbing included” alternative that makes some commonly found
design patterns involving GHC’s TypeLits functionality a little smoother,
especially when working with external libraries or GHC TypeLit’s Nat
comparison API.

You can use the Refl that cmpNat gives you with flipCmpNat and
cmpNatLE to “flip” the inequality or turn it into something compatible
with <=? (useful for when you have to work with libraries that mix the
two methods) or cmpNatEq and eqCmpNat to get to/from witnesses for
equality of the two Nats.

GHC.TypeLits.Witnesses

SOFT DEPRECATED: Use singletons library instead! However, this
module is still here in case people want the functionality of singletons
without requiring the entire library.

Provides witnesses for instances arising from the arithmetic operations
defined in GHC.TypeLits.

In general, if you have KnownNat n, GHC can’t infer KnownNat (n + 1);
and if you have KnownNat m, as well, GHC can’t infer KnownNat (n + m).

This can be extremely annoying when dealing with libraries and applications
where one regularly adds and subtracts type-level nats and expects KnownNat
instances to follow. For example, vector concatenation of length-encoded
vector types can be:

Within the scope of the argument of
withNatOp (%*) (Proxy @n) (Proxy @m), n * m is an instance
of KnownNat, so you can use natVal on it, and get the expected result:

> getDoubled (Proxy @12)
24

There are four “nat operations” defined here, corresponding to the four
type-level operations on Nat provided in GHC.TypeLits: (%+), (%-),
(%*), and (%^), corresponding to addition, subtraction, multiplication, and
exponentiation, respectively.

Note that (%-) is implemented in a way that allows for the result to be a
negativeNat.

There are more advanced operations dealing with low-level machinery, as well,
in the module. See module documentation for more detail.

Singletons replacement

This module is deprecated, and it is recommended you use the functionality from
the singletons package instead. A direct translation using Proxy would
be:

GHC.TypeLits.List

**HARD DEPRECATED: Use singletons library instead! This module is
extremely unweildy, and using singletons is much, much smoother on many
levels, and integrates everything together in a nice way. This module will
likely be removed in a future version.

Provides analogies of KnownNat, SomeNat, natVal, etc., to type-level
lists of KnownNat instances, and also singletons for iterating over
type-level lists of Nats and Symbols.

If you had KnownNats ns, then you have two things you can do with it; first,
natsVal, which is like natVal but for type-level lists of KnownNats:

> natsVal (Proxy @[1,2,3])
[1,2,3]

And more importantly, natsList, which provides singletons that you can
pattern match on to “reify” the structure of the list, getting a Proxy n for
every item in the list with a KnownNat/KnownSymbol instance in scope for
you to use:

Another thing you can do is provide witneses that two [Nat]s or [Symbol]s
are the same/were instantiated with the same numbers/symbols.

> reifyNats [1,2,3] $ \ns -> do
reifyNats [1,2,3] $ \ms -> do
case sameNats ns ms of
Just Refl -> -- in this branch, ns and ms are the same.
Nothing -> -- in this branch, they aren't

The above would match on the Just Refl branch.

See module documentation for more details and variations.

Singletons replacement

This module is deprecated, and it is recommended you use the functionality from
the singletons package instead. natsVal is fromSing, reifyNats is
toSing/withSomeSing, sameNats is simply %~, and you can traverse/reify
singletons of lists too:

Version 0.1.2.0

Added mapNatList' and mapSymbolList' companions to mapNatList and
mapSymbolList; they use NatList and SymbolList instead of Rank-2
types, so they can work better with function composition with (.) and
other things that Rank-2 types would have trouble with.

Added sameNats and sameSymbols, modeled after sameNat and
sameSymbol. They provide witnesses to GHC that KnownNats passed in
are both the same.