-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Helps when going "seed values" -> alternatives and optional -> answers
--
--
--
--
-- Types to support turning structured collections of seed values into
-- the same structures with alternatives along with some functions for
-- regular uses. Please see README.md for more information
@package subzero
@version 0.1.0.4
-- | Here is a longer description of this module, containing some
-- commentary with some markup.
module Control.Applicative.SubZero
-- | Turns a container of values to a container of either retained or
-- destroyed values based on a predicate
--
-- The type constraint allows us to model possible outcomes so destroyed
-- values are just "no possible outcomes" while retained values represent
-- "the only possible outcome".
--
-- To represent that "no value" is a possible outcome, a should
-- be some type like (Maybe a) or (Either
-- String a).
--
--
-- - f This Functor defines the broad scale
-- behaviours but its Alternative instance is overridden. This in
-- particular might change during upcoming design validation.
-- - g This Functor supplies the supercedent
-- Alternative instance and thus the finer behaviours.
--
points :: (Functor f, Alternative g) => (a -> Bool) -> f a -> Compose f g a
-- | Converts a functor so that each point at the source has alternatives.
--
-- It's just like Compose but the applicative instance appends new
-- alternative values in the rightmost (inner/minor) functor instead of
-- in the leftmost (outer/major) functor.
--
-- The result is that two ZipLists of alternatives zip
-- together, providing alternatives to each point.
--
-- Given the immediate utility of this, I do wonder if the
-- Alternative instance of Compose is the
-- wrong one.
--
--
-- - f The major functor, overall mapping/view
-- - g This has a a few key useful interpretations
-- depending on its instances, examples below.
-- - a Transformed/contained value type.
--
--
-- Some example instances that you might want to rely on from g:
--
--
-- - Alternative Superposition
-- functor.
- How do individual items have a set of possible
-- values?
- How do those possible values collapse to form one
-- optional value?
- etc.
-- - etc There are a lot of other utilities for this type.
--
--
-- Provides structure for values at the other end of a
-- Functor
reveal :: (Functor f, Applicative g) => f a -> Compose f g a
-- | If the type constructor of the possibilities concept is
-- Maybe then you can use flatten to
-- provide default values for impossible points.
--
--
-- - NOTE: This uses the applicative instance of the broad scale
-- Functor which means exact behaviour can vary depending
-- on the type of Applicative f because each has a
-- different technique to ensure a value is found for every
-- point:
- list of a Cross-product; Providing all
-- default values once for all points.
- ZipList
-- a zipWith; Providing one default value for each point until
-- there are either no defaults remaining or no more
-- points.
- Identity a One default must
-- surely be provided and it is used if a default is
-- required.
- Maybe a Not sure exactly what
-- this does, TBC.
- Either a Not sure
-- exactly what this does, TBC.
--
flatten :: (Applicative f) => f a -> Compose f Maybe a -> f a
-- | fmap below the zeropoint
(<-$>) :: (Functor f) => (g a -> h a) -> Compose f g a -> Compose f h a
-- | fmap below the zeropoint, function variant of <-$>
-- operator
universal :: Functor f => (g a -> h a) -> Compose * * f g a -> Compose * * f h a
-- | Alternative below the zeropoint
(<-|>) :: (Applicative f, Alternative g) => Compose * * f g a -> Compose * * f g a -> Compose * * f g a
-- |
-- collapse f empty = simplify empty
--
--
--
-- collapse f (pure x) = simplify (pure x)
--
--
--
-- collapse f (x <|> y) = pure (f x y)
--
--
-- g must form a monoid under f when
-- empty is the monoid's identity.
class (Applicative g, Applicative h) => Superposition g h
-- | Tries to convert from one alternative to another
simplify :: Superposition g h => g a -> Maybe (h a)
-- | Combines many alternatives into one using a function parameter.
-- empty stays empty. This is quite free
-- in the type of the result so the user can choose whether to keep the
-- same type to re-expand the structure or to transform to a smaller type
-- to avoid relying on instances for certain behaviours.
collapse :: Superposition g h => (a -> a -> a) -> g a -> h a
-- | Tries to convert from one alternative to another
simplify :: Superposition g h => g a -> Maybe (h a)
-- | Combines many alternatives into one using a function parameter.
-- empty stays empty. This is quite free
-- in the type of the result so the user can choose whether to keep the
-- same type to re-expand the structure or to transform to a smaller type
-- to avoid relying on instances for certain behaviours.
collapse :: Superposition g h => (a -> a -> a) -> g a -> h a
-- | Turns a value "a" to Just a or
-- Nothing based on a predicate assuming you use it in a
-- context that wants Maybe a instead of some other
-- representation of Alternatives
keep :: (Alternative f) => (a -> Bool) -> a -> f a
-- | Does the same as keep for values at the other end of
-- Identity.
--
--
-- keep = (keepIdentity . Identity) f
--
keepIdentity :: (Alternative f) => (a -> Bool) -> Identity a -> f a
instance GHC.Base.Alternative h => Control.Applicative.SubZero.Superposition [] h
instance (GHC.Base.Applicative f, Control.Applicative.SubZero.Superposition g h) => Control.Applicative.SubZero.Superposition (Data.Functor.Compose.Compose f g) (Data.Functor.Compose.Compose f h)