Merge pull request #84 from marick/master

A start at documentation

Author: marick

src/Data/Lens/At.purs

@@ -3,6 +3,7 @@ module Data.Lens.At
   , at
   ) where
 
+
 import Prelude
 
 import Data.Identity (Identity(..))
@@ -15,6 +16,23 @@ import Data.Newtype (unwrap)
 import Data.Lens (Lens', lens)
 import Data.Lens.Index (class Index)
 
+-- | `At` is a type class whose instances let you add
+-- | new elements or delete old ones from "container-like" types:
+-- | 
+-- | ```purescript 
+-- | whole = Map.singleton "key" "value"
+-- | optic = at "key"
+-- |
+-- | view optic whole == Just "value"
+-- | 
+-- | set optic (Just "NEW") whole == Map.singleton "key" "NEW"
+-- | 
+-- | set optic Nothing whole == Map.empty
+-- | ```
+-- |
+-- | If you don't want to add or delete, but only to view or change
+-- | an existing element, see `Data.Lens.Index`. 
+
 class Index m a b <= At m a b | m -> a, m -> b where
   at :: a -> Lens' m (Maybe b)
 

src/Data/Lens/Index.purs

@@ -15,6 +15,35 @@ import Data.Set as S
 import Data.StrMap as SM
 import Data.Traversable (traverse)
 
+-- | `Index` is a type class whose instances are optics used when:
+-- | 1. The focus element might not be present.
+-- | 2. You either cannot or do not want to add new elements or delete existing ones. 
+-- |
+-- | `Array` is a typical example:
+-- |
+-- | ```purescript 
+-- | preview (ix 1) [0, 1, 2] == Just 1
+-- |
+-- | set (ix 1) 8888 [0, 1, 2] == [0,8888,2]
+-- | ```
+-- |
+-- | Note the use of `preview` rather `view`. That's because the optic is 
+-- | a `Data.Lens.Traversal` tailored to the case where there's a single element
+-- | of interest.
+-- | 
+-- | Another common use is a `Map` that you don't want to either grow or shrink:
+-- |
+-- | ```purescript 
+-- | (set (ix "k") "new" $ Map.singleton "k" "old") == Map.singleton "k" "new"
+-- | 
+-- | (set (ix "k") "new" $ Map.empty) == Map.empty
+-- | ```
+-- |
+-- | Note the second line: an attempt to `set` a missing focus element
+-- | leaves the original whole unchanged.
+-- |
+-- | If you *do* want to add or delete elements, see `Data.Lens.At`. 
+
 class Index m a b | m -> a, m -> b where
   ix :: a -> Traversal' m b
 

src/Data/Lens/Lens.purs

@@ -24,13 +24,24 @@ import Data.Profunctor.Strong (first)
 import Data.Tuple (Tuple(..))
 import Data.Newtype(un)
 
-lens' :: forall s t a b. (s -> Tuple a (b -> t)) -> Lens s t a b
-lens' to pab = dimap to (\(Tuple b f) -> f b) (first pab)
-
 -- | Create a `Lens` from a getter/setter pair.
+-- |
+-- | ```purescript
+-- | > species = lens _.species $ _ {species = _}
+-- | > view species {species : "bovine"}
+-- | "bovine"
+-- |
+-- | > _2 = lens Tuple.snd $ \(Tuple keep _) new -> Tuple keep new
+-- | ```
+-- |
+-- | Note: `_2` is predefined in `Data.Lens.Tuple`.
+
 lens :: forall s t a b. (s -> a) -> (s -> b -> t) -> Lens s t a b
 lens get set = lens' \s -> Tuple (get s) \b -> set s b
 
+lens' :: forall s t a b. (s -> Tuple a (b -> t)) -> Lens s t a b
+lens' to pab = dimap to (\(Tuple b f) -> f b) (first pab)
+
 withLens :: forall s t a b r. ALens s t a b -> ((s -> a) -> (s -> b -> t) -> r) -> r
 withLens l f = case l (Shop id \_ b -> b) of Shop x y -> f x y
 

src/Data/Lens/Types.purs

@@ -27,21 +27,77 @@ import Data.Profunctor.Choice (class Choice)
 import Data.Profunctor.Closed (class Closed)
 import Data.Profunctor.Strong (class Strong)
 
--- | A general-purpose Data.Lens.
-type Optic p s t a b = p a b -> p s t
-type Optic' p s a = Optic p s s a a
+-- | Given a type whose "focus element" always exists,
+-- | a lens provides a convenient way to view, set, and transform
+-- | that element. 
+-- | 
+-- | For example, `_2` is a tuple-specific `Lens` available from `Data.Lens`, so:
+-- | ```purescript
+-- | over _2 String.length $ Tuple "ignore" "four" == Tuple "ignore" 4
+-- | ```
+-- | Note the result has a different type than the original tuple.
+-- | That is, the four `Lens` type variables have been narrowed to:
+-- |
+-- | * `s` is `Tuple String String`
+-- | * `t` is `Tuple String Int`
+-- | * `a` is `String`
+-- | * `b` is `Int`
+-- | 
+-- | See `Data.Lens.Getter` and `Data.Lens.Setter` for functions and operators
+-- | frequently used with lenses.
+
+
+type Lens s t a b = forall p. Strong p => Optic p s t a b
+
+-- | `Lens'` is a specialization of `Lens`. An optic of type `Lens'`
+-- | can change only the value of its focus,
+-- | not its type. As an example, consider the `Lens` `_2`, which has this type:
+-- |
+-- | ```purescript
+-- | _2 :: forall s t a b. Lens (Tuple s a) (Tuple t b) a b 
+-- | ```
+-- |
+-- | `_2` can produce a `Tuple Int String` from a `Tuple Int Int`:
+-- |
+-- | ```purescript
+-- | set _2 "NEW" (Tuple 1 2) == (Tuple 1 "NEW")
+-- | ```
+-- |
+-- | If we specialize `_2`'s type with `Lens'`, the following will not
+-- | type check:
+-- |
+-- | ```purescript
+-- | set (_2 :: Lens' (Tuple Int Int) Int) "NEW" (Tuple 1 2)
+-- |            ^^^^^^^^^^^^^^^^^^^^^^^^^
+-- | ```
+-- |
+-- | See `Data.Lens.Getter` and `Data.Lens.Setter` for functions and operators
+-- | frequently used with lenses.
+
+type Lens' s a = Lens s s a a
+
+-- | A prism.
+type Prism s t a b = forall p. Choice p => Optic p s t a b
+type Prism' s a = Prism s s a a
 
 -- | A generalized isomorphism.
 type Iso s t a b = forall p. Profunctor p => Optic p s t a b
 type Iso' s a = Iso s s a a
 
+-- | A traversal.
+type Traversal s t a b = forall p. Wander p => Optic p s t a b
+type Traversal' s a = Traversal s s a a
+
+
+
+
+-- | A general-purpose Data.Lens.
+type Optic p s t a b = p a b -> p s t
+type Optic' p s a = Optic p s s a a
+
 type AnIso s t a b = Optic (Exchange a b) s t a b
 type AnIso' s a = AnIso s s a a
 
--- | A lens.
-type Lens s t a b = forall p. Strong p => Optic p s t a b
-type Lens' s a = Lens s s a a
-
 type ALens s t a b = Optic (Shop a b) s t a b
 type ALens' s a = ALens s s a a
 
@@ -52,17 +108,9 @@ type IndexedLens' i s a = IndexedLens i s s a a
 type AnIndexedLens i s t a b = IndexedOptic (Shop (Tuple i a) b) i s t a b
 type AnIndexedLens' i s a = AnIndexedLens i s s a a
 
--- | A prism.
-type Prism s t a b = forall p. Choice p => Optic p s t a b
-type Prism' s a = Prism s s a a
-
 type APrism s t a b = Optic (Market a b) s t a b
 type APrism' s a = APrism s s a a
 
--- | A traversal.
-type Traversal s t a b = forall p. Wander p => Optic p s t a b
-type Traversal' s a = Traversal s s a a
-
 -- | A grate (http://r6research.livejournal.com/28050.html)
 type Grate s t a b = forall p. Closed p => Optic p s t a b
 type Grate' s a = Grate s s a a