Add Foldable1 And Traversable1 type classes (#68)

* Add Foldable1 and Traversable1 classes

* Add docs

* Only export what needs to exported

* Remove redundant parens

Author: LukaJCB

src/Data/Semigroup/Foldable.purs

@@ -0,0 +1,73 @@
+module Data.Semigroup.Foldable
+  ( class Foldable1
+  , foldMap1
+  , fold1
+  , traverse1_
+  , for1_
+  , sequence1_
+  , foldMap1Default
+  , fold1Default
+  ) where
+
+import Prelude
+import Data.Foldable (class Foldable)
+import Data.Monoid.Dual (Dual(..))
+import Data.Monoid.Multiplicative (Multiplicative(..))
+
+-- | `Foldable1` represents data structures with a minimum of one element that can be _folded_.
+-- |
+-- | - `fold1` folds a structure using a `Semigroup` instance
+-- | - `foldMap1` folds a structure by accumulating values in a `Semigroup`
+-- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `fold1Default`
+-- | - `foldMap1Default`
+-- |
+-- | Note: some combinations of the default implementations are unsafe to
+-- | use together - causing a non-terminating mutually recursive cycle.
+-- | These combinations are documented per function.
+class Foldable t <= Foldable1 t where
+  foldMap1 :: forall a m. Semigroup m => (a -> m) -> t a -> m
+  fold1 :: forall m. Semigroup m => t m -> m
+
+-- | A default implementation of `fold1` using `foldMap1`.
+fold1Default :: forall t m. Foldable1 t => Semigroup m => t m -> m
+fold1Default = foldMap1 id
+
+-- | A default implementation of `foldMap1` using `fold1`.
+foldMap1Default :: forall t m a. Foldable1 t => Functor t => Semigroup m => (a -> m) -> t a -> m
+foldMap1Default f = (map f) >>> fold1
+
+instance foldableDual :: Foldable1 Dual where
+  foldMap1 f (Dual x) = f x
+  fold1 = fold1Default
+
+instance foldableMultiplicative :: Foldable1 Multiplicative where
+  foldMap1 f (Multiplicative x) = f x
+  fold1 = fold1Default
+
+newtype Act f a = Act (f a)
+
+getAct :: forall f a. Act f a -> f a
+getAct (Act f) = f
+
+instance semigroupAct :: Apply f => Semigroup (Act f a) where
+  append (Act a) (Act b) = Act (a *> b)
+
+-- | Traverse a data structure, performing some effects encoded by an
+-- | `Apply` instance at each value, ignoring the final result.
+traverse1_ :: forall t f a b. Foldable1 t => Apply f => (a -> f b) -> t a -> f Unit
+traverse1_ f t = unit <$ getAct (foldMap1 (Act <<< f) t)
+
+-- | A version of `traverse1_` with its arguments flipped.
+-- |
+-- | This can be useful when running an action written using do notation
+-- | for every element in a data structure:
+for1_ :: forall t f a b. Foldable1 t => Apply f => t a -> (a -> f b) -> f Unit
+for1_ = flip traverse1_
+
+-- | Perform all of the effects in some data structure in the order
+-- | given by the `Foldable1` instance, ignoring the final result.
+sequence1_ :: forall t f a. Foldable1 t => Apply f => t (f a) -> f Unit
+sequence1_ = traverse1_ id

src/Data/Semigroup/Traversable.purs

@@ -0,0 +1,51 @@
+module Data.Semigroup.Traversable where
+
+import Prelude
+import Data.Traversable (class Traversable)
+import Data.Semigroup.Foldable (class Foldable1)
+
+-- | `Traversable1` represents data structures with a minimum of one element that can be _traversed_,
+-- | accumulating results and effects in some `Applicative` functor.
+-- |
+-- | - `traverse1` runs an action for every element in a data structure,
+-- |   and accumulates the results.
+-- | - `sequence1` runs the actions _contained_ in a data structure,
+-- |   and accumulates the results.
+-- |
+-- | The `traverse1` and `sequence1` functions should be compatible in the
+-- | following sense:
+-- |
+-- | - `traverse1 f xs = sequence1 (f <$> xs)`
+-- | - `sequence1 = traverse1 id`
+-- |
+-- | `Traversable1` instances should also be compatible with the corresponding
+-- | `Foldable1` instances, in the following sense:
+-- |
+-- | - `foldMap1 f = runConst <<< traverse1 (Const <<< f)`
+-- |
+-- | Default implementations are provided by the following functions:
+-- |
+-- | - `traverse1Default`
+-- | - `sequence1Default`
+class (Foldable1 t, Traversable t) <= Traversable1 t where
+  traverse1 :: forall a b f. Apply f => (a -> f b) -> t a -> f (t b)
+  sequence1 :: forall b f. Apply f => t (f b) -> f (t b)
+
+-- | A default implementation of `traverse1` using `sequence1`.
+traverse1Default
+  :: forall t a b m
+   . Traversable1 t
+  => Apply m
+  => (a -> m b)
+  -> t a
+  -> m (t b)
+traverse1Default f ta = sequence1 (f <$> ta)
+
+-- | A default implementation of `sequence1` using `traverse1`.
+sequence1Default
+  :: forall t a m
+   . Traversable1 t
+  => Apply m
+  => t (m a)
+  -> m (t a)
+sequence1Default = traverse1 id