Merge pull request #5 from tfausak/cauldron

Split things up and pare them down

.devcontainer/Dockerfile

@@ -0,0 +1,5 @@
+FROM haskell:9.0.1
+ARG USER=haskell
+RUN useradd --create-home --shell "$( which bash )" "$USER"
+USER "$USER"
+ENV PATH="/home/$USER/.cabal/bin:$PATH"

.devcontainer/devcontainer.json

@@ -0,0 +1,9 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "extensions": [
+    "taylorfausak.purple-yolk"
+  ],
+  "postCreateCommand": "cabal update"
+}

.github/workflows/ci.yaml

@@ -12,13 +12,14 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         include:
-          - { os: ubuntu-18.04, ghc: 9.0.1, cabal: 3.4.0.0 }
+          - { os: ubuntu-20.04, ghc: 9.0.1, cabal: 3.4.0.0 }
-          - { os: ubuntu-18.04, ghc: 8.10.3, cabal: 3.2.0.0 }
+          - { os: macos-10.15, ghc: 9.0.1, cabal: 3.4.0.0 }
-          - { os: macos-10.15, ghc: 8.10.3, cabal: 3.2.0.0 }
+          - { os: windows-2019, ghc: 9.0.1, cabal: 3.4.0.0 }
-          - { os: windows-2019, ghc: 8.10.3, cabal: 3.2.0.0 }
+          - { os: ubuntu-20.04, ghc: 8.10.4, cabal: 3.2.1.0 }
-          - { os: ubuntu-18.04, ghc: 8.8.4, cabal: 3.0.0.0 }
+          - { os: ubuntu-20.04, ghc: 8.8.4, cabal: 3.0.1.0 }
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
@@ -42,5 +43,5 @@ jobs:
           path: dist-newstyle/sdist/witch-*.tar.gz
           name: witch-${{ github.sha }}.tar.gz
       - run: cabal check
-      - if: github.event_name == 'release' && matrix.os == 'ubuntu-18.04' && matrix.ghc == '9.0.1'
+      - if: github.event_name == 'release' && matrix.os == 'ubuntu-20.04' && matrix.ghc == '9.0.1'
         run: cabal upload --publish --username '${{ secrets.HACKAGE_USERNAME }}' --password '${{ secrets.HACKAGE_PASSWORD }}' dist-newstyle/sdist/witch-*.tar.gz

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "purple-yolk.brittany.command": "false",
+  "purple-yolk.ghci.command": "cabal repl --ghc-options -Wwarn --repl-options -ddump-json",
+  "purple-yolk.hlint.command": "false",
+  "purple-yolk.hlint.onSave": false,
+  "editor.rulers": [
+    79
+  ],
+  "editor.tabSize": 2,
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true
+}

README.markdown

@@ -5,3 +5,7 @@
 [![Stackage](https://www.stackage.org/package/witch/badge/nightly?label=stackage)](https://www.stackage.org/package/witch)
 
 :mage_woman: Convert values from one type into another.
+
+## To do
+
+- [ ] Add more instances ...

cabal.project

@@ -0,0 +1,6 @@
+jobs: $ncpus
+packages: .
+
+package witch
+  ghc-options: -Werror
+  tests: True

src/ghc-8.10/Witch/Lift.hs

@@ -0,0 +1,73 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE ExplicitForAll #-}
+{-# LANGUAGE TypeFamilies #-}
+
+module Witch.Lift where
+
+import qualified Data.Typeable as Typeable
+import qualified Language.Haskell.TH.Syntax as TH
+import qualified Witch.Identity as Identity
+import qualified Witch.TryCast as TryCast
+import qualified Witch.Utility as Utility
+
+-- | This is like 'Utility.unsafeCast' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeCast "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast "some literal")
+liftedCast
+  :: forall source target
+   . ( TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedCast = TH.liftTyped . Utility.unsafeCast
+
+-- | This is like 'Utility.unsafeFrom' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeFrom @s "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @s "some literal")
+liftedFrom
+  :: forall s target source
+   . ( Identity.Identity s ~ source
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedFrom = liftedCast
+
+-- | This is like 'Utility.unsafeInto' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeInto @t "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @t "some literal")
+liftedInto
+  :: forall t source target
+   . ( Identity.Identity t ~ target
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedInto = liftedCast

src/ghc-8.8/Witch/Lift.hs

@@ -0,0 +1,73 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeFamilies #-}
+
+module Witch.Lift where
+
+import qualified Data.Typeable as Typeable
+import qualified Language.Haskell.TH.Syntax as TH
+import qualified Witch.Identity as Identity
+import qualified Witch.TryCast as TryCast
+import qualified Witch.Utility as Utility
+
+-- | This is like 'Utility.unsafeCast' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeCast "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast "some literal")
+liftedCast
+  :: forall source target
+   . ( TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedCast s = TH.unsafeTExpCoerce $ TH.lift (Utility.unsafeCast s :: target)
+
+-- | This is like 'Utility.unsafeFrom' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeFrom @s "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @s "some literal")
+liftedFrom
+  :: forall s target source
+   . ( Identity.Identity s ~ source
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedFrom = liftedCast
+
+-- | This is like 'Utility.unsafeInto' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeInto @t "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @t "some literal")
+liftedInto
+  :: forall t source target
+   . ( Identity.Identity t ~ target
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> TH.Q (TH.TExp target)
+liftedInto = liftedCast

src/ghc-9.0/Witch/Lift.hs

@@ -0,0 +1,76 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE ExplicitForAll #-}
+{-# LANGUAGE TypeFamilies #-}
+
+module Witch.Lift where
+
+import qualified Data.Typeable as Typeable
+import qualified Language.Haskell.TH.Syntax as TH
+import qualified Witch.Identity as Identity
+import qualified Witch.TryCast as TryCast
+import qualified Witch.Utility as Utility
+
+-- | This is like 'Utility.unsafeCast' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeCast "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast "some literal")
+liftedCast
+  :: forall source target m
+   . ( TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     , TH.Quote m
+     )
+  => source
+  -> TH.Code m target
+liftedCast = TH.liftTyped . Utility.unsafeCast
+
+-- | This is like 'Utility.unsafeFrom' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeFrom @s "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @s "some literal")
+liftedFrom
+  :: forall s target m source
+   . ( Identity.Identity s ~ source
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     , TH.Quote m
+     )
+  => source
+  -> TH.Code m target
+liftedFrom = liftedCast
+
+-- | This is like 'Utility.unsafeInto' except that it works at compile time
+-- rather than runtime.
+--
+-- > -- Avoid this:
+-- > unsafeInto @t "some literal"
+-- >
+-- > -- Prefer this:
+-- > $$(liftedCast @t "some literal")
+liftedInto
+  :: forall t source m target
+   . ( Identity.Identity t ~ target
+     , TryCast.TryCast source target
+     , TH.Lift target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     , TH.Quote m
+     )
+  => source
+  -> TH.Code m target
+liftedInto = liftedCast

src/lib/Witch.hs

@@ -1,319 +1,161 @@
-{-# language AllowAmbiguousTypes #-}
+-- | The Witch package is a library that allows you to confidently convert
-{-# language DefaultSignatures #-}
+-- values between various types. This module exports everything you need to
-{-# language FlexibleInstances #-}
+-- perform conversions or define your own. It is designed to be imported
-{-# language MultiParamTypeClasses #-}
+-- unqualified, so getting started is as easy as:
-{-# language ScopedTypeVariables #-}
-{-# language TypeFamilies #-}
-
--- | This module provides the 'Cast' type class for converting values between
--- various types. This aims to be a common interface for the various @xToY@ or
--- @yFromX@ functions you might write instead. It is inspired by the
--- @std::convert::From@ trait that the Rust programming language provides.
 --
--- Many Haskell libraries already provide similar functionality. Here's how
+-- >>> import Witch
--- this module compares to them:
+module Witch
---
+  ( -- * Motivation
--- - <https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-Coerce.html>:
+  -- | Haskell provides many ways to convert between common types, and core
---   This type class is convenient because it's automatically inferred by the
+  -- libraries add even more. It can be challenging to know which function to
---   compiler, but it only works for types that have the same runtime
+  -- use when converting from some source type @a@ to some target type @b@. It
---   representation.
+  -- can be even harder to know if that conversion is safe or if there are any
---
+  -- pitfalls to watch out for.
--- - <https://hackage.haskell.org/package/convertible-1.1.1.0/docs/Data-Convertible-Base.html>:
---   This type class allows for conversions to fail.
---
--- - <https://hackage.haskell.org/package/basement-0.0.11/docs/Basement-From.html>:
---   This type class is essentially the same, but the @basement@ package is an
---   alternative standard library that some people may not want to depend on.
---
--- - <https://hackage.haskell.org/package/inj-base-0.2.0.0/docs/Inj-Base.html>:
---   This type class requires conversions to be injective, as opposed to merely
---   suggesting it. Also some conversions fail at runtime.
---
--- - <https://github.com/mbj/conversions/blob/6ac6c52/src/Data/Conversions/FromType.hs>:
---   This type class comes with many convenient helper functions, but some of
---   the provided instances fail at runtime.
---
--- - <https://github.com/kframework/kore/blob/626f230/kore/src/From.hs>:
---   This package is not available on Hackage, but otherwise is very similar to
---   this one.
-module Witch (Cast(cast), from, into, via) where
-
-import qualified Data.ByteString as ByteString
-import qualified Data.ByteString.Lazy as LazyByteString
-import qualified Data.Coerce as Coerce
-import qualified Data.Foldable as Foldable
-import qualified Data.Int as Int
-import qualified Data.List.NonEmpty as NonEmpty
-import qualified Data.Map as Map
-import qualified Data.Sequence as Seq
-import qualified Data.Set as Set
-import qualified Data.Text as Text
-import qualified Data.Text.Lazy as LazyText
-import qualified Data.Tuple as Tuple
-import qualified Data.Void as Void
-import qualified Data.Word as Word
-import qualified Numeric.Natural as Natural
-
--- | This type class represents a way to convert values from some type into
--- another type. The constraint @Cast a b@ means that you can convert from a
--- value of type @a@ into a value of type @b@.
---
--- This is primarily intended for "zero cost" conversions like @newtype@s. For
--- example if you wanted to have a type to represent someone's name, you could
--- say:
---
--- > newtype Name = Name String
--- > instance Cast String Name
--- > instance Cast Name String
---
--- And then you could convert back and forth between @Name@s and @String@s:
---
--- > let someString = "Taylor"
--- > let someName = Name someString
--- > into @Name someString -- convert from string to name
--- > into @String someName -- convert from name to string
---
--- This type class does not have any laws, but it does have some expectations:
---
--- - Conversions should be total. A conversion should never fail or crash.
---   Avoid writing instances like @Cast Int (Maybe Char)@. (It might be
---   worthwhile to have a separate @TryCast@ type class for this.)
---
--- - Conversions should be unambiguous. For example there are many ways to
---   decode a @ByteString@ into @Text@, so you shouldn't provide an instance
---   for that.
---
--- - Conversions should be cheap, ideally free. For example converting from
---   @String@ to @Text@ is probably fine, but converting from a UTF-8 encoded
---   @ByteString@ to @Text@ is problematic.
---
--- - Conversions should be lossless. In other words if you have @Cast a b@ then
---   no two @a@ values should be converted to the same @b@ value. For example
---   @Cast Int Integer@ is fine because every @Int@ can be mapped to a
---   corresponding @Integer@, but @Cast Integer Int@ is not good because some
---   @Integer@s are out of bounds and would need to be clamped.
---
--- - If you have both @Cast a b@ and @Cast b a@, then @cast . cast@ should be
---   the same as 'id'. In other words @a@ and @b@ are isomorphic.
---
--- - If you have both @Cast a b@ and @Cast b c@, then it's up to you if you
---   want to provide @Cast a c@. Sometimes using 'via' is ergonomic enough,
---   other times you want the extra instance. (It would be nice if we could
---   provide @instance (Cast a b, Cast b c) => Cast a c where cast = via \@b@.)
-class Cast source target where
-  -- | This method implements the conversion of a value between types. In
-  -- practice most instances don't need an explicit implementation. At call
-  -- sites you'll usually want to use 'from' or 'into' instead of 'cast'.
   --
-  -- The default implementation of 'cast' simply calls 'Coerce.coerce', which
+  -- This library tries to address that problem by providing a common
-  -- works for types that have the same runtime representation.
+  -- interface for converting between types. The 'Witch.Cast.Cast' type class
-  cast :: source -> target
+  -- is for conversions that cannot fail, and the 'Witch.TryCast.TryCast' type
-  default cast :: Coerce.Coercible source target => source -> target
+  -- class is for conversions that can fail. These type classes are inspired
-  cast = Coerce.coerce
+  -- by the [@From@](https://doc.rust-lang.org/std/convert/trait.From.html)
+  -- trait in Rust.
 
--- This ugly hack is used to require type applications when calling 'from' and
+  -- * Alternatives
--- 'into'. See <https://twitter.com/taylorfausak/status/1329084033003782148>.
+  -- | Many Haskell libraries already provide similar functionality. How is
-data Never
+  -- this library different?
-type family Ambiguous a where
+  --
-  Ambiguous Never = ()
+  -- - [@Coercible@](https://hackage.haskell.org/package/base-4.15.0.0/docs/Data-Coerce.html#t:Coercible):
-  Ambiguous a = a
+  --   This type class is solved by the compiler, but it only works for types
+  --   that have the same runtime representation. This is very convenient for
+  --   @newtype@s, but it does not work for converting between arbitrary types
+  --   like @Int8@ and @Int16@.
+  --
+  -- - [@Convertible@](https://hackage.haskell.org/package/convertible-1.1.1.0/docs/Data-Convertible-Base.html#t:Convertible):
+  --   This popular conversion type class is similar to what this library
+  --   provides. The main difference is that it does not differentiate between
+  --   conversions that can fail and those that cannot.
+  --
+  -- - [@From@](https://hackage.haskell.org/package/basement-0.0.11/docs/Basement-From.html#t:From):
+  --   This type class is almost identical to what this library provides.
+  --   Unfortunately it is part of the @basement@ package, which is an
+  --   alternative standard library that some people may not want to depend
+  --   on.
+  --
+  -- - [@Inj@](https://hackage.haskell.org/package/inj-1.0/docs/Inj.html#t:Inj):
+  --   This type class requires instances to be an injection, which means that
+  --   no two input values should map to the same output. That restriction
+  --   prohibits many useful instances. Also many instances throw impure
+  --   exceptions.
+  --
+  -- In addition to those general-purpose type classes, there are many
+  -- alternatives for more specific conversions. How does this library compare
+  -- to those?
+  --
+  -- - Monomorphic conversion functions like [@Data.Text.pack@](https://hackage.haskell.org/package/text-1.2.4.1/docs/Data-Text.html#v:pack)
+  --   are explicit but not necessarily convenient. It can be tedious to
+  --   manage the imports necessary to use the functions. And if you want to
+  --   put them in a custom prelude, you will have to come up with your own
+  --   names.
+  --
+  -- - Polymorphic conversion methods like 'toEnum' are more convenient but
+  --   may have unwanted semantics or runtime behavior. For example the 'Enum'
+  --   type class is more or less tied to the 'Int' data type and frequently
+  --   throws impure exceptions.
+  --
+  -- - Polymorphic conversion functions like 'fromIntegral' are very
+  --   convenient. Unfortunately it can be challenging to know which types
+  --   have the instances necessary to make the conversion possible. And even
+  --   if the conversion is possible, is it safe? For example converting a
+  --   negative 'Int' into a 'Word' will overflow, which may be surprising.
 
--- | This function converts a value from one type into another. This is
+  -- * Instances
--- intended to be used with the @TypeApplications@ language extension. The
+  -- | When should you add a 'Witch.Cast.Cast' (or 'Witch.TryCast.TryCast')
--- @Ambiguous@ type in the signature makes a type application required. If
+  -- instance for some pair of types? This is a surprisingly tricky question
--- you'd prefer not to provide a type application, use 'cast' instead.
+  -- to answer precisely. Instances are driven more by guidelines than rules.
---
+  --
--- As an example, here are a few ways to convert from an 'Int' into an
+  -- - Conversions must not throw impure exceptions. This means no 'undefined'
--- 'Integer':
+  --   or anything equivalent to it.
---
+  --
--- > from @Int @Integer 123
+  -- - Conversions should be unambiguous. If there are multiple reasonable
--- > from @_ @Integer (123 :: Int)
+  --   ways to convert from @a@ to @b@, then you probably should not add a
--- > from @Int @_ 123 :: Integer
+  --   @Cast@ instance for them.
--- > from @Int 123 :: Integer
+  --
---
+  -- - Conversions should be lossless. If you have @Cast a b@ then no two @a@
--- Often the context around an expression will make the explicit type
+  --   values should be converted to the same @b@ value.
--- signatures unnecessary. If you find yourself using a partial type
+  --
--- signature, consider using 'into' instead. For example:
+  -- - If you have both @Cast a b@ and @Cast b a@, then
---
+  --   @cast \@b \@a . cast \@a \@b@ should be the same as 'id'. In other
--- > let someInt = 123 :: Int
+  --   words, @a@ and @b@ are isomorphic.
--- > from @_ @Integer someInt -- avoid this
+  --
--- > into @Integer someInt -- prefer this
+  -- - If you have both @Cast a b@ and @Cast b c@, then you could also have
---
+  --   @Cast a c@ and it should be the same as @cast \@b \@c . cast \@a \@b@.
-from :: forall s target source . (Ambiguous s ~ source, Cast source target) => source -> target
+  --   In other words, @Cast@ is transitive.
-from = cast
+  --
+  -- In general if @s@ is a @t@, then you should add a 'Witch.Cast.Cast'
+  -- instance for it. But if @s@ merely can be a @t@, then you could add a
+  -- 'Witch.TryCast.TryCast' instance for it. And if it is technically
+  -- possible to convert from @s@ to @t@ but there are a lot of caveats, you
+  -- probably should not write any instances at all.
 
--- | This function converts a value from one type into another. This is the
+  -- * Type applications
--- same as 'from' except that the type variables are in the opposite order.
+  -- | This library is designed to be used with the [@TypeApplications@](https://downloads.haskell.org/~ghc/9.0.1/docs/html/users_guide/exts/type_applications.html)
-into :: forall t source target . (Ambiguous t ~ target, Cast source target) => source -> target
+  -- language extension. Although it is not required for basic functionality,
-into = cast
+  -- it is strongly encouraged. You can use 'Witch.Cast.cast',
+  -- 'Witch.TryCast.tryCast', 'Witch.Utility.unsafeCast', and
+  -- 'Witch.Lift.liftedCast' without type applications. Everything else
+  -- requires a type application.
 
--- | This function converts a value from one type into another by going through
+  -- * Ambiguous types
--- some third type. This is the same as calling 'cast' (or 'from' or 'into')
+  -- | You may see @Identity@ show up in some type signatures. Anywhere you see
--- twice, but can sometimes be more convenient.
+  -- @Identity a@, you can mentally replace it with @a@. It is a type family
---
+  -- used to trick GHC into requiring type applications for certain functions.
--- Note that the type in the middle of the conversion is the first type
+  -- If you forget to give a type application, you will see an error like
--- variable of this function. In other words, @via \@b \@a \@c@ first converts
+  -- this:
--- from @a@ to @b@, and then from @b@ to @c@. Often both @a@ and @c@ will be
+  --
--- inferred from context, which means you can just write @via \@b@.
+  -- >>> from (1 :: Int8) :: Int16
-via :: forall through source target . (Cast source through, Cast through target) => source -> target
+  -- <interactive>:1:1: error:
-via = cast . (\ x -> x :: through) . cast
+  --     * Couldn't match type `Identity s0' with `Int8'
+  --         arising from a use of `from'
+  --       The type variable `s0' is ambiguous
+  --     * In the expression: from (1 :: Int8) :: Int16
+  --       In an equation for `it': it = from (1 :: Int8) :: Int16
+  --
+  -- You can fix the problem by giving a type application:
+  --
+  -- >>> from @Int8 1 :: Int16
+  -- 1
 
--- | 'id'
+  -- * Type classes
-instance Cast a a where
+  -- ** Cast
-  cast = id
+    Witch.Cast.Cast(cast)
+  , Witch.Utility.from
+  , Witch.Utility.into
 
--- | 'const'
+  -- ** TryCast
-instance Cast a (x -> a) where
+  , Witch.TryCast.TryCast(tryCast)
-  cast = const
+  , Witch.Utility.tryFrom
+  , Witch.Utility.tryInto
+  , Witch.TryCastException.TryCastException(..)
 
--- | 'pure'
+  -- * Utilities
-instance Cast a [a] where
+  , Witch.Utility.as
-  cast = pure
+  , Witch.Utility.over
+  , Witch.Utility.via
+  , Witch.Utility.tryVia
 
--- | 'Just'
+  -- ** Unsafe
-instance Cast a (Maybe a) where
+  , Witch.Utility.unsafeCast
-  cast = Just
+  , Witch.Utility.unsafeFrom
+  , Witch.Utility.unsafeInto
 
--- | 'Left'
+  -- ** Template Haskell
-instance Cast a (Either a x) where
+  , Witch.Lift.liftedCast
-  cast = Left
+  , Witch.Lift.liftedFrom
+  , Witch.Lift.liftedInto
+  ) where
 
--- | 'Right'
+import qualified Witch.Cast
-instance Cast a (Either x a) where
+import Witch.Instances ()
-  cast = Right
+import qualified Witch.Lift
-
+import qualified Witch.TryCast
--- | 'Void.absurd'
+import qualified Witch.TryCastException
-instance Cast Void.Void x where
+import qualified Witch.Utility
-  cast = Void.absurd
-
--- | 'fst'
-instance Cast (a, x) a where
-  cast = fst
-
--- | 'snd'
-instance Cast (x, a) a where
-  cast = snd
-
--- | 'Tuple.swap'
-instance Cast (a, b) (b, a) where
-  cast = Tuple.swap
-
--- | 'NonEmpty.toList'
-instance Cast (NonEmpty.NonEmpty a) [a] where
-  cast = NonEmpty.toList
-
--- | 'fromIntegral'
-instance Cast Word.Word8 Word.Word16 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Word.Word16 Word.Word32 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Word.Word32 Word.Word64 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Word Natural.Natural where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Natural.Natural Integer where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Int.Int8 Int.Int16 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Int.Int16 Int.Int32 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Int.Int32 Int.Int64 where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Int Integer where
-  cast = fromIntegral
-
--- | 'fromIntegral'
-instance Cast Integer Rational where
-  cast = fromIntegral
-
--- | 'realToFrac'
-instance Cast Float Double where
-  cast = realToFrac
-
--- | 'fromEnum'
-instance Cast Bool Int where
-  cast = fromEnum
-
--- | 'fromEnum'
-instance Cast Char Int where
-  cast = fromEnum
-
--- | 'ByteString.pack'
-instance Cast [Word.Word8] ByteString.ByteString where
-  cast = ByteString.pack
-
--- | 'ByteString.unpack'
-instance Cast ByteString.ByteString [Word.Word8] where
-  cast = ByteString.unpack
-
--- | 'LazyByteString.fromStrict'
-instance Cast ByteString.ByteString LazyByteString.ByteString where
-  cast = LazyByteString.fromStrict
-
--- | 'LazyByteString.toStrict'
-instance Cast LazyByteString.ByteString ByteString.ByteString where
-  cast = LazyByteString.toStrict
-
--- | 'Text.pack'
---
--- Note that some 'Char' values cannot be represented in 'Text' and will be
--- replaced by U+FFFD.
-instance Cast String Text.Text where
-  cast = Text.pack
-
--- | 'Text.unpack'
-instance Cast Text.Text String where
-  cast = Text.unpack
-
--- | 'LazyText.fromStrict'
-instance Cast Text.Text LazyText.Text where
-  cast = LazyText.fromStrict
-
--- | 'LazyText.toStrict'
-instance Cast LazyText.Text Text.Text where
-  cast = LazyText.toStrict
-
--- | 'Seq.fromList'
-instance Cast [a] (Seq.Seq a) where
-  cast = Seq.fromList
-
--- | 'Foldable.toList'
-instance Cast (Seq.Seq a) [a] where
-  cast = Foldable.toList
-
--- | 'Set.fromList'
---
--- Note that this will remove duplicate elements from the list.
-instance Ord a => Cast [a] (Set.Set a) where
-  cast = Set.fromList
-
--- | 'Set.toAscList'
-instance Cast (Set.Set a) [a] where
-  cast = Set.toAscList
-
--- | 'Map.fromList'
---
--- Note that if there are duplicate keys in the list, the one closest to the
--- end will win.
-instance Ord k => Cast [(k, v)] (Map.Map k v) where
-  cast = Map.fromList
-
--- | 'Map.toAscList'
-instance Cast (Map.Map k v) [(k, v)] where
-  cast = Map.toAscList

src/lib/Witch/Cast.hs

@@ -0,0 +1,31 @@
+{-# LANGUAGE DefaultSignatures #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+
+module Witch.Cast where
+
+import qualified Data.Coerce as Coerce
+
+-- | This type class is for converting values from some @source@ type into
+-- some other @target@ type. The constraint @Cast source target@ measn that
+-- you can convert from a value of type @source@ into a value of type
+-- @target@.
+--
+-- This type class is for conversions that cannot fail. If your conversion can
+-- fail, consider implementing @TryCast@ instead.
+class Cast source target where
+  -- | This method implements the conversion of a value between types. At call
+  -- sites you will usually want to use @from@ or @into@ instead of this
+  -- method.
+  --
+  -- The default implementation of this method simply calls 'Coerce.coerce',
+  -- which works for types that have the same runtime representation. This
+  -- means that for @newtype@s you do not need to implement this method at
+  -- all. For example:
+  --
+  -- >>> newtype Name = Name String
+  -- >>> instance Cast Name String
+  -- >>> instance Cast String Name
+  cast :: source -> target
+
+  default cast :: Coerce.Coercible source target => source -> target
+  cast = Coerce.coerce

src/lib/Witch/Identity.hs

@@ -0,0 +1,14 @@
+{-# LANGUAGE TypeFamilies #-}
+
+module Witch.Identity where
+
+-- | This is an ugly hack used to make GHC require type applications for
+-- certain functions. See this Twitter thread for a discussion:
+-- <https://twitter.com/taylorfausak/status/1329084033003782148>.
+type family Identity a where
+  Identity Never = ()
+  Identity a = a
+
+-- | Never use this type for anything! It only exists to make the 'Identity'
+-- type family non-trivial.
+data Never

src/lib/Witch/TryCast.hs

@@ -0,0 +1,18 @@
+{-# LANGUAGE MultiParamTypeClasses #-}
+
+module Witch.TryCast where
+
+import qualified Witch.TryCastException as TryCastException
+
+-- | This type class is for converting values from some @source@ type into
+-- some other @target@ type. The constraint @TryCast source target@ means that
+-- you may be able to convert from a value of type @source@ into a value of
+-- type @target@, but that conversion may fail at runtime.
+--
+-- This type class is for conversions that can fail. If your conversion cannot
+-- fail, consider implementing @Cast@ instead.
+class TryCast source target where
+  -- | This method implements the conversion of a value between types. At call
+  -- sites you will usually want to use @tryFrom@ or @tryInto@ instead of this
+  -- method.
+  tryCast :: source -> Either (TryCastException.TryCastException source target) target

src/lib/Witch/TryCastException.hs

@@ -0,0 +1,33 @@
+{-# LANGUAGE ScopedTypeVariables #-}
+
+module Witch.TryCastException where
+
+import qualified Control.Exception as Exception
+import qualified Data.Proxy as Proxy
+import qualified Data.Typeable as Typeable
+
+-- | This exception is thrown when a @TryCast@ conversion fails. It has the
+-- original @source@ value that caused the failure and it knows the @target@
+-- type it was trying to convert into.
+newtype TryCastException source target
+  = TryCastException source
+  deriving Eq
+
+instance
+  ( Show source
+  , Typeable.Typeable source
+  , Typeable.Typeable target
+  ) => Show (TryCastException source target) where
+  showsPrec d (TryCastException x) =
+    showParen (d > 10)
+      $ showString "TryCastException {- "
+      . shows
+          (Typeable.typeRep (Proxy.Proxy :: Proxy.Proxy (source -> target)))
+      . showString " -} "
+      . showsPrec 11 x
+
+instance
+  ( Show source
+  , Typeable.Typeable source
+  , Typeable.Typeable target
+  ) => Exception.Exception (TryCastException source target)

src/lib/Witch/Utility.hs

@@ -0,0 +1,211 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeFamilies #-}
+
+module Witch.Utility where
+
+import qualified Control.Exception as Exception
+import qualified Data.Typeable as Typeable
+import qualified GHC.Stack as Stack
+import qualified Witch.Cast as Cast
+import qualified Witch.Identity as Identity
+import qualified Witch.TryCast as TryCast
+import qualified Witch.TryCastException as TryCastException
+
+-- | This is the same as 'id' except that it requires a type application. 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
+as :: forall s source . Identity.Identity s ~ source => source -> source
+as = id
+
+-- | This is the same as 'Cast.cast' except that it requires a type
+-- application for the @source@ type.
+--
+-- > -- Avoid this:
+-- > cast (x :: s)
+-- >
+-- > -- Prefer this:
+-- > from @s x
+from
+  :: forall s target source
+   . (Identity.Identity s ~ source, Cast.Cast source target)
+  => source
+  -> target
+from = Cast.cast
+
+-- | This is the same as 'Cast.cast' except that it requires a type
+-- application for the @target@ type.
+--
+-- > -- Avoid this:
+-- > cast x :: t
+-- >
+-- > -- Prefer this:
+-- > into @t x
+into
+  :: forall t source target
+   . (Identity.Identity t ~ target, Cast.Cast source target)
+  => source
+  -> target
+into = Cast.cast
+
+-- | 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 . from @s
+-- >
+-- > -- Prefer this:
+-- > over @t f
+over
+  :: forall t source target
+   . ( Identity.Identity t ~ target
+     , Cast.Cast source target
+     , Cast.Cast target source
+     )
+  => (target -> target)
+  -> source
+  -> source
+over f = Cast.cast . f . Cast.cast
+
+-- | 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 'Cast.Cast' 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
+via
+  :: forall u source target through
+   . ( Identity.Identity u ~ through
+     , Cast.Cast source through
+     , Cast.Cast through target
+     )
+  => source
+  -> target
+via = Cast.cast . (\x -> x :: through) . Cast.cast
+
+-- | This is the same as 'TryCast.tryCast' except that it requires a type
+-- application for the @source@ type.
+--
+-- > -- Avoid this:
+-- > tryCast (x :: s)
+-- >
+-- > -- Prefer this:
+-- > tryFrom @s x
+tryFrom
+  :: forall s target source
+   . (Identity.Identity s ~ source, TryCast.TryCast source target)
+  => source
+  -> Either (TryCastException.TryCastException source target) target
+tryFrom = TryCast.tryCast
+
+-- | This is the same as 'TryCast.tryCast' except that it requires a type
+-- application for the @target@ type.
+--
+-- > -- Avoid this:
+-- > tryCast x :: Either (TryCastException s t) t
+-- >
+-- > -- Prefer this:
+-- > tryInto @t x
+tryInto
+  :: forall t source target
+   . (Identity.Identity t ~ target, TryCast.TryCast source target)
+  => source
+  -> Either (TryCastException.TryCastException source target) target
+tryInto = TryCast.tryCast
+
+-- | This is similar to 'via' except that it works with 'TryCast.TryCast'
+-- instances instead. This function is especially convenient because juggling
+-- the types in the 'TryCastException.TryCastException' can be tedious.
+--
+-- > -- Avoid this:
+-- > fmap (tryFrom @u) . tryInto @u
+-- >
+-- > -- Prefer this:
+-- > tryVia @u
+tryVia
+  :: forall u source target through
+   . ( Identity.Identity u ~ through
+     , TryCast.TryCast source through
+     , TryCast.TryCast through target
+     )
+  => source
+  -> Either (TryCastException.TryCastException source target) target
+tryVia s = case TryCast.tryCast s of
+  Left _ -> Left $ TryCastException.TryCastException s
+  Right u -> case TryCast.tryCast (u :: through) of
+    Left _ -> Left $ TryCastException.TryCastException s
+    Right t -> Right t
+
+-- | This function is like 'TryCast.tryCast' except that it will throw an
+-- impure exception if the conversion fails.
+--
+-- > -- Avoid this:
+-- > either throw id . cast
+-- >
+-- > -- Prefer this:
+-- > unsafeCast
+unsafeCast
+  :: forall source target
+   . ( Stack.HasCallStack
+     , TryCast.TryCast source target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> target
+unsafeCast = either Exception.throw id . TryCast.tryCast
+
+-- | This function is like 'from' except that it will throw an impure
+-- exception if the conversion fails.
+--
+-- > -- Avoid this:
+-- > either throw id . from @s
+-- >
+-- > -- Prefer this:
+-- > unsafeFrom @s
+unsafeFrom
+  :: forall s target source
+   . ( Identity.Identity s ~ source
+     , Stack.HasCallStack
+     , TryCast.TryCast source target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> target
+unsafeFrom = unsafeCast
+
+-- | This function is like 'into' except that it will throw an impure
+-- exception if the conversion fails.
+--
+-- > -- Avoid this:
+-- > either throw id . into @t
+-- >
+-- > -- Prefer this:
+-- > unsafeInto @t
+unsafeInto
+  :: forall t source target
+   . ( Identity.Identity t ~ target
+     , Stack.HasCallStack
+     , TryCast.TryCast source target
+     , Show source
+     , Typeable.Typeable source
+     , Typeable.Typeable target
+     )
+  => source
+  -> target
+unsafeInto = unsafeCast

stack.yaml

@@ -1 +1 @@
-resolver: lts-17.0
+resolver: nightly-2021-04-06

witch.cabal

@@ -1,52 +1,77 @@
-cabal-version: >= 1.10
+cabal-version: 2.2
+
+name: witch
+version: 0.0.0.5
+synopsis: Convert values from one type into another.
+description: Witch converts values from one type into another.
 
 build-type: Simple
 category: Data
-description: Witch converts values from one type into another.
 extra-source-files: CHANGELOG.markdown README.markdown
 license-file: LICENSE.txt
 license: ISC
 maintainer: Taylor Fausak
-name: witch
-synopsis: Convert values from one type into another.
-version: 0.0.0.5
 
 source-repository head
   location: https://github.com/tfausak/witch
   type: git
 
-library
+common basics
   build-depends:
-    base >= 4.13.0 && < 4.16
+    , base >= 4.13.0 && < 4.16
-    , bytestring >= 0.10.10 && < 0.11
+    , bytestring >= 0.10.12 && < 0.11
     , containers >= 0.6.2 && < 0.7
     , text >= 1.2.4 && < 1.3
   default-language: Haskell2010
-  exposed-modules: Witch
   ghc-options:
     -Weverything
     -Wno-implicit-prelude
+    -Wno-missing-deriving-strategies
+    -Wno-missing-export-lists
+    -Wno-missing-exported-signatures
     -Wno-redundant-constraints
     -Wno-safe
     -Wno-unsafe
-  hs-source-dirs: src/lib
 
   if impl(ghc >= 8.10)
     ghc-options:
       -Wno-missing-safe-haskell-mode
       -Wno-prepositive-qualified-module
 
-test-suite test
+library
+  import: basics
+
   build-depends:
-    base
+    , template-haskell >= 2.15.0 && < 2.18
-    , bytestring
+  exposed-modules:
-    , containers
+    Witch
-    , hspec >= 2.7.6 && < 2.8
+    Witch.Cast
-    , QuickCheck >= 2.13.2 && < 2.15
+    Witch.Identity
-    , text
+    Witch.Instances
+    Witch.Lift
+    Witch.TryCast
+    Witch.TryCastException
+    Witch.Utility
+  hs-source-dirs: src/lib
+
+  if impl(ghc >= 9.0)
+    hs-source-dirs: src/ghc-9.0
+  else
+    if impl(ghc >= 8.10)
+      hs-source-dirs: src/ghc-8.10
+    else
+      hs-source-dirs: src/ghc-8.8
+
+test-suite test
+  import: basics
+
+  build-depends:
+    , hspec >= 2.7.9 && < 2.8
     , witch
-  default-language: Haskell2010
+  ghc-options:
-  ghc-options: -rtsopts -threaded
+    -rtsopts
+    -threaded
+    -Wno-all-missed-specialisations
   hs-source-dirs: src/test
   main-is: Main.hs
   type: exitcode-stdio-1.0