Witch.Utility

Documentation

as :: forall source. source -> source

This is the same as id. This can be an ergonomic way to pin down a polymorphic type in a function pipeline. For example:

-- Avoid this:
f . (\ x -> x :: Int) . g

-- Prefer this:
f . as @Int . g

into :: forall target source. From source target => source -> target

This is the same as from except that the type variables are in the opposite order.

-- Avoid this:
from x :: t

-- Prefer this:
into @t x

over :: forall target source. (From source target, From target source) => (target -> target) -> source -> source

This function converts from some source type into some target type, applies the given function, then converts back into the source type. This is useful when you have two types that are isomorphic but some function that only works with one of them.

-- Avoid this:
from @t . f . into @t

-- Prefer this:
over @t f

via :: forall through source target. (From source through, From through target) => source -> target

This function first converts from some source type into some through type, and then converts that into some target type. Usually this is used when writing From instances. Sometimes this can be used to work around the lack of an instance that should probably exist.

-- Avoid this:
from @u . into @u

-- Prefer this:
via @u

tryInto :: forall target source. TryFrom source target => source -> Either (TryFromException source target) target

This is the same as tryFrom except that the type variables are in the opposite order.

-- Avoid this:
tryFrom x :: Either (TryFromException s t) t

-- Prefer this:
tryInto @t x

tryVia :: forall through source target. (TryFrom source through, TryFrom through target) => source -> Either (TryFromException source target) target

This is similar to via except that it works with TryFrom instances instead. This function is especially convenient because juggling the types in the TryFromException can be tedious.

-- Avoid this:
case tryInto @u x of
  Left (TryFromException _ e) -> Left $ TryFromException x e
  Right y -> case tryFrom @u y of
    Left (TryFromException _ e) -> Left $ TryFromException x e
    Right z -> Right z

-- Prefer this:
tryVia @u

maybeTryFrom :: (source -> Maybe target) -> source -> Either (TryFromException source target) target

This function can be used to implement tryFrom with a function that returns Maybe. For example:

-- Avoid this:
tryFrom s = case f s of
  Nothing -> Left $ TryFromException s Nothing
  Just t -> Right t

-- Prefer this:
tryFrom = maybeTryFrom f

eitherTryFrom :: Exception exception => (source -> Either exception target) -> source -> Either (TryFromException source target) target

This function can be used to implement tryFrom with a function that returns Either. For example:

-- Avoid this:
tryFrom s = case f s of
  Left e -> Left . TryFromException s . Just $ toException e
  Right t -> Right t

-- Prefer this:
tryFrom = eitherTryFrom f

unsafeFrom :: forall source target. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target

This function is like tryFrom except that it will throw an impure exception if the conversion fails.

-- Avoid this:
either throw id . tryFrom @s

-- Prefer this:
unsafeFrom @s

unsafeInto :: forall target source. (HasCallStack, TryFrom source target, Show source, Typeable source, Typeable target) => source -> target

This function is like tryInto except that it will throw an impure exception if the conversion fails.

-- Avoid this:
either throw id . tryInto @t

-- Prefer this:
unsafeInto @t

withSource :: newSource -> TryFromException oldSource target -> TryFromException newSource target

withTarget :: forall newTarget source oldTarget. TryFromException source oldTarget -> TryFromException source newTarget