-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | mapWith: like fmap, but with additional arguments (isFirst, isLast, etc). -- -- fmap over Traversables (including lists), but pass additional -- parameters to the map function, such as isFirst, isLast, prevElt, -- nextElt, index from start or end, custom params. For examples see -- https://github.com/davjam/MapWith/blob/master/doc/examples.hs @package MapWith @version 0.1.0.0 -- | Provides fmap-like functionality, but can also "inject" -- additional parameters to the mapping function, such as: -- --

whether the first / last item
the previous / next item
the index from the start / end

module MapWith -- | Maps over a Traversable, with additional parameters indicating -- whether an item is the first or last (or both) in the list. -- --

--   >>> let f x isFirst isLast = star isFirst ++ x ++ star isLast; star b = if b then "*" else "" in withFirstLast f ["foo", "bar", "baz"]
--   ["*foo", "bar", "baz*"]
--

withFirstLast :: Traversable t => (a -> Bool -> Bool -> b) -> t a -> t b -- |

--   andFirstLast = withFirstLast (,,)
--

andFirstLast :: Traversable t => t a -> t (a, Bool, Bool) -- | Maps over a Traversable, with additional parameters indicating -- the previous and next elements. -- -- The second (or third) parameter to the map function is Nothing -- when called for the first (or last) item, otherwise it's Just -- the previous (or next) item. -- --

--   >>> let f x prvMay nxtMay = maybe "*" (cmp x) prvMay ++ x ++ maybe "*" (cmp x) nxtMay; cmp x y = show $ compare x y in withPrevNext f ["foo", "bar", "baz"]
--   ["*fooGT","LTbarLT","GTbaz*"]
--

withPrevNext :: Traversable t => (a -> Maybe a -> Maybe a -> b) -> t a -> t b -- |

--   andPrevNext = withPrevNext (,,)
--

andPrevNext :: Traversable t => t a -> t (a, Maybe a, Maybe a) -- | maps an InjectedFn over a Traversable type t, -- turning a t a into a t b and preserving the -- structure of t. -- -- Parameters (as defined in the InjectedFn) are passed to a map -- function (embedded in the InjectedFn), in addition to the -- elements of the Traversable. mapWith :: Traversable t => InjectedFn a b -> t a -> t b -- | like mapM, but with an InjectedFn. mapWithM :: (Traversable t, Monad m) => InjectedFn a (m b) -> t a -> m (t b) -- | like mapM_ (which is like mapM but ignores the results), -- but with an InjectedFn. mapWithM_ :: (Traversable t, Monad m) => InjectedFn a (m b) -> t a -> m () -- | like foldMap, but with an InjectedFn foldMapWith :: (Traversable t, Monoid b) => InjectedFn a b -> t a -> b -- | Represents a function from a, plus a number of injected -- values, to b. -- -- Used by mapWith (& related), which maps over a -- Traversable, injecting the additional values as it goes. -- -- Constructed by combining a map function with Injectors using -- the ^-> and <-^ operators. -- -- The sequence: -- --

--   (a -> i1 -> i2 -> ... -> in -> b) op1 inj1 op2 inj2 ... opn injn
--

-- -- where: -- --

each op is ^-> or <-^; -- and
each inj is an Injector

-- -- produces an InjectedFn a b, with n injected values. data InjectedFn a b -- | An Injectable is (recursively) either: -- --

a function (a -> i -> b); or
an InjectedFn a (i -> b), created by -- Injectable op Injector

class Injectable m -- | Inject "from the left" (^->) :: Injectable m => m a (i -> b) -> Injector a i -> InjectedFn a b -- | Inject "from the right" (<-^) :: Injectable m => m a (i -> b) -> Injector a i -> InjectedFn a b infixl 1 ^-> infixl 1 <-^ -- | inject True if the item is at the limit: -- --

from the left: if it's the first item
from the right: if it's the last item

-- -- else inject False. isLim :: Injector a Bool -- | inject Just the adjacent item: -- --

from the left: the previous item, except for the first item
from the right: the next item, except for the last item. (The -- "previous from the right" is the "next".)

-- -- inject Nothing if there is no adjacent item (i.e. for the first -- / last). adjElt :: Injector a (Maybe a) -- | inject the item index: -- --

from the left: the first item is 0, the second 1, etc.
from the right: the last item is 0, the penultimate 1, etc.

eltIx :: Integral i => Injector a i -- | Inject each given element in turn: -- --

from the left: the first element will be injected for the first -- item in the Traversable.
from the right: the first element will be injected for the last -- item in the Traversable.

-- -- As a result of laziness, it is not always an error if there are not -- enough elements, for example: -- --

--   >>> drop 1 $ mapWith ((\_ i -> i) <-^ eltFrom [8,2]) "abc"
--   [2,8]
--

eltFrom :: Foldable f => f i -> Injector a i -- | a safe version of eltFrom. Injects Just each given -- element in turn, or Nothing after they've been exhausted. eltFromMay :: Foldable f => f i -> Injector a (Maybe i) -- | a safe version of eltFrom. Injects each given element in turn, -- or the default after they've been exhausted. eltFromDef :: Foldable f => i -> f i -> Injector a i -- | isLim, from the left. isFirst :: Injectable f => f a (Bool -> b) -> InjectedFn a b -- | isLim, from the right. isLast :: Injectable f => f a (Bool -> b) -> InjectedFn a b -- | adjElt, from the left. prevElt :: Injectable f => f a (Maybe a -> b) -> InjectedFn a b -- | adjElt, from the right. nextElt :: Injectable f => f a (Maybe a -> b) -> InjectedFn a b -- | Injectors have an initial state and a generate function. -- -- For each item in the Traversable, the generate function can use -- both: -- --

the item from the Traversable, and
the current state

-- -- to determine both: -- --

the injection value, and
the new state.

-- -- The first value to inject is determined by a first call to the -- generate function. The first call to the generate function is with the -- first (if combined with ^->) or last (if combined with -- <-^) item from the Traversable and the initial state. -- -- For example: -- --

--   >>> funnyNext a s = (a + s, a + 1)
--   
--   >>> funnyInjector = Injector funnyNext 17
--   
--   >>> mapWith ((\_ i -> i) ^-> funnyInjector) [4,8,3]
--   [21,13,12]
--

-- -- TODO: table -- --

--   >>> mapWith ((\_ i -> i) <-^ funnyInjector) [4,8,3]
--   [13,12,20]
--

-- -- TODO: table -- -- More usefully, this would allow for e.g. the prior two elements: -- --

--   prev2Inj = Injector (\x i@(prev1May, prev2May) -> (i, (Just x, prev1May))) (Nothing, Nothing)
--

-- -- or random values, etc. data Injector a i -- | the first argument is a generate function, the second argument is the -- initial state. Injector :: (a -> s -> (i, s)) -> s -> Injector a i instance MapWith.Injectable (->) instance MapWith.Injectable MapWith.InjectedFn