Merge branch 'new'

Author: marick

src/Data/Lens/Prism.purs

@@ -1,7 +1,45 @@
--- | This module defines functions for working with prisms.
+-- | Prisms are used for selecting cases of a type, most often a sum
+-- | type. Consider this:
+-- |
+-- | ```purescript
+-- | data Fill -- think of a paint program filling a shape
+-- |   = Solid Color
+-- |   ...
+-- | ```
+-- |
+-- | A prism that focuses on `Solid` fills would be written like this:
+-- |
+-- | ```purescript
+-- | solidFocus :: Prism' Fill Color
+-- | solidFocus = prism' Solid case _ of
+-- |   Solid color -> Just color
+-- |   _ -> Nothing
+-- | ```
+-- |
+-- | ... and used like this:
+-- |
+-- | ```purescript
+-- | preview solidFocus (Solid Color.white) == Just Color.white
+-- | preview solidFocus NoFill == Nothing
+-- |
+-- | is solidFocus (Solid Color.white) == true
+-- | ```
+-- |
+-- | `review` can be used to go from a `Color` to a `Fill`:
+-- |
+-- | ```purescript
+-- | review solidFocus Color.white == Solid Color.white
+-- | ```
+-- | 
+-- | For more information, see `PrismsForSumTypes` in the
+-- | `examples/src` directory.
+
 module Data.Lens.Prism
-  ( prism, prism', review, nearly, only, clonePrism, withPrism, matching
+  ( prism, prism'
+  , only, nearly
+  , review
   , is, isn't
+  , clonePrism, withPrism, matching
   , module ExportTypes
   ) where
 
@@ -18,23 +56,79 @@ import Data.Profunctor (dimap, rmap)
 import Data.Profunctor.Choice (right)
 import Data.Newtype (under)
 
--- | Create a `Prism` from a constructor/pattern pair.
+-- | Create a `Prism` from a constructor and a "focus" function that
+-- | produces an `Either`:
+-- | 
+-- | ```purescript
+-- | solidFocus' :: Prism' Fill Color
+-- | solidFocus' = prism Solid case _ of
+-- |   Solid color -> Right color
+-- |   anotherCase -> Left anotherCase
+-- | ```
 prism :: forall s t a b. (b -> t) -> (s -> Either t a) -> Prism s t a b
 prism to fro pab = dimap fro (either id id) (right (rmap to pab))
 
+-- | Create a `Prism` from a constructor and a "focus" function that
+-- | produces an `Maybe`:
+-- | 
+-- | ```purescript
+-- | solidFocus' :: Prism' Fill Color
+-- | solidFocus' = prism' Solid case _ of
+-- |   Solid color -> Just color
+-- |   _ -> Nothing
+-- | ```
 prism' :: forall s a. (a -> s) -> (s -> Maybe a) -> Prism' s a
 prism' to fro = prism to (\s -> maybe (Left s) Right (fro s))
 
--- | Review a value through a `Prism`.
-review :: forall s t a b. Review s t a b -> b -> t
-review = under Tagged
+-- | Create a prism that focuses on only some of the values of a case,
+-- | such as solid colors that are "bright enough":
+-- | 
+-- | ```purescript
+-- | brightSolidFocus :: Prism' Fill Unit
+-- | brightSolidFocus = nearly (Solid referenceColor) predicate
+-- |   where
+-- |     referenceColor = Color.graytone 0.8
+-- |     predicate = case _ of
+-- |       Solid color ->
+-- |         Color.brightness color >= Color.brightness referenceColor
+-- |       _ ->
+-- |         false
+-- |
+-- | preview brightSolidFocus (Solid Color.white) == Just unit
+-- | preview brightSolidFocus (Solid Color.black) == Nothing
+-- | preview brightSolidFocus NoFill              == Nothing
+-- |
+-- | is      brightSolidFocus (Solid Color.white) == true
+-- | review  brightSolidFocus unit                == Color.graytone 0.8
+-- | ```
+
 
 nearly :: forall a. a -> (a -> Boolean) -> Prism' a Unit
 nearly x f = prism' (const x) (guard <<< f)
 
+-- | `only` focuses not just on a case, but a specific value of that case.
+-- | 
+-- | ```purescript
+-- | solidWhiteFocus :: Prism' Fill Unit
+-- | solidWhiteFocus = only $ Solid Color.white
+-- |
+-- | is      solidWhiteFocus (Solid Color.white) == true
+-- | preview solidWhiteFocus (Solid Color.white) == Just unit
+-- | review  solidWhiteFocus unit                == Solid Color.white
+-- | ```
 only :: forall a. Eq a => a -> Prism a a Unit Unit
 only x = nearly x (_ == x)
 
+
+-- | Create the "whole" corresponding to a specific "part":
+-- |
+-- | ```purescript
+-- | -- solidFocus is a `Prism Fill Color`
+-- | review solidFocus Color.white == Solid Color.white
+-- | ```
+review :: forall s t a b. Review s t a b -> b -> t
+review = under Tagged
+
 clonePrism :: forall s t a b. APrism s t a b -> Prism s t a b
 clonePrism l = withPrism l \x y p -> prism x y p
 
@@ -45,8 +139,10 @@ withPrism l f = case l (Market id Right) of
 matching :: forall s t a b. APrism s t a b -> s -> Either t a
 matching l = withPrism l \_ f -> f
 
+--| Would `preview prism` produce a `Just`?
 is :: forall s t a b r. HeytingAlgebra r => APrism s t a b -> s -> r
 is l = either (const ff) (const tt) <<< matching l
 
+--| Would `preview prism` produce a `Nothing`?
 isn't :: forall s t a b r. HeytingAlgebra r => APrism s t a b -> s -> r
 isn't l = not <<< is l

src/Data/Lens/Traversal.purs

@@ -1,12 +1,30 @@
--- | This module defines functions for working with traversals.
+-- | `Traversal` is an optic that focuses on zero or more functor values. An
+-- | `Array` would be a typical example:
+-- |
+-- | ```purescript
+-- | over    traversed negate [1, 2, 3] == [-1, -2, -3]
+-- | preview traversed [1, 2, 3] == Just 1
+-- | firstOf traversed [1, 2, 3] == Just 1  -- same as `preview`
+-- | lastOf  traversed [1, 2, 3] == Just 3
+-- | ```
+-- |
+-- | `view` might surprise you. It assumes that the wrapped values
+-- | are a monoid, and `append`s them together:
+-- |
+-- | ```purescript
+-- | view traversed ["D", "a", "w", "n"] == "Dawn"
+-- | ```
+-- |
+-- | Many of the functions you'll use are documented in `Data.Lens.Fold`. 
+
 module Data.Lens.Traversal
   ( traversed
+  , element
   , traverseOf
   , sequenceOf
   , failover
   , elementsOf
   , itraverseOf
-  , element
   , module ExportTypes
   ) where
 
@@ -24,7 +42,12 @@ import Data.Traversable (class Traversable, traverse)
 import Data.Tuple (Tuple(..), uncurry)
 import Data.Newtype (under, unwrap)
 
--- | Create a `Traversal` which traverses the elements of a `Traversable` functor.
+-- | A `Traversal` for the elements of a `Traversable` functor.
+-- |
+-- | ```purescript
+-- | over traversed negate [1, 2, 3] == [-1,-2,-3]
+-- | over traversed negate (Just 3) == Just -3
+-- | ```
 traversed :: forall t a b. Traversable t => Traversal (t a) (t b) a b
 traversed = wander traverse
 
@@ -37,6 +60,29 @@ traverseOf = under Star
 
 -- | Sequence the foci of a `Traversal`, pulling out an `Applicative` effect.
 -- | If you do not need the result, see `sequenceOf_` for `Fold`s.
+-- |
+-- | `sequenceOf traversed` has the same result as `Data.Traversable.sequence`:
+-- |
+-- | ```purescript
+-- | sequenceOf traversed (Just [1, 2]) == [Just 1, Just 2]
+-- | sequence             (Just [1, 2]) == [Just 1, Just 2]
+-- | ```
+-- |
+-- | An example with effects:
+-- | ```purescript
+-- | > array = [random, random]
+-- | > :t array
+-- | Array (Eff ... Number)
+-- |
+-- | > effect = sequenceOf traversed array
+-- | > :t effect
+-- | Eff ... (Array Number)
+-- |
+-- | > effect >>= logShow
+-- | [0.15556037108154985,0.28500369615270515]
+-- | unit
+-- | ```
+
 sequenceOf
   :: forall f s t a
    . Applicative f
@@ -56,7 +102,14 @@ failover t f s = case unwrap (t $ Star $ Tuple (Disj true) <<< f) s of
   Tuple (Disj true) x  -> pure x
   Tuple (Disj false) _ -> empty
 
--- | Affine traversal the `n`-th focus of a `Traversal`.
+-- | Combine an index and a traversal to narrow the focus to a single
+-- | element. This is called an "affine traversal". Compare to `Data.Lens.Index`. 
+-- |
+-- | ```purescript
+-- | set     (element 2 traversed) 8888 [0, 0, 3] == [0, 0, 8888]
+-- | preview (element 2 traversed)      [0, 0, 3] == Just 3
+-- | ```
+
 element
   :: forall p s t a
    . Wander p