BSD-3-Clause licensed by Chris Penner
Maintained by [email protected]
This version can be pinned in stack with:selections-0.3.0.0@sha256:e9992612bf4416d09b8e12987bcb2a1b2d183217ced6e4746cf33a8dc18da89e,1156

Module documentation for 0.3.0.0

Depends on 1 package(full list with versions):

Selections

Hackage

See it on Hackage

See also this library’s Scala port by Christopher Davenport

You’ll probably want to start by reading the tutorial.

selections is a haskell package for transforming subsets of values within a functor using an intuitive selection-based interface.

Ever wished you could select just a few values within a functor, perform some operations on them, then flatten them back into the plain old functor again? Now you can!

Selection is a newtype wrapper around Functors which adds several combinators and interesting instances. Wrapping a functor in Selection allows you to:

  • Select specific values within your functor according to a predicate
  • Expand/Contract selections based on additional predicates using include and exclude
  • Select values based on their context if your functor is also a Comonad
  • Map over unselected and/or selected values using Bifunctor
  • Traverse over unselected and/or selected values using Bitraversable
  • Fold over unselected and/or selected values using Bifoldable
  • Perform monad computations over selected values if your functor is a Monad
  • Extract all unselected or selected elements to a list
  • Deselect and return to your original functor using unify
  • Traverse or fold over selections using Control.Lens

Here’s how it looks, tutorials are available here.

xs = [1..6]
λ> newSelection xs  -- wrap `[Int]` into `Selection [] Int Int`, you can wrap any functor
     & select even  -- Focus on only even integers
     & mapSelected (+100)  -- Increment selected ints by 100
     & bimap (("Odd: " ++) . show) (("Even: " ++) . show)  -- map over unselected and selected values respectively
     & forgetSelection -- Collapse back down to the underlying functor, in this case a list
["Odd: 1","Even: 102","Odd: 3","Even: 104","Odd: 5","Even: 106"]

Technically you could use Selection as a monad-transformer, but it’s a bit clunky and you’d probably be better off with EitherT.

Fun fact, Selection is isomorphic to EitherT, but the semantics are quite different and they’re suited to different purposes.

When Should/Shouldn’t I Use Selections?

You can use selections whenever you’ve got a bunch of things and you want to operate over just a few of them at a time. You can do everything that selections provides by combining a bunch of predicates with fmap, but it gets messy really quick; selections provides a clean interface for this sort of operation.

You shouldn’t use selections when you’re looking for a monadic interface for this sort of thing, selections works at the value level and typically you want to chain selection commands using (.) or (&), it technically can be used as a monad transformer if your underlying functor is also a monad, but at that point you may wish to check out EitherT instead.

Examples

Check out the Accounts tutorial first to get your bearings. After that continue to the Lenses tutorial.