HORIZON HASKELLDocslts/ghc-10.0.x8c2f8e82026-10-19Search names, modules, packages, or :: a typeCtrl K

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 8c2f8e8 · 2026-10-19

Modulefused-effects-1.1.2.7Haskell2010

Control.Effect.NonDet

An effect modelling nondeterminism with choice and failure.

Nondeterministic operations are encapsulated by the Alternative class, where empty represents failure and <|> represents choice. This module re-exports the Alternative interface. If you can't or don't want to use Alternative, you can use the empty and <|> operations (from Control.Effect.Empty and Control.Effect.Choose respectively) directly, as the NonDet effect is the composition of Choose and Empty.

Predefined carriers:

  • Control.Carrier.NonDet.Church, which collects all branches' results using an Alternative functor.

  • If NonDet is the last effect in a stack, it can be interpreted directly into a [].

  • 4 types
  • 3 classes
  • 5 values

NonDet effects

5 declarations
datadata Choose (m :: Type -> Type) k where
#

Constructors

Instances6Algebra
datadata Empty (m :: Type -> Type) k where
#

Constructors

Instances8Algebra, …
valueoneOf :: (Foldable t, Alternative m) => t a -> m a
#

Nondeterministically choose an element from a Foldable collection. This can be used to emulate the style of nondeterminism associated with programming in the list monad:

  pythagoreanTriples = do
    a <- oneOf [1..10]
    b <- oneOf [1..10]
    c <- oneOf [1..10]
    guard (a^2 + b^2 == c^2)
    pure (a, b, c)

Re-exports

7 declarations
classclass Applicative f => Alternative (f :: Type -> Type) where
#

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

Examples
Example1 expression
Nothing <|> Just 42Just 42
Example1 expression
[1, 2] <|> [3, 4][1,2,3,4]
Example1 expression
empty <|> print (2^15)32768

Methods

  • empty :: f a

    The identity of <|>

    empty <|> a     == a
a     <|> empty == a
  • (<|>) :: f a -> f a -> f ainfixl 3

    An associative binary operation

  • some :: f a -> f [a]

    One or more.

    Examples
    Example1 expression
    some (putStr "la")lalalalalalalalala... * goes on forever *
    Example1 expression
    some Nothingnothing
    Example1 expression
    take 5 <$> some (Just 1)* hangs forever *

    Note that this function can be used with Parsers based on Applicatives. In that case some parser will attempt to parse parser one or more times until it fails.

  • many :: f a -> f [a]

    Zero or more.

    Examples
    Example1 expression
    many (putStr "la")lalalalalalalalala... * goes on forever *
    Example1 expression
    many NothingJust []
    Example1 expression
    take 5 <$> many (Just 1)* hangs forever *

    Note that this function can be used with Parsers based on Applicatives. In that case many parser will attempt to parse parser zero or more times until it fails.

Instances67Alternative, …
classclass Monad m => Algebra (sig :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) | m -> sig where
#

The class of carriers (results) for algebras (effect handlers) over signatures (effects), whose actions are given by the alg method.

Instances53Algebra, …
typetype Has (eff :: (Type -> Type) -> Type -> Type) (sig :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) = (Members eff sig, Algebra sig m)
#

m is a carrier for sig containing eff.

Note that if eff is a sum, it will be decomposed into multiple Member constraints. While this technically allows one to combine multiple unrelated effects into a single Has constraint, doing so has two significant drawbacks:

  1. Due to a problem with recursive type families, this can lead to significantly slower compiles.

  2. It defeats ghc’s warnings for redundant constraints, and thus can lead to a proliferation of redundant constraints as code is changed.

classclass (Alternative m, Monad m) => MonadPlus (m :: Type -> Type) where
#

Monads that also support choice and failure.

Methods

  • mzero :: m a

    The identity of mplus. It should also satisfy the equations

    mzero >>= f  =  mzero
v >> mzero   =  mzero

    The default definition is

    mzero = empty
  • mplus :: m a -> m a -> m a

    An associative operation. The default definition is

    mplus = (<|>)
Instances59MonadPlus, …
valueguard :: Alternative f => Bool -> f ()
#

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty
Examples

Common uses of guard include conditionally signalling an error in an error monad and conditionally rejecting the current choice in an Alternative-based parser.

As an example of signalling an error in the error monad Maybe, consider a safe division function safeDiv x y that returns Nothing when the denominator y is zero and Just (x `div` y) otherwise. For example:

Example1 expression
safeDiv 4 0Nothing
Example1 expression
safeDiv 4 2Just 2

A definition of safeDiv using guards, but not guard:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

A definition of safeDiv using guard and Monad do-notation:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)
valueoptional :: Alternative f => f a -> f (Maybe a)
#

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

Example1 expression
import Control.Monad.Except
Example2 expressions
canFail = throwError "it failed" :: Except String Intfinal = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

Example1 expression
runExcept $ canFail *> finalLeft "it failed"
Example1 expression
runExcept $ optional canFail *> finalRight 42
valuerun :: Identity a -> a
#

Run an action exhausted of effects to produce its final result value.