# `Effable`

_A data structure for emission plans_

![GitHub License](https://img.shields.io/github/license/carlwr/effable)
![Hackage Version](https://img.shields.io/hackage/v/effable)

<br>


```haskell
-- λ> import Effable
-- λ> :info Effable

type Effable :: (* -> *) -> * -> *
newtype Effable m b

instance Semigroup   (Effable m b)
instance Monoid      (Effable m b)

instance Functor     (Effable m)
instance Applicative (Effable m)
instance Monad       (Effable m)

instance Alternative (Effable m)
instance MonadPlus   (Effable m)

instance IsString b => IsString (Effable m b)
```

Links:
* [Hackage page](https://hackage.haskell.org/package/effable)
* [API documentation](https://hackage.haskell.org/package/effable/docs/Effable.html)
* [github.com/carlwr/effable](https://github.com/carlwr/effable)

---
<br>

An `Effable m b` is

- a **pure plan** for the later emission of `b`s

- a representation of an **ordered sequence of `b`s**, each annotated with an *emission wrapper* `m () -> m ()`

- **emitted** to its eventual result `m ()` **with `run`** (*interpretation*/*elimination*)

- fairly **opaque**

  - its constructor is not exported

  - observing it is only supported through `run`/`runWith`

- ***niche: see Caveats section***

## Why?

Compared to just working in the monadic `m b` context, `Effable` brings one particular distinguishing feature:

> An `Effable` can undergo decoration with emission wrappers (`wrap`, `wrapInside`) after which it is still a pure `Effable`.

This means that even after having been modified with wrappers, or any other supported transformation...

- ...it is still a `Functor`, `Applicative` and `Monad` in `b`

- ...it can be transformed further and combined into more complex structures with `<>`

Emission wrappers can be applied to granular constituents of an `Effable` as the user code is building it. The `Effable` machinery will track the wrappers behind-the-scenes through all supported transformations so that the eventual emission respects them.

## Caveats and usage scope

- effectful predicates and emission wrappers typically run more than once when a plan is emitted

  - these actions should yield the same value across evaluations, otherwise the inclusion of branches will be inconsistent

  - *therefore*, `Effable` is only suitable when **these actions are read-like** (return the same value over repeated evaluations and are free of externally observable side-effects)

<!-- -->

- the nesting of combinators and use of `<*>` and `>>=` will grow the internal `Effable` representation, and the number of times actions are run at emission, combinatorially

## Intuition

> `Effable`s are kept pure through all supported transformations by representing all possible outcomes of actions that affect structure. Running the actions is deferred to emission time. This comes with the cost of the internal representation carrying a complexity proportional to all possible outcomes.

Metaphorically, `Effable` is the many-worlds interpretation of *actions* meaning actions can be represented without them interacting with the actual world (= purity) and its representation is not collapsed to an outcome until it is observed (= `run`).

## "Effable"?

*Effable* as in *sayable* or *utterable*.

Or, *Eff-able* as in *able to be effected* or *effectuated* - something with the potential of becoming effects.