Add Final Effect

ChangeLog.md

@@ -1,5 +1,34 @@
 # Changelog for polysemy
 
+
+## 1.2.0.0 (TODO)
+
+### Breaking Changes
+
+- All `lower-` interpreters have been deprecated, in favor of corresponding
+    `-Final` interpreters.
+- `runFixpoint` and `runFixpointM` have been deprecated in favor of `fixpointToFinal`.
+- The semantics for `runNonDet` when `<|>` is used inside a higher-order action of
+    another effect has been changed.
+- Type variables for certain internal functions and `failToEmbed` have been rearranged.
+
+## Other changes
+
+- Added `Final` effect, an effect for embedding higher-order actions in the
+    final monad of the effect stack. Any interpreter should use this instead of
+    requiring to be provided an explicit lowering function to the final monad.
+- Added `Strategy` environment for use together with `Final`
+- Added `asyncToIOFinal`, a better alternative of `lowerAsync`
+- Added `errorToIOFinal`, a better alternative of `lowerError`
+- Added `fixpointToFinal`, a better alternative of `runFixpoint` and `runFixpointM`
+- Added `resourceToIOFinal`, a better alternative of `lowerResource`
+- Added `outputToIOMonoid` and `outputToIOMonoidAssocR`
+- Added `runWriterTVar`, `writerToIOFinal`, and `writerToIOAssocRFinal`
+- Added `writerToEndoWriter`
+- Added `subsume` operation
+- Exposed `raiseUnder`/`2`/`3` in `Polysemy`
+
+
 ## 1.1.0.0 (2019-08-15)
 
 ### Breaking Changes

src/Polysemy/Fixpoint.hs

@@ -34,8 +34,8 @@ import Polysemy.Internal.Fixpoint
 -- bad =
 --    'Data.Functor.Identity.runIdentity'
 --  . 'runFinal'
---  . 'fixpointToFinal' @'Data.Functor.Identity.Identity'
---  . 'Polysemy.State.runLazyState' @Int 1
+--  . 'fixpointToFinal' \@'Data.Functor.Identity.Identity'
+--  . 'Polysemy.State.runLazyState' \@Int 1
 --  . 'Polysemy.Error.runError'
 --  $ mdo
 --   'Polysemy.State.put' a
@@ -45,7 +45,12 @@ import Polysemy.Internal.Fixpoint
 --
 -- 'fixpointToFinal' also operates under the assumption that any effectful
 -- state which can't be inspected using 'Polysemy.Inspector' can't contain any
--- values. This is true for all interpreters featured in this package,
+-- values. For example, the effectful state for 'Polysemy.Error.runError' is
+-- @'Either' e a@. The inspector for this effectful state only fails if the
+-- effectful state is a @'Left'@ value, which therefore doesn't contain any
+-- values of @a@.
+--
+-- This assumption holds true for all interpreters featured in this package,
 -- and is presumably always true for any properly implemented interpreter.
 -- 'fixpointToFinal' may throw an exception if it is used together with an
 -- interpreter that uses 'Polysemy.Internal.Union.weave' improperly.