-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Helps when going "seed values" -> alternatives and optional -> answers
--   
--   <pre>
--   </pre>
--   
--   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.2


-- | Here is a longer description of this module, containing some
--   commentary with <tt>some markup</tt>.
module Control.Applicative.SubZero

-- | 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 <tt><a>ZipList</a></tt>s of alternatives zip
--   together, providing alternatives to each point.
--   
--   Given the immediate utility of this, I do wonder if the
--   <tt><a>Alternative</a></tt> instance of <tt><a>Compose</a></tt> is the
--   wrong one.
--   
--   <ul>
--   <li><i><tt>f</tt></i> The major functor, overall mapping/view</li>
--   <li><i><tt>g</tt></i> This has a a few key useful interpretations
--   depending on its instances, examples below.</li>
--   <li><i><tt>a</tt></i> Transformed/contained value type.</li>
--   </ul>
--   
--   Some example instances that you might want to rely on from <tt>g</tt>:
--   
--   <ul>
--   <li><i><tt><a>Alternative</a></tt></i> Superposition
--   functor.<ul><li>How do individual items have a set of possible
--   values?</li><li>How do those possible values collapse to form one
--   optional value?</li><li>etc.</li></ul></li>
--   <li><i>etc</i> There are a lot of other utilities for this type.</li>
--   </ul>
data SubZero f g a

-- | 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, <tt>a</tt> should
--   be some type like (<tt><a>Maybe</a> a</tt>) or (<tt><a>Either</a>
--   <a>String</a> a</tt>).
--   
--   <ul>
--   <li><i><tt>f</tt></i> This <a>Functor</a> defines the broad scale
--   behaviours but its <a>Alternative</a> instance is overridden. This in
--   particular might change during upcoming design validation.</li>
--   <li><i><tt>g</tt></i> This <a>Functor</a> supplies the supercedent
--   <a>Alternative</a> instance and thus the finer behaviours.</li>
--   </ul>
points :: (Functor f, Alternative g) => (a -> Bool) -> f a -> SubZero f g a

-- | Provides structure for values at the other end of a
--   <tt><a>Functor</a></tt>
reveal :: (Functor f, Applicative g) => f a -> SubZero f g a

-- | If the type constructor of the possibilities concept is
--   <tt><a>Maybe</a></tt> then you can use <tt><a>flatten</a></tt> to
--   provide default values for impossible points.
--   
--   <ul>
--   <li><i>NOTE</i>: This uses the applicative instance of the broad scale
--   <tt><a>Functor</a></tt> which means exact behaviour can vary depending
--   on the type of <tt><a>Applicative</a> f</tt> because each has a
--   different technique to ensure a value is found for every
--   point:<ul><li><i><tt>list of a</tt></i> Cross-product; Providing all
--   default values once for all points.</li><li><i><tt><a>ZipList</a>
--   a</tt></i> zipWith; Providing one default value for each point until
--   there are either no defaults remaining or no more
--   points.</li><li><i><tt><a>Identity</a> a</tt></i> One default must
--   surely be provided and it is used if a default is
--   required.</li><li><i><tt><a>Maybe</a> a</tt></i> Not sure exactly what
--   this does, TBC.</li><li><i><tt><a>Either</a> a</tt></i> Not sure
--   exactly what this does, TBC.</li></ul></li>
--   </ul>
flatten :: (Applicative f) => f a -> SubZero f Maybe a -> f a

-- | Take the alternatives embedded in the <tt><a>SubZero</a></tt> and
--   collapse them with a combining function to a single
--   <tt><a>Alternative</a></tt> value or empty which means no possible
--   outcomes. This is quite free in the type of the possibilities concept
--   of the result. It's compatible with <tt><a>Maybe</a></tt> for further
--   uses with <tt><a>flatten</a></tt>, but you can retain behaviours of
--   more sophisticated types. A consequence of this is that you will
--   probably need to state a type.
collapse :: (Functor f, Foldable g, Alternative h) => (a -> a -> a) -> SubZero f g a -> SubZero f h a
instance (GHC.Base.Applicative g, GHC.Base.Applicative f) => GHC.Base.Applicative (Control.Applicative.SubZero.SubZero f g)
instance (GHC.Base.Functor g, GHC.Base.Functor f) => GHC.Base.Functor (Control.Applicative.SubZero.SubZero f g)
instance (GHC.Classes.Ord a, Data.Functor.Classes.Ord1 g, Data.Functor.Classes.Ord1 f) => GHC.Classes.Ord (Control.Applicative.SubZero.SubZero f g a)
instance (GHC.Classes.Eq a, Data.Functor.Classes.Eq1 g, Data.Functor.Classes.Eq1 f) => GHC.Classes.Eq (Control.Applicative.SubZero.SubZero f g a)
instance (GHC.Read.Read a, Data.Functor.Classes.Read1 g, Data.Functor.Classes.Read1 f) => GHC.Read.Read (Control.Applicative.SubZero.SubZero f g a)
instance (GHC.Show.Show a, Data.Functor.Classes.Show1 g, Data.Functor.Classes.Show1 f) => GHC.Show.Show (Control.Applicative.SubZero.SubZero f g a)
instance (GHC.Base.Applicative f, GHC.Base.Alternative g) => GHC.Base.Alternative (Control.Applicative.SubZero.SubZero f g)