### Example: Splitting State Effect

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Demonstrates splitting a `State` effect into read-only (`Get`) and read-write (`Put`) components using `interpret_` and `inject`. This showcases how to decompose complex effects.

```haskell
>>> **:{ 
** data Get s :: Effect where
   Get :: Get s m s
 type instance DispatchOf (Get s) = Dynamic
:} 

>>> **:{ 
** data Put s :: Effect where
   Put :: s -> Put s m ()
 type instance DispatchOf (Put s) = Dynamic
:} 

>>> **import Effectful.State.Static.Local qualified as S
**

>>> **:{ 
** runGetPut :: forall s es a. s -> Eff (Get s : Put s : es) a -> Eff es (a, s)
 runGetPut s0
   = S.runState s0
   . interpret_ @(Put s) (\(Put s) -> S.put s)
   . interpret_ @(Get s) (\Get -> S.get)
   . inject
:} 
```

--------------------------------

### Example usage of putStrLnWithCallStack

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Error-Dynamic

Provides an example of calling the `putStrLnWithCallStack` function and shows the expected output, which includes the provided message followed by a formatted call-stack trace.

```Haskell
putStrLnWithCallStack "hello"
```

--------------------------------

### Example Action with Profiling (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Defines an example action that uses the 'profile' helper to time a simple IO action. The type signature shows the required effect constraints.

```haskell
action = profile "greet" . liftIO $ putStrLn "Hello!"

-- Type signature:
action :: (Profiling :> es, IOE :> es) => Eff es ()
```

--------------------------------

### Example: Augmenting an Effect Handler with interpose

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Demonstrates augmenting an existing effect handler using `interpose` and `passthrough`. This example modifies the behavior of `Op2` while allowing other operations to be handled by the original handler.

```haskell
>>> **:{ 
**  augmentOp2 :: (E :> es, IOE :> es) => Eff es a -> Eff es a
  augmentOp2 = interpose $ \env -> \case
    Op2 -> liftIO (putStrLn "augmented op2") >> send Op2
    op  -> passthrough env op
:} 

>>> **runEff . runE . augmentOp2 $ action
**op1
augmented op2
op2


```

--------------------------------

### Run Example Action with Stdout Logger

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Static

Executes the 'action' using the 'stdoutLogger' and the 'runLog' runner. The output demonstrates the logged messages being printed to the console, followed by the final result 'True'.

```haskell
runEff . runLog stdoutLogger $ action
```

--------------------------------

### Example: Using liftIO with StateT in Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful

This example demonstrates how to use liftIO to embed an IO action (printing the current state) within a StateT monad transformer stack. It highlights the type mismatch error that occurs without liftIO and shows the correct usage for successful execution.

```haskell
import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state
```

--------------------------------

### Haskell: Example of SeqForkUnlift Strategy

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful

Demonstrates the `SeqForkUnlift` strategy for handling effects when unlifting Eff computations. This example shows how `SeqForkUnlift` allows state modifications in unlifted actions to be isolated from the main thread, contrasting with `SeqUnlift` which would cause errors.

```haskell
>>> **import Effectful
**>>> **import Effectful.State.Dynamic
**>>> **:{ 
** action :: (IOE :> es, State Int :> es) => Eff es ()
 action = do
   modify @Int (+1)
   withEffToIO SeqForkUnlift $ \unlift -> unlift $ modify @Int (+2)
   modify @Int (+4)
 **:} 

>>> **runEff . execStateLocal @Int 0 $ action
**5

>>> **runEff . execStateShared @Int 0 $ action
**7

>>> **:{ 
**  delayed :: UnliftStrategy -> IO (IO String)
  delayed strategy = runEff . evalStateLocal "Hey" $ do
    r <- withEffToIO strategy $ \unlift -> pure $ unlift get
    modify (++ "!!!")
    pure r
 **:} 

>>> **join $ delayed SeqForkUnlift
**"Hey"
```

--------------------------------

### Type of Example Action

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Static

Shows the type signature of the 'action' defined previously. It confirms that 'action' is polymorphic in the effect stack 'es' but requires the 'Log' effect to be available (Log :> es).

```haskell
action :: (Log :> es) => Eff es Bool
```

--------------------------------

### Setup Error Handling with Local Unlifting in Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.NonDet

This setup function configures error handling for computations within a local environment. It uses 'localSeqUnlift' to manage effects, allowing computations to be unlifted from a local monad stack ('localEs') into a broader error-handling context ('Error ErrorEmpty : es'). It returns either a successful result or a 'CallStack' indicating an error.

```Haskell
setup :: forall {es :: [(Type -> Type) -> Type -> Type]} {b}.
Eff (Error ErrorEmpty : es) b -> Eff es (Either CallStack b)
setup ((forall {a} {localEs :: [(Type -> Type) -> Type -> Type]}.
  (HasCallStack, NonDet :> localEs) =>
  LocalEnv localEs (Error ErrorEmpty : es)
  -> NonDet (Eff localEs) a -> Eff (Error ErrorEmpty : es) a)
 -> Eff (NonDet : es) a -> Eff es (Either CallStack a))
-> (forall {a} {localEs :: [(Type -> Type) -> Type -> Type]}.
    (HasCallStack, NonDet :> localEs) =>
    LocalEnv localEs (Error ErrorEmpty : es)
    -> NonDet (Eff localEs) a -> Eff (Error ErrorEmpty : es) a)
-> Eff (NonDet : es) a
-> Eff es (Either CallStack a)
```

--------------------------------

### Example: Exception Handling with CallStack

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Shows how `HasCallStack` constraints aid in debugging when an exception is raised during effect handling. The output includes a detailed call stack trace, pinpointing the source of the error.

```haskell
>>> **runEff . runE . augmentOp2 $ send Op3
******* Exception: Op3 not implemented
... 
  error, called at <interactive>:...
  handler, called at src/Effectful/Dispatch/Dynamic.hs:...
  passthrough, called at <interactive>:...
  handler, called at src/Effectful/Dispatch/Dynamic.hs:...
  send, called at <interactive>:...


```

--------------------------------

### Run Example Action with Dummy Logger

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Static

Executes the 'action' using the 'dummyLogger' and the 'runLog' runner. Since the 'dummyLogger' performs no output, only the final result 'True' is shown, demonstrating the effect's execution without side effects.

```haskell
runEff . runLog dummyLogger $ action
```

--------------------------------

### State Operations: Get, Gets, Put, State, Modify in Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.State.Static.Local

Provides core operations for interacting with the 'State' effect. 'get' retrieves the current state, 'gets' applies a function to the state, 'put' updates the state, and 'state' and 'modify' allow for more complex state transformations.

```haskell
-- | Fetch the current value of the state.
get :: (HasCallStack, State s :> es) => Eff es s
get = do
  State s <- getStaticRep
  pure s

-- | Get a function of the current state.
--
-- @'gets' f ≡ f '<$>' 'get'@
gets
  :: (HasCallStack, State s :> es)
  => (s -> a) -- ^ The function to apply to the state.
  -> Eff es a
gets f = f <$> get

-- | Replace the current state with a new value.
put :: (HasCallStack, State s :> es) => s -> Eff es ()
put s = state (const ((), s))

-- | Apply a function to the current state and return a result.
state
  :: (HasCallStack, State s :> es)
  => (s -> (a, s)) -- ^ Function to compute the result and the new state.
  -> Eff es a
state f = do
  s <- get
  let (a, s') = f s
  put s'
  pure a

-- | Apply a function to the current state.
--
-- @'modify' f ≡ 'state' (\s → ((), f s))@
modify :: (HasCallStack, State s :> es) => (s -> s) -> Eff es ()
modify f = state (s -> ((), f s))

-- | Apply a monadic function to the current state and return a result.
stateM
  :: (HasCallStack, State s :> es)
  => (s -> Eff es (a, s))
  -> Eff es a
stateM f = do
  s <- get
  (a, s') <- f s
  put s'
  pure a

-- | Apply a monadic function to the current state.
modifyM :: (HasCallStack, State s :> es) => (s -> Eff es s) -> Eff es ()
modifyM f = stateM (s -> (,s) <$> f s)

```

--------------------------------

### gets

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Labeled.State

Gets a function of the current state.

```APIDOC
## gets

### Description
Gets a function of the current state.

`gets f ≡ f <$> get`

### Method
Not Applicable (Function Signature)

### Endpoint
Not Applicable (Function Signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **a** (a) - The result of applying the function to the current state.

#### Response Example
None
```

--------------------------------

### Reinterpret Effect with Setup

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

Reinterprets an effectful computation with a setup function for encapsulated effects. It takes the setup function, the effect action, and the effect handler, returning a modified effectful computation. This function is for first-order effects.

```haskell
reinterpretWith_ :: (HasCallStack, DispatchOf e ~ Dynamic)
  => (Eff handlerEs a -> Eff es b)
  -> Eff (e : es) a
  -> EffectHandler_ e handlerEs
  -> Eff      es  b
reinterpretWith_ runSetup action handler = reinterpretImpl runSetup action $ \
  HandlerImpl (let ?callStack = thawCallStack ?callStack in const handler)
```

--------------------------------

### Impose Effect with Setup (Alternative Order)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

Imposes an effect handler onto an effectful computation with a setup function. It takes the setup function, the effect action, and the handler, returning a modified computation. This function is for first-order effects.

```haskell
imposeWith_ :: (HasCallStack, DispatchOf e ~ Dynamic, e :> es)
  => (Eff handlerEs a -> Eff es b)
  -> Eff es a
  -> EffectHandler_ e handlerEs
  -> Eff es b
imposeWith_ runSetup action handler = imposeImpl runSetup action $ \
  HandlerImpl (let ?callStack = thawCallStack ?callStack in const handler)
```

--------------------------------

### Example: Handling Multiple Operations with interpose

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Illustrates how to use `interpose` to handle multiple operations (`Op1`, `Op2`, `Op3`) of an effect `E`. It shows basic operation handling and error handling for unimplemented operations.

```haskell
>>> **:{ 
**  data E :: Effect where
    Op1 :: E m ()
    Op2 :: E m ()
    Op3 :: E m ()
  type instance DispatchOf E = Dynamic
:} 

>>> **:{ 
**  runE :: IOE :> es => Eff (E : es) a -> Eff es a
  runE = interpret_ $ \case
    Op1 -> liftIO (putStrLn "op1")
    Op2 -> liftIO (putStrLn "op2")
    Op3 -> error "Op3 not implemented"
:} 

>>> **let action = send Op1 >> send Op2
**

>>> **runEff . runE $ action
**op1
op2


```

--------------------------------

### Impose Effect with Setup and Handler

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

Imposes an effect handler onto an effectful computation, allowing for setup of encapsulated effects. It takes a setup function, an effect handler, and the action, returning a new computation. This is for first-order effects.

```haskell
impose_ :: (HasCallStack, DispatchOf e ~ Dynamic, e :> es)
  => (Eff handlerEs a -> Eff es b)
  -> EffectHandler_ e handlerEs
  -> Eff es a
  -> Eff es b
impose_ runSetup handler action = imposeImpl runSetup action $ \
  HandlerImpl (let ?callStack = thawCallStack ?callStack in const handler)
```

--------------------------------

### Define and Run a FileSystem Action

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

This example defines a simple action that reads a file and checks if its content is non-empty. It then demonstrates how to run this action using both a pure interpretation (runFileSystemPure) and an IO-based interpretation (runFileSystemIO), including error handling.

```haskell
action :: (FileSystem :> es) => Eff es Bool
action = do
  file <- readFile "effectful-core.cabal"
  pure $ length file > 0

-- Running with IO interpretation:
-- runEff . runError @FsError . runFileSystemIO $ action

-- Running with pure interpretation:
-- runPureEff . runErrorNoCallStack @FsError . runFileSystemPure M.empty $ action

```

--------------------------------

### Reinterpret Effect with Setup and Handler

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

Reinterprets an effectful computation, allowing for setup of encapsulated effects within the handler. It takes a setup function, an effect handler, and the action to reinterpret, returning a new effectful computation. This is for first-order effects.

```haskell
reinterpret_ :: (HasCallStack, DispatchOf e ~ Dynamic)
  => (Eff handlerEs a -> Eff es b)
  -> EffectHandler_ e handlerEs
  -> Eff (e : es) a
  -> Eff      es  b
reinterpret_ runSetup handler action = reinterpretImpl runSetup action $ \
  HandlerImpl (let ?callStack = thawCallStack ?callStack in const handler)
```

--------------------------------

### Haskell: Get Function of State

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Labeled-State

Retrieves a value derived from the current state by applying a given function. This operation is built upon the 'get' operation.

```haskell
gets :: forall label s es a. (HasCallStack, Labeled label (State s) :> es) => (s -> a) -> Eff es a
gets f = f <$> get
```

--------------------------------

### Functional Dependencies with MonadInput and Eff

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Demonstrates how to use functional dependencies with the MonadInput class and the Eff monad, including a workaround for the liberal coverage condition.

```APIDOC
## Functional Dependencies with MonadInput and Eff

### Description
This section explains how to handle classes with functional dependencies, specifically `MonadInput`, when working with the `Eff` monad. It highlights a common issue with the liberal coverage condition and provides a solution by including the instance head in the context.

### Method
N/A (Illustrative code examples)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```haskell
-- Enabling Functional Dependencies
:set -XFunctionalDependencies

-- Class definition
class Monad m => MonadInput i m | m -> i where
  input :: m i

-- Attempt leading to violation
-- instance Reader i :> es => MonadInput i (Eff es) where
--   input = ask

-- Corrected instance declaration
instance (MonadInput i (Eff es), Reader i :> es) => MonadInput i (Eff es) where
  input = ask

-- Usage example
double :: MonadInput Int m => m Int
double = (+) <$> input <*> input

-- Running the example
runPureEff . runReader @Int 3 $ double
```

### Response
#### Success Response (200)
N/A (Illustrative output)

#### Response Example
```
6
```
```

--------------------------------

### reinterpretWith_ API

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Dispatch.Dynamic

Reinterprets a first-order effect with a setup function. This is similar to `reinterpret_` but explicitly includes a setup function for effect transformation.

```APIDOC
## POST /websites/hackage-content_haskell_package_effectful-core-2_6_1_0/reinterpretWith_

### Description
Reinterprets a first-order effect with a setup function. This is similar to `reinterpret_` but explicitly includes a setup function for effect transformation.

### Method
POST

### Endpoint
/websites/hackage-content_haskell_package_effectful-core-2_6_1_0/reinterpretWith_

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **setup** (Eff handlerEs a -> Eff es b) - Required - Setup of effects encapsulated in the handler.
- **action** (Eff (e : es) a) - Required - The effect action to reinterpret.
- **handler** (EffectHandler_ e handlerEs) - Required - The effect handler.

### Request Example
```json
{
  "setup": "(Eff handlerEs a -> Eff es b)",
  "action": "Eff (e : es) a",
  "handler": "EffectHandler_ e handlerEs"
}
```

### Response
#### Success Response (200)
- **result** (Eff es b) - The reinterpreted effect.

#### Response Example
```json
{
  "result": "Eff es b"
}
```
```

--------------------------------

### GHC.Show Instance for CallStack

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Labeled-Error

Details about the Show instance for the CallStack type, including showsPrec, show, and showList functions for formatting CallStack information.

```APIDOC
## GHC.Show Instance for CallStack

### Description
Provides functions to format a `CallStack` for display, including pretty printing and showing lists of CallStacks.

### Method
N/A (Instance Definition)

### Endpoint
N/A (Instance Definition)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Show instance for CallStack in Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-NonDet

The `Show` instance for `CallStack` provides functions to convert a `CallStack` into a `String` representation. `showsPrec` is used for showing with precedence, and `show` provides a basic string conversion.

```Haskell
showsPrec :: Int -> CallStack -> ShowS
```

```Haskell
show :: CallStack -> String
```

```Haskell
showList :: [CallStack] -> ShowS
```

--------------------------------

### Get Function of State in Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Static-Shared

Retrieves a value by applying a function to the current state. This is a convenience function equivalent to 'f <$> get'. Requires 'State' effect and 'HasCallStack'.

```haskell
gets :: (HasCallStack, State s :> es) => (s -> a) -> Eff es a Source #
```
gets f ≡ f <$> get
```
```

--------------------------------

### Show Instance for SomeException

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Exception

Provides the 'Show' instance for the 'SomeException' type, allowing it to be converted to a string representation. This is available since base-3.0.

```haskell
instance Show SomeException where
  showsPrec :: Int -> SomeException -> ShowS
  show :: SomeException -> String
  showList :: [SomeException] -> ShowS
```

--------------------------------

### Get State Value Transformed by Function in Effectful

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/State/Dynamic

Applies a given function to the current state and returns the result. This is equivalent to getting the state and then applying the function to it.

```haskell
gets
  :: (HasCallStack, State s :> es)
  => (s -> a)
  -> Eff es a
gets f = f <$> get
```

--------------------------------

### Get State Value Using a Function - Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/State/Static/Local

Retrieves a value derived from the current state by applying a given function. This is a convenience function equivalent to applying a function to the result of 'get'.

```Haskell
gets
  :: (HasCallStack, State s :> es)
  => (s -> a) -- ^ The function to apply to the state.
  -> Eff es a
gets f = f <$> get
```

--------------------------------

### Define and Run a Profiling Action

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/src/src/Effectful/Dispatch/Dynamic

This example defines an action that uses the 'profile' function to measure the execution time of a simple IO action (printing "Hello!"). It then shows how to run this action using both the 'runProfiling' interpreter (which will print timing information) and the 'runNoProfiling' interpreter (which will not).

```haskell
import Effectful.IO (liftIO)

action :: (Profiling :> es, IOE :> es) => Eff es ()
action = profile "greet" . liftIO $ putStrLn "Hello!"

-- Running with profiling:
-- runEff . runProfiling $ action

-- Running without profiling:
-- runEff . runNoProfiling $ action

```

--------------------------------

### Get Derived State Value (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Labeled.State

Applies a function to the current state and returns the result. This is a convenience function equivalent to applying a function to the result of 'get'.

```haskell
gets
  :: forall label s es a
   . (HasCallStack, Labeled label (State s) :> es)
  => (s -> a)
  -- ^ Function to apply to the current state.
  -> Eff es a
```

--------------------------------

### Running the State Effect with Initial State

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Static-Shared

Demonstrates how to run the `State` effect using `runState`, `evalState`, and `execState` with an initial state value. These functions are crucial for initializing and managing the state throughout the computation.

```haskell
runState :: HasCallStack => s -> Eff (State s : es) a -> Eff es (a, s)
evalState :: HasCallStack => s -> Eff (State s : es) a -> Eff es a
execState :: HasCallStack => s -> Eff (State s : es) a -> Eff es s

```

--------------------------------

### Execute Action with IO Handler using runProvider_

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Provider

Demonstrates running the 'action' defined earlier with the IO-based handler 'runWriteIO' using 'runProvider_'. The output shows the messages being printed to the console with their respective file paths.

```haskell
>>> **:{ 
**  runEff
    . runProvider_ runWriteIO
    $ action
:} 

```

--------------------------------

### imposeWith_ API

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Dispatch.Dynamic

Imposes an effect handler with a specific setup function for first-order effects. This is a variation of 'impose_' that takes the setup function as the first argument.

```APIDOC
## POST /effect/imposeWith_

### Description
Imposes an effect handler with a specific setup function for first-order effects. This is a variation of 'impose_' that takes the setup function as the first argument.

### Method
POST

### Endpoint
/effect/imposeWith_

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **setup** (Eff handlerEs a -> Eff es b) - Required - Setup of effects encapsulated in the handler.
- **action** (Eff es a) - Required - The action to be performed.
- **handler** (EffectHandler_ e handlerEs) - Required - The effect handler.

### Request Example
```json
{
  "setup": "Eff handlerEs a -> Eff es b",
  "action": "Eff es a",
  "handler": "EffectHandler_ e handlerEs"
}
```

### Response
#### Success Response (200)
- **result** (Eff es b) - The result of the action after the handler has been imposed.

#### Response Example
```json
{
  "result": "Eff es b"
}
```
```

--------------------------------

### Show Instances for CompactionFailed

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Exception

Provides instances for the Show type class for the CompactionFailed newtype. This enables CompactionFailed values to be converted to strings for display. It defines showsPrec, show, and showList.

```Haskell
instance Show CompactionFailed

showsPrec :: Int -> CompactionFailed -> ShowS
show :: CompactionFailed -> String
showList :: [CompactionFailed] -> ShowS
```

--------------------------------

### Reinterpret With Effect Handler (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Dispatch.Dynamic

Allows reinterpreting effects with an additional setup function. This is useful when the reinterpretation logic itself depends on the context provided by the setup.

```haskell
reinterpretWith_ :: forall (e :: Effect) (handlerEs :: [Effect]) a (es :: [Effect]) b.
(HasCallStack, DispatchOf e ~ 'Dynamic) =>
(Eff handlerEs a -> Eff es b)
-> Eff (e : es) a -> EffectHandler_ e handlerEs -> Eff es b
reinterpretWith_ Eff handlerEs a -> Eff es b
runSetup Eff (e : es) a
action EffectHandler_ e handlerEs
handler = (Eff handlerEs a -> Eff es b)
-> Eff (e : es) a -> HandlerImpl e handlerEs -> Eff es b
forall (e :: Effect) (handlerEs :: [Effect]) a (es :: [Effect]) b.
(HasCallStack, DispatchOf e ~ 'Dynamic) =>
(Eff handlerEs a -> Eff es b)
-> Eff (e : es) a -> HandlerImpl e handlerEs -> Eff es b
reinterpretImpl Eff handlerEs a -> Eff es b
runSetup Eff (e : es) a
action (HandlerImpl e handlerEs -> Eff es b)
-> HandlerImpl e handlerEs -> Eff es b
forall a b. (a -> b) -> a -> b
$
  EffectHandler e handlerEs -> HandlerImpl e handlerEs
forall (e :: Effect) (es :: [Effect]).
EffectHandler e es -> HandlerImpl e es
HandlerImpl (let ?callStack = CallStack -> CallStack
thawCallStack HasCallStack
CallStack
?callStack in (e (Eff localEs) a -> Eff handlerEs a)
-> LocalEnv localEs handlerEs
-> e (Eff localEs) a
-> Eff handlerEs a
forall a b. a -> b -> a
const e (Eff localEs) a -> Eff handlerEs a
EffectHandler_ e handlerEs
handler)
```

--------------------------------

### Show Instances for AllocationLimitExceeded

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Exception

Provides instances for the Show type class for the AllocationLimitExceeded data type. This enables AllocationLimitExceeded values to be converted to strings for display. It defines showsPrec, show, and showList.

```Haskell
instance Show AllocationLimitExceeded

showsPrec :: Int -> AllocationLimitExceeded -> ShowS
show :: AllocationLimitExceeded -> String
showList :: [AllocationLimitExceeded] -> ShowS
```

--------------------------------

### State Effect Operations

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.State.Dynamic

Core operations for interacting with the State effect, including getting the current state, getting a modified part of the state, putting a new state, and modifying the state.

```APIDOC
## State Effect Operations

### Description
Core operations for interacting with the 'State' effect.

### Method
Operation

### Endpoint
N/A (Effectful library functions)

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```haskell
-- Example usage (conceptual)
-- get
-- gets (fmap snd)
-- put newState
-- state (\(s, x) -> (s + 1, x * 2))
-- modify (+1)
-- stateM (\s -> pure (s, s + 1))
-- modifyM (\s -> pure (s + 1))
```

### Response
#### Success Response (200)
- **get**: Returns the current state.
- **gets**: Returns a value derived from the current state.
- **put**: Updates the state to a new value.
- **state**: Updates the state and returns a value based on the old state.
- **modify**: Applies a function to update the state.
- **stateM**: Asynchronously updates the state and returns a value.
- **modifyM**: Asynchronously applies a function to update the state.

#### Response Example
```haskell
-- Example response structure (conceptual)
-- currentState
-- derivedValue
-- ()
-- newValue
-- ()
-- monadicResult
-- monadicResult
```
```

--------------------------------

### State Effect Helper Function Definitions (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Static-Local

Shows the definitions or equivalences for helper functions within the `State` effect, such as `gets` and `modify`, illustrating their relationship to more fundamental operations like `get` and `state`.

```haskell
gets f = f <$> get

modify f = state (s -> ((), f s))

modifyM f = stateM (s -> ((), ) <$> f s)
```

--------------------------------

### Haskell Compilation and Haddock Generation for transformers-base

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/reports/1/log

This snippet shows the command-line output for compiling the 'transformers-base' Haskell library and generating Haddock documentation. It includes messages about preprocessing, Haddock execution, warnings, compilation status, and final installation paths.

```text
Preprocessing library for transformers-base-0.4.6..
Running Haddock on library for transformers-base-0.4.6..
Warning: --source-* options are ignored when --hyperlinked-source is enabled.
[1 of 1] Compiling Control.Monad.Base ( src/Control/Monad/Base.hs, nothing )
Haddock coverage:
  33% (  1 /  3) in 'Control.Monad.Base'
  Missing documentation for:
    Module header
    MonadBase (src/Control/Monad/Base.hs:60)
Documentation created: dist/doc/html/transformers-base/,
dist/doc/html/transformers-base/transformers-base.txt
Installing library in /var/lib/hackage-doc-builder/build-cache/tmp-install/lib/x86_64-linux-ghc-9.8.4/transformers-base-0.4.6-IL0Wd7HO1bp151a2hrrU7W
Completed    transformers-base-0.4.6
```

--------------------------------

### provideListWith Operation

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Provider-List

Runs the handler associated with the `ProviderList` effect, providing an explicit input.

```APIDOC
provideListWith Source #

### Arguments

- **Input**: `input` - The input to the handler.
- **Effectful Computation**: `Eff (providedEs ++ es) a` - The computation to run.

### Returns

- `Eff es (f a)` - The result of the computation after handling, potentially with an altered return type.

**Description**: Run the handler with a given input.
```

--------------------------------

### State Effect Operations

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Dynamic

Defines core operations for interacting with the State effect: get, gets, put, state, modify, stateM, and modifyM. These allow fetching, updating, and transforming the state within an Eff monad.

```haskell
get :: (HasCallStack, State s :> es) => Eff es s
gets :: (HasCallStack, State s :> es) => (s -> a) -> Eff es a
put :: (HasCallStack, State s :> es) => s -> Eff es ()
state :: (HasCallStack, State s :> es) => (s -> (a, s)) -> Eff es a
modify :: (HasCallStack, State s :> es) => (s -> s) -> Eff es ()
stateM :: (HasCallStack, State s :> es) => (s -> Eff es (a, s)) -> Eff es a
modifyM :: (HasCallStack, State s :> es) => (s -> Eff es s) -> Eff es ()
```

--------------------------------

### Define Example Action Using Log Effect

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Static

Defines an 'action' that utilizes the custom 'log' operation. This action logs three messages sequentially and then returns 'True'. Its type signature indicates it requires the 'Log' effect to be present in the execution context.

```haskell
action = do
  log "Computing things..."
  log "Sleeping..."
  log "Computing more things..."
  pure True
```

--------------------------------

### Accessing and Modifying State

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Static-Shared

Details the core operations for interacting with the `State` effect: `get` to retrieve the current state, `gets` to retrieve a part of the state, `put` to update the state, `state` to perform a state transformation, and `modify` to apply a function to the state.

```haskell
get :: (HasCallStack, State s :> es) => Eff es s
gets :: (HasCallStack, State s :> es) => (s -> a) -> Eff es a
put :: (HasCallStack, State s :> es) => s -> Eff es ()
state :: (HasCallStack, State s :> es) => (s -> (a, s)) -> Eff es a
modify :: (HasCallStack, State s :> es) => (s -> s) -> Eff es ()

```

--------------------------------

### Running Fork Effect with Unmasking (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Dynamic

Demonstrates how to run a `Fork` effect, which includes a `ForkWithUnmask` constructor. This example utilizes `withLiftMapIO` and `localUnliftIO` to manage the unmasking function within the effectful computation, allowing for safe concurrency operations like `forkIOWithUnmask`.

```Haskell
data Fork :: Effect where
  ForkWithUnmask :: ((forall a. m a -> m a) -> m ()) -> Fork m ThreadId
type instance DispatchOf Fork = Dynamic

runFork :: IOE :> es => Eff (Fork : es) a -> Eff es a
runFork = interpret $ \env (ForkWithUnmask m) -> withLiftMapIO env $ \liftMap -> do
  localUnliftIO env (ConcUnlift Ephemeral $ Limited 1) $ \unlift -> do
    forkIOWithUnmask $ \unmask -> unlift $ m $ liftMap unmask
```

--------------------------------

### State Effect Operations (Haskell)

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-State-Static-Local

Provides a synopsis of the core operations for the `State` effect, including running the effect with different handlers (`runState`, `evalState`, `execState`) and manipulating the state (`get`, `gets`, `put`, `state`, `modify`, `stateM`, `modifyM`).

```haskell
data State (s :: Type) :: Effect

runState :: HasCallStack => s -> Eff (State s : es) a -> Eff es (a, s)
evalState :: HasCallStack => s -> Eff (State s : es) a -> Eff es a
execState :: HasCallStack => s -> Eff (State s : es) a -> Eff es s
get :: (HasCallStack, State s :> es) => Eff es s
gets :: (HasCallStack, State s :> es) => (s -> a) -> Eff es a
put :: (HasCallStack, State s :> es) => s -> Eff es ()
state :: (HasCallStack, State s :> es) => (s -> (a, s)) -> Eff es a
modify :: (HasCallStack, State s :> es) => (s -> s) -> Eff es ()
stateM :: (HasCallStack, State s :> es) => (s -> Eff es (a, s)) -> Eff es a
modifyM :: (HasCallStack, State s :> es) => (s -> Eff es s) -> Eff es ()
```

--------------------------------

### Alternative Instances

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-NonDet

This section lists and describes the various Alternative instances provided by the effectful-core package and its dependencies.

```APIDOC
## Alternative Instances

This section details the various `Alternative` instances available in the `effectful-core` package and its dependencies.

### Instance: ZipList

- **Since**: base-4.11.0.0
- **Defined in**: Control.Applicative
- **Methods**: `empty :: ZipList a`, `(<|>) :: ZipList a -> ZipList a -> ZipList a`, `some :: ZipList a -> ZipList [a]`, `many :: ZipList a -> ZipList [a]`

### Instance: STM

- **Description**: Takes the first non-`retry`ing `STM` action.
- **Since**: base-4.8.0.0
- **Defined in**: GHC.Conc.Sync
- **Methods**: `empty :: STM a`, `(<|>) :: STM a -> STM a -> STM a`, `some :: STM a -> STM [a]`, `many :: STM a -> STM [a]`

### Instance: P

- **Since**: base-4.5.0.0
- **Defined in**: Text.ParserCombinators.ReadP
- **Methods**: `empty :: P a`, `(<|>) :: P a -> P a -> P a`, `some :: P a -> P [a]`, `many :: P a -> P [a]`

### Instance: ReadP

- **Since**: base-4.6.0.0
- **Defined in**: Text.ParserCombinators.ReadP
- **Methods**: `empty :: ReadP a`, `(<|>) :: ReadP a -> ReadP a -> ReadP a`, `some :: ReadP a -> ReadP [a]`, `many :: ReadP a -> ReadP [a]`

### Instance: IO

- **Description**: Takes the first non-throwing `IO` action's result. `empty` throws an exception.
- **Since**: base-4.9.0.0
- **Defined in**: GHC.Base
- **Methods**: `empty :: IO a`, `(<|>) :: IO a -> IO a -> IO a`, `some :: IO a -> IO [a]`, `many :: IO a -> IO [a]`

### Instance: SmallArray

- **Defined in**: Data.Primitive.SmallArray
- **Methods**: `empty :: SmallArray a`, `(<|>) :: SmallArray a -> SmallArray a -> SmallArray a`, `some :: SmallArray a -> SmallArray [a]`, `many :: SmallArray a -> SmallArray [a]`

### Instance: Maybe

- **Description**: Picks the leftmost `Just` value, or, alternatively, `Nothing`.
- **Since**: base-2.1
- **Defined in**: GHC.Base
- **Methods**: `empty :: Maybe a`, `(<|>) :: Maybe a -> Maybe a -> Maybe a`, `some :: Maybe a -> Maybe [a]`, `many :: Maybe a -> Maybe [a]`

### Instance: List

- **Description**: Combines lists by concatenation, starting from the empty list.
- **Since**: base-2.1
- **Defined in**: GHC.Base
- **Methods**: `empty :: [a]`, `(<|>) :: [a] -> [a] -> [a]`, `some :: [a] -> [[a]]`, `many :: [a] -> [[a]]`

### Instance: WrappedMonad m

- **Since**: base-2.1
- **Defined in**: Control.Applicative
- **Methods**: `empty :: WrappedMonad m a`, `(<|>) :: WrappedMonad m a -> WrappedMonad m a -> WrappedMonad m a`, `some :: WrappedMonad m a -> WrappedMonad m [a]`, `many :: WrappedMonad m a -> WrappedMonad m [a]`

### Instance: ArrowMonad a

- **Since**: base-4.6.0.0
- **Defined in**: Control.Arrow
- **Methods**: `empty :: ArrowMonad a a0`, `(<|>) :: ArrowMonad a a0 -> ArrowMonad a a0 -> ArrowMonad a a0`, `some :: ArrowMonad a a0 -> ArrowMonad a [a0]`, `many :: ArrowMonad a a0 -> ArrowMonad a [a0]`

### Instance: Proxy (Type -> Type)

- **Since**: base-4.9.0.0
- **Defined in**: Data.Proxy
- **Methods**: `empty :: Proxy a`, `(<|>) :: Proxy a -> Proxy a -> Proxy a`, `some :: Proxy a -> Proxy [a]`, `many :: Proxy a -> Proxy [a]`

### Instance: U1 (Type -> Type)

- **Since**: base-4.9.0.0
- **Defined in**: GHC.Generics
- **Methods**: `empty :: U1 a`, `(<|>) :: U1 a -> U1 a -> U1 a`, `some :: U1 a -> U1 [a]`, `many :: U1 a -> U1 [a]`

### Instance: Eff es

- **Since**: 2.2.0.0
- **Defined in**: Effectful.Internal.Monad
- **Methods**: `empty :: Eff es a`, `(<|>) :: Eff es a -> Eff es a -> Eff es a`, `some :: Eff es a -> Eff es [a]`, `many :: Eff es a -> Eff es [a]`

### Instance: MaybeT m

- **Defined in**: Control.Monad.Trans.Maybe
- **Methods**: `empty :: MaybeT m a`, `(<|>) :: MaybeT m a -> MaybeT m a -> MaybeT m a`, `some :: MaybeT m a -> MaybeT m [a]`, `many :: MaybeT m a -> MaybeT m [a]`

### Instance: WrappedArrow a b

- **Since**: base-2.1
- **Defined in**: Control.Applicative
- **Methods**: `empty :: WrappedArrow a b a0`, `(<|>) :: WrappedArrow a b a0 -> WrappedArrow a b a0 -> WrappedArrow a b a0`, `some :: WrappedArrow a b a0 -> WrappedArrow a b [a0]`, `many :: WrappedArrow a b a0 -> WrappedArrow a b [a0]`

### Instance: Kleisli m a

- **Since**: base-4.14.0.0
- **Defined in**: Control.Arrow
- **Methods**: `empty :: Kleisli m a a0`, `(<|>) :: Kleisli m a a0 -> Kleisli m a a0 -> Kleisli m a a0`, `some :: Kleisli m a a0 -> Kleisli m a [a0]`, `many :: Kleisli m a a0 -> Kleisli m a [a0]`

### Instance: Ap f

- **Since**: base-4.12.0.0
- **Defined in**: Data.Monoid
- **Methods**: `empty :: Ap f a`, `(<|>) :: Ap f a -> Ap f a -> Ap f a`, `some :: Ap f a -> Ap f [a]`, `many :: Ap f a -> Ap f [a]`

### Instance: Alt f

- **Since**: base-4.8.0.0
- **Defined in**: Data.Semigroup.Internal
- **Methods**: `empty :: Alt f a`, `(<|>) :: Alt f a -> Alt f a -> Alt f a`, `some :: Alt f a -> Alt f [a]`, `many :: Alt f a -> Alt f [a]`

### Instance: Generically1 f

- **Since**: base-4.17.0.0
- **Defined in**: GHC.Generics
- **Methods**: `empty :: Generically1 f a`, `(<|>) :: Generically1 f a -> Generically1 f a -> Generically1 f a`, `some :: Generically1 f a -> Generically1 f [a]`, `many :: Generically1 f a -> Generically1 f [a]`

### Instance: Rec1 f

- **Since**: base-4.9.0.0
- **Defined in**: Control.Applicative
- **Methods**: `empty :: Rec1 f a`, `(<|>) :: Rec1 f a -> Rec1 f a -> Rec1 f a`, `some :: Rec1 f a -> Rec1 f [a]`, `many :: Rec1 f a -> Rec1 f [a]`
```

--------------------------------

### Run Writer Effect and Get Output - Haskell

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Writer.Static.Shared

Runs a Writer effect and returns both the final result and the accumulated output. It initializes a new MVar for the writer's state with the monoidal identity and then evaluates the effect, finally reading the MVar to get the accumulated output.

```haskell
runWriter :: forall w (es :: [(Type -> Type) -> Type -> Type]) a.
(HasCallStack, Monoid w) =>
Eff (Writer w : es) a -> Eff es (a, w)
runWriter m = do
  v <- unsafeEff_ (newMVar' mempty)
  a <- evalStaticRep (Writer v) m
  (a,) <$> unsafeEff_ (readMVar' v)
```

--------------------------------

### Execute Action with Pure Handler using runProvider_

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Provider

Shows how to execute the 'action' with the pure 'runWritePure' handler. The result is the final state of the State monad, containing a map of file paths to lists of written messages, reversed for demonstration.

```haskell
>>> **:{ 
**  runPureEff
    . fmap (fmap reverse)
    . execState @(M.Map FilePath [String]) M.empty
    . runProvider_ runWritePure
    $ action
:} 

```

--------------------------------

### get

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/src/Effectful.Labeled.State

Fetches the current value of the state.

```APIDOC
## get

### Description
Fetches the current value of the state.

### Method
Not Applicable (Function Signature)

### Endpoint
Not Applicable (Function Signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **s** (s) - The current state value.

#### Response Example
None
```

--------------------------------

### Define Dummy Logger

Source: https://hackage-content.haskell.org/package/effectful-core-2.6.1.0/docs/Effectful-Dispatch-Static

Creates a 'dummyLogger' instance that performs no actual logging. Its 'logMessage' action simply returns 'pure ()', making it suitable for testing or scenarios where logging is not required.

```haskell
dummyLogger = Logger { logMessage = \_ -> pure () }
```