-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Exhaustive pattern matching using lenses, traversals, and prisms
--
-- Use this library if you wish to hide your data type's internal
-- representation while still providing a way to exhaustively pattern
-- match on your type using exposed lenses, traversals, or prisms.
@package total
@version 1.0.6
module Lens.Family.Complete
class Full a
trivial :: Full a => x -> a
trivial :: (Full a, Generic a, GFull (Rep a)) => x -> a
class GFull f
gtrivial :: GFull f => x -> f a
-- | Synonym for trivial, used to check if a copattern is complete
_cocase :: Full a => x -> a
-- | Copattern match on a Traversal
at :: ((() -> Identity b) -> s -> Identity t) -> (i -> b) -> (i -> s) -> i -> t
-- | & is a reverse application operator. This provides
-- notational convenience. Its precedence is one higher than that of the
-- forward application operator $, which allows & to be
-- nested in $.
--
--
-- >>> 5 & (+1) & show
-- "6"
--
(&) :: () => a -> (a -> b) -> b
infixl 1 &
-- | Fanout: send the input to both argument arrows and combine their
-- output.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')
infixr 3 &&&
instance Lens.Family.Complete.Full ()
instance (Lens.Family.Complete.Full a, Lens.Family.Complete.Full b) => Lens.Family.Complete.Full (a, b)
instance Lens.Family.Complete.Full a => Lens.Family.Complete.Full (Data.Either.Either a b)
instance Lens.Family.Complete.Full a => Lens.Family.Complete.GFull (GHC.Generics.K1 i a)
instance Lens.Family.Complete.GFull GHC.Generics.U1
instance (Lens.Family.Complete.GFull a, Lens.Family.Complete.GFull b) => Lens.Family.Complete.GFull (a GHC.Generics.:*: b)
instance Lens.Family.Complete.GFull a => Lens.Family.Complete.GFull (GHC.Generics.M1 i c a)
instance Lens.Family.Complete.GFull a => Lens.Family.Complete.GFull (a GHC.Generics.:+: b)
-- | This module lets you exhaustively pattern match on types using
-- Lenses, Traversals, or Prisms.
--
-- Here's an example use of this library:
--
--
-- import Lens.Family.Total
-- import Lens.Family.Stock
--
-- total :: Either Char Int -> String -- Same as:
-- total = _case -- total = \case
-- & on _Left (\c -> replicate 3 c ) -- Left c -> replicate 3 c
-- & on _Right (\n -> replicate n '!') -- Right n -> replicate n '!'
--
--
-- Our total function pattern matches exhaustively on the
-- Either type using the _Left and _Right prisms:
--
--
-- >>> total (Left 'X')
-- "XXX"
--
-- >>> total (Right 2)
-- "!!"
--
--
-- The types ensure that the above function is total. For example, if you
-- omit the _Right branch:
--
--
-- partial :: Either Char Int -> String
-- partial = _case
-- & on _Left (\c -> replicate 3 c )
--
--
-- ... then you will get the following type error:
--
--
-- No instance for (Empty Int) arising from a use of ‘_case’
-- In the first argument of ‘(&)’, namely ‘_case’
-- In the expression: _case & on _Left (\ c -> replicate 3 c)
-- In an equation for ‘partial’:
-- partial = _case & on _Left (\ c -> replicate 3 c)
--
--
-- That type error means that you didn't pattern match on the branch with
-- the Int.
--
-- You can also implement exhaustive pattern matching for your own data
-- types with Traversals or Prisms. However, this only
-- works if you have one type variable for each branch of your type:
--
--
-- {-# LANGUAGE DeriveGeneric #-}
-- {-# LANGUAGE TemplateHaskell #-}
--
-- import Control.Lens.TH
-- import GHC.Generics (Generic)
-- import Lens.Family.Total
--
-- data Example a b c = C1 a | C2 b | C3 c deriving (Generic)
--
-- makePrisms ''Example
--
-- instance (Empty a, Empty b, Empty c) => Empty (Example a b c)
--
-- example :: Example String Char Int -> String -- Same as:
-- example = _case -- example = \case
-- & on _C1 (\s -> s ) -- C1 s -> s
-- & on _C2 (\c -> replicate 3 c ) -- C2 c -> replicate 3 c
-- & on _C3 (\n -> replicate n '!') -- C3 n -> replicate n '!'
--
--
-- There is no way to prove that the pattern match is exhaustive unless
-- there is a type parameter for every branch. This is because each
-- successive pattern match Voids out that branch's type parameter
-- to prove that the branch no longer needs to be handled. _case
-- just verifies that all type parameters are Void.
--
-- You can still write an inexhaustive pattern match so long as you
-- provide a default:
--
--
-- example :: Example Int String Float -> String
-- example = _default "default"
-- & on _C2 (\s -> s)
--
--
-- You can even pattern match using Lenses, too:
--
--
-- example :: (Int, Char) -> String -- Same as:
-- example = _case -- example = \case
-- & on _1 (\n -> replicate n '1') -- (n, _) -> replicate n '1'
--
--
-- ... and of course the identity lens (id) works, too:
--
--
-- example :: (Int, Char) -> String -- Same as:
-- example = _case -- example = \case
-- & on id (\(n, c) -> replicate n c) -- (n, c) -> replicate n c
--
module Lens.Family.Total
-- | A type class for uninhabited types
class Empty a
impossible :: Empty a => a -> x
impossible :: (Empty a, Generic a, GEmpty (Rep a)) => a -> x
class GEmpty f
gimpossible :: GEmpty f => f a -> x
-- | Synonym for impossible, used to check if a pattern match is
-- exhaustive
_case :: Empty a => a -> x
-- | Synonym for const, used to provide a default if a pattern match
-- is inexhaustive
_default :: x -> a -> x
-- | Pattern match on a Traversal
on :: ((a -> Either a Void) -> s -> Either a r) -> (a -> o) -> (r -> o) -> s -> o
-- | & is a reverse application operator. This provides
-- notational convenience. Its precedence is one higher than that of the
-- forward application operator $, which allows & to be
-- nested in $.
--
--
-- >>> 5 & (+1) & show
-- "6"
--
(&) :: () => a -> (a -> b) -> b
infixl 1 &
-- | Uninhabited data type
data Void
instance Lens.Family.Total.Empty Data.Void.Void
instance (Lens.Family.Total.Empty a, Lens.Family.Total.Empty b) => Lens.Family.Total.Empty (Data.Either.Either a b)
instance Lens.Family.Total.Empty a => Lens.Family.Total.Empty (a, b)
instance Lens.Family.Total.Empty a => Lens.Family.Total.GEmpty (GHC.Generics.K1 i a)
instance Lens.Family.Total.GEmpty GHC.Generics.V1
instance (Lens.Family.Total.GEmpty a, Lens.Family.Total.GEmpty b) => Lens.Family.Total.GEmpty (a GHC.Generics.:+: b)
instance Lens.Family.Total.GEmpty a => Lens.Family.Total.GEmpty (GHC.Generics.M1 i c a)
instance Lens.Family.Total.GEmpty a => Lens.Family.Total.GEmpty (a GHC.Generics.:*: b)