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


-- | Combinators for operating with selections over an underlying functor
--   
--   See the <a>README on github</a> for tutorials!
@package selections
@version 0.3.0.0

module Data.Functor.Selection

-- | A selection wraps a Functor <tt>f</tt> and has an unselected type
--   <tt>b</tt> and a selected type <tt>a</tt>
newtype Selection f b a
Selection :: f (Either b a) -> Selection f b a

-- | Expose the underlying representation of a <a>Selection</a>
[unwrapSelection] :: Selection f b a -> f (Either b a)

-- | A type alias for selections with the same unselected/selected types
type Selection' f a = Selection f a a

-- | Modify the underlying representation of a selection
--   
--   A powerful and low-level way to transform your selection
withUnwrapped :: Functor f => (f (Either b a) -> g (Either d c)) -> Selection f b a -> Selection g d c

-- | Create a selection from a functor by selecting all values
newSelection :: Functor f => f a -> Selection f b a

-- | Drops selection from your functor returning all values (selected or
--   not).
--   
--   <pre>
--   <tt>forgetSelection</tt> . <a>newSelection</a> = id
--   </pre>
--   
--   <pre>
--   <tt>forgetSelection</tt> = <a>unify</a> id id
--   </pre>
runSelection :: Functor f => Selection f a a -> f a

-- | Clear the selection then select only items which match a predicate.
--   
--   <pre>
--   <a>select</a> f = <a>include</a> f . <a>deselectAll</a>
--   </pre>
select :: Functor f => (a -> Bool) -> Selection f a a -> Selection f a a

-- | Add items which match a predicate to the current selection
--   
--   <pre>
--   <a>include</a> f . <a>select</a> g = <a>select</a> (a -&gt; f a || g a)
--   </pre>
include :: Functor f => (a -> Bool) -> Selection f a a -> Selection f a a

-- | Remove items which match a predicate to the current selection
--   
--   <pre>
--   <a>exclude</a> f . <a>select</a> g = <a>select</a> (a -&gt; f a &amp;&amp; not (g a))
--   </pre>
exclude :: Functor f => (a -> Bool) -> Selection f a a -> Selection f a a

-- | Select all items in the container
--   
--   <pre>
--   <a>selectAll</a> = <a>include</a> (const True)
--   </pre>
selectAll :: Functor f => Selection f a a -> Selection f b a

-- | Deselect all items in the container
--   
--   <pre>
--   <a>deselectAll</a> = <a>exclude</a> (const True)
--   </pre>
deselectAll :: Functor f => Selection f b b -> Selection f b a

-- | Flip the selection, all selected are now unselected and vice versa.
invertSelection :: Functor f => Selection f b a -> Selection f a b

-- | Map over selected values
--   
--   <pre>
--   <a>mapSelected</a> = fmap
--   </pre>
mapSelected :: Functor f => (a -> c) -> Selection f b a -> Selection f b c

-- | Map over unselected values
--   
--   <pre>
--   <a>mapUnselected</a> = <a>first</a>
--   </pre>
mapUnselected :: Functor f => (b -> c) -> Selection f b a -> Selection f c a

-- | Collect all selected values into a list.
--   
--   <pre>
--   <a>getSelected</a> = toList
--   </pre>
getSelected :: Foldable f => Selection f b a -> [a]

-- | Collect all unselected values into a list. For more complex operations
--   use operations from Bifoldable.
--   
--   <pre>
--   <a>getUnselected</a> = <a>getSelected</a> . <a>invertSelection</a>
--   </pre>
getUnselected :: (Foldable f, Functor f) => Selection f b a -> [b]

-- | Unify selected and unselected and forget the selection
--   
--   <pre>
--   <a>unify</a> f g == <tt>forgetSelection</tt> . <tt>onUnselected</tt> f . <tt>onSelected</tt> g
--   </pre>
unify :: Functor f => (b -> c) -> (a -> c) -> Selection f b a -> f c

-- | Perform a natural transformation over the underlying container of a
--   selectable
hoist :: Functor f => (forall c. f c -> g c) -> Selection f b a -> Selection g b a
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Data.Functor.Selection.Selection f b)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Data.Functor.Selection.Selection f b)
instance GHC.Base.Functor f => GHC.Base.Functor (Data.Functor.Selection.Selection f b)
instance GHC.Show.Show (f (Data.Either.Either b a)) => GHC.Show.Show (Data.Functor.Selection.Selection f b a)
instance GHC.Classes.Eq (f (Data.Either.Either b a)) => GHC.Classes.Eq (Data.Functor.Selection.Selection f b a)
instance GHC.Base.Monad m => GHC.Base.Applicative (Data.Functor.Selection.Selection m b)
instance GHC.Base.Monad m => GHC.Base.Monad (Data.Functor.Selection.Selection m b)
instance GHC.Base.Functor f => Data.Bifunctor.Bifunctor (Data.Functor.Selection.Selection f)
instance Data.Foldable.Foldable f => Data.Bifoldable.Bifoldable (Data.Functor.Selection.Selection f)
instance Data.Traversable.Traversable f => Data.Bitraversable.Bitraversable (Data.Functor.Selection.Selection f)

module Control.Lens.Selection

-- | Traversal over selected elements
--   
--   <pre>
--   <a>selected</a> = <a>traverse</a>
--   </pre>
selected :: Traversable f => Traversal (Selection f b a) (Selection f b a') a a'

-- | Traversal over unselected elements
--   
--   <pre>
--   <a>unselected</a> = <tt>inverting</tt> . <a>selected</a>
--   </pre>
unselected :: Traversable f => Traversal (Selection f b a) (Selection f b' a) b b'

-- | Traversal which inverts the current selection
--   
--   This is provided as a Traversal to avoid adding a <tt>profunctors</tt>
--   dependency. You can write the corresponding iso if you wish:
--   
--   <pre>
--   <tt>inverting</tt> = iso <a>invertSelection</a> <a>invertSelection</a>
--   </pre>
inverted :: Functor f => Traversal (Selection f b a) (Selection f b' a') (Selection f a b) (Selection f a' b')

-- | Traversal which exposes the underlying functor representation
--   
--   This is provided as a Traversal to avoid adding a <tt>profunctors</tt>
--   dependency. You can write the corresponding iso if you wish:
--   
--   <pre>
--   <tt>unwrapping</tt> = iso <a>unwrapSelection</a> <tt>wrapSelection</tt>
--   </pre>
unwrapped :: Traversal (Selection f b a) (Selection f b' a') (f (Either b a)) (f (Either b' a'))