Focus

focus-1.0.3.2: A general abstraction for manipulating elements of container data structures

Safe Haskell | None
Language | Haskell2010

Focus

Contents

- Pure functions
  - Reading functions
  - Modifying functions
  - Construction utils
- Monadic functions
  - Reading functions
  - Modifying functions
  - Construction utils
- Composition
- Change-inspecting functions
- STM

Synopsis

- data Focus element (m :: Type -> Type) result = Focus (m (result, Change element)) (element -> m (result, Change element))
- data Change a
  - = Leave
  - | Remove
  - | Set a
- member :: forall (m :: Type -> Type) a. Monad m => Focus a m Bool
- lookup :: forall (m :: Type -> Type) a. Monad m => Focus a m (Maybe a)
- lookupWithDefault :: forall (m :: Type -> Type) a. Monad m => a -> Focus a m a
- delete :: forall (m :: Type -> Type) a. Monad m => Focus a m ()
- lookupAndDelete :: forall (m :: Type -> Type) a. Monad m => Focus a m (Maybe a)
- insert :: forall (m :: Type -> Type) a. Monad m => a -> Focus a m ()
- insertOrMerge :: forall (m :: Type -> Type) a. Monad m => (a -> a -> a) -> a -> Focus a m ()
- alter :: forall (m :: Type -> Type) a. Monad m => (Maybe a -> Maybe a) -> Focus a m ()
- adjust :: forall (m :: Type -> Type) a. Monad m => (a -> a) -> Focus a m ()
- update :: forall (m :: Type -> Type) a. Monad m => (a -> Maybe a) -> Focus a m ()
- accessAndAdjust :: forall (m :: Type -> Type) s a. Monad m => (s -> a) -> (s -> s) -> Focus s m (Maybe a)
- liftState :: forall (m :: Type -> Type) s a. Monad m => State s a -> Focus s m (Maybe a)
- liftStateFn :: forall (m :: Type -> Type) s a. Monad m => (s -> (a, s)) -> Focus s m (Maybe a)
- cases :: forall (m :: Type -> Type) b a. Monad m => (b, Change a) -> (a -> (b, Change a)) -> Focus a m b
- unitCases :: forall (m :: Type -> Type) a. Monad m => Change a -> (a -> Change a) -> Focus a m ()
- lookupWithDefaultM :: Monad m => m a -> Focus a m a
- insertM :: Monad m => m a -> Focus a m ()
- insertOrMergeM :: Monad m => (a -> a -> m a) -> m a -> Focus a m ()
- alterM :: Monad m => (Maybe a -> m (Maybe a)) -> Focus a m ()
- adjustM :: Monad m => (a -> m a) -> Focus a m ()
- updateM :: Monad m => (a -> m (Maybe a)) -> Focus a m ()
- casesM :: m (b, Change a) -> (a -> m (b, Change a)) -> Focus a m b
- unitCasesM :: Monad m => m (Change a) -> (a -> m (Change a)) -> Focus a m ()
- mappingInput :: forall (m :: Type -> Type) a b x. Monad m => (a -> b) -> (b -> a) -> Focus a m x -> Focus b m x
- extractingInput :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Maybe a)
- extractingChange :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Change a)
- projectingChange :: forall (m :: Type -> Type) a c b. Monad m => (Change a -> c) -> Focus a m b -> Focus a m (b, c)
- testingIfModifies :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool)
- testingIfRemoves :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool)
- testingIfInserts :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool)
- testingSizeChange :: forall (m :: Type -> Type) sizeChange a b. Monad m => sizeChange -> sizeChange -> sizeChange -> Focus a m b -> Focus a m (b, sizeChange)
- onTVarValue :: Focus a STM b -> Focus (TVar a) STM b

# Documentation

data Focus element (m :: Type -> Type) result #

Abstraction over the modification of an element of a datastructure.

It is composable using the standard typeclasses, e.g.:

    lookupAndDelete :: Monad m => Focus a m (Maybe a)
    lookupAndDelete = lookup <* delete

Constructors

Focus (m (result, Change element)) (element -> m (result, Change element)) |

#### Instances

Instances details

MonadTrans (Focus element) # |
Instance details Defined in Focus Methods lift :: Monad m => m a -> Focus element m a #
Monad m => Applicative (Focus element m) # |
Instance details Defined in Focus Methods pure :: a -> Focus element m a # (<*>) :: Focus element m (a -> b) -> Focus element m a -> Focus element m b # liftA2 :: (a -> b -> c) -> Focus element m a -> Focus element m b -> Focus element m c # (*>) :: Focus element m a -> Focus element m b -> Focus element m b # (<*) :: Focus element m a -> Focus element m b -> Focus element m a #
Functor m => Functor (Focus element m) # |
Instance details Defined in Focus Methods fmap :: (a -> b) -> Focus element m a -> Focus element m b # (<$) :: a -> Focus element m b -> Focus element m a #
Monad m => Monad (Focus element m) # |
Instance details Defined in Focus Methods (>>=) :: Focus element m a -> (a -> Focus element m b) -> Focus element m b # (>>) :: Focus element m a -> Focus element m b -> Focus element m b # return :: a -> Focus element m a #

data Change a #

What to do with the focused value.

The interpretation of the commands is up to the context APIs.

Constructors

Leave | Produce no changes
Remove | Delete it
Set a | Set its value to the provided one

#### Instances

Instances details

Functor Change # |
Instance details Defined in Focus Methods fmap :: (a -> b) -> Change a -> Change b # (<$) :: a -> Change b -> Change a #
Monoid (Change a) # |
Instance details Defined in Focus Methods mempty :: Change a # mappend :: Change a -> Change a -> Change a # mconcat :: [Change a] -> Change a #
Semigroup (Change a) # |
Instance details Defined in Focus Methods (<>) :: Change a -> Change a -> Change a # sconcat :: NonEmpty (Change a) -> Change a # stimes :: Integral b => b -> Change a -> Change a #
Show a => Show (Change a) # |
Instance details Defined in Focus Methods showsPrec :: Int -> Change a -> ShowS # show :: Change a -> String # showList :: [Change a] -> ShowS #
Eq a => Eq (Change a) # |
Instance details Defined in Focus Methods (==) :: Change a -> Change a -> Bool # (/=) :: Change a -> Change a -> Bool #
Ord a => Ord (Change a) # |
Instance details Defined in Focus Methods compare :: Change a -> Change a -> Ordering # (<) :: Change a -> Change a -> Bool # (<=) :: Change a -> Change a -> Bool # (>) :: Change a -> Change a -> Bool # (>=) :: Change a -> Change a -> Bool # max :: Change a -> Change a -> Change a # min :: Change a -> Change a -> Change a #

# Pure functions

## Reading functions

member :: forall (m :: Type -> Type) a. Monad m => Focus a m Bool #

Reproduces the behaviour of `Data.Map.member`.

lookup :: forall (m :: Type -> Type) a. Monad m => Focus a m (Maybe a) #

Reproduces the behaviour of `Data.Map.lookup`.

lookupWithDefault :: forall (m :: Type -> Type) a. Monad m => a -> Focus a m a #

Reproduces the behaviour of `Data.Map.findWithDefault` with a better name.

## Modifying functions

delete :: forall (m :: Type -> Type) a. Monad m => Focus a m () #

Reproduces the behaviour of `Data.Map.delete`.

lookupAndDelete :: forall (m :: Type -> Type) a. Monad m => Focus a m (Maybe a) #

Lookup an element and delete it if it exists.

Same as ``lookup` <* `delete``.

insert :: forall (m :: Type -> Type) a. Monad m => a -> Focus a m () #

Reproduces the behaviour of `Data.Map.insert`.

insertOrMerge :: forall (m :: Type -> Type) a. Monad m => (a -> a -> a) -> a -> Focus a m () #

Reproduces the behaviour of `Data.Map.insertWith` with a better name.

alter :: forall (m :: Type -> Type) a. Monad m => (Maybe a -> Maybe a) -> Focus a m () #

Reproduces the behaviour of `Data.Map.alter`.

adjust :: forall (m :: Type -> Type) a. Monad m => (a -> a) -> Focus a m () #

Reproduces the behaviour of `Data.Map.adjust`.

update :: forall (m :: Type -> Type) a. Monad m => (a -> Maybe a) -> Focus a m () #

Reproduces the behaviour of `Data.Map.update`.

accessAndAdjust :: forall (m :: Type -> Type) s a. Monad m => (s -> a) -> (s -> s) -> Focus s m (Maybe a) #

Same as all of the following expressions:

`f g -> fmap (fmap f) lookup <* adjust g` `f g -> liftStateFn (f &&& g)` `f g -> liftStateFn ((,) $ f * g)`

liftState :: forall (m :: Type -> Type) s a. Monad m => State s a -> Focus s m (Maybe a) #

Lift a pure state monad.

liftStateFn :: forall (m :: Type -> Type) s a. Monad m => (s -> (a, s)) -> Focus s m (Maybe a) #

Lift a pure state-monad-like function.

## Construction utils

cases :: forall (m :: Type -> Type) b a. Monad m => (b, Change a) -> (a -> (b, Change a)) -> Focus a m b #

Lift pure functions which handle the cases of presence and absence of the element.

unitCases :: forall (m :: Type -> Type) a. Monad m => Change a -> (a -> Change a) -> Focus a m () #

Lift pure functions which handle the cases of presence and absence of the element and produce no result.

# Monadic functions

## Reading functions

lookupWithDefaultM :: Monad m => m a -> Focus a m a #

A monadic version of `lookupWithDefault`.

## Modifying functions

insertM :: Monad m => m a -> Focus a m () #

A monadic version of `insert`.

insertOrMergeM :: Monad m => (a -> a -> m a) -> m a -> Focus a m () #

A monadic version of `insertOrMerge`.

alterM :: Monad m => (Maybe a -> m (Maybe a)) -> Focus a m () #

A monadic version of `alter`.

adjustM :: Monad m => (a -> m a) -> Focus a m () #

A monadic version of `adjust`.

updateM :: Monad m => (a -> m (Maybe a)) -> Focus a m () #

A monadic version of `update`.

## Construction utils

casesM :: m (b, Change a) -> (a -> m (b, Change a)) -> Focus a m b #

Lift monadic functions which handle the cases of presence and absence of the element.

unitCasesM :: Monad m => m (Change a) -> (a -> m (Change a)) -> Focus a m () #

Lift monadic functions which handle the cases of presence and absence of the element and produce no result.

# Composition

mappingInput :: forall (m :: Type -> Type) a b x. Monad m => (a -> b) -> (b -> a) -> Focus a m x -> Focus b m x #

Map the Focus input.

# Change-inspecting functions

extractingInput :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Maybe a) #

Extends the output with the input.

extractingChange :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Change a) #

Extends the output with the change performed.

projectingChange :: forall (m :: Type -> Type) a c b. Monad m => (Change a -> c) -> Focus a m b -> Focus a m (b, c) #

Extends the output with a projection on the change that was performed.

testingIfModifies :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool) #

Extends the output with a flag, signaling whether a change, which is not `Leave`, has been introduced.

testingIfRemoves :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool) #

Extends the output with a flag, signaling whether the `Remove` change has been introduced.

testingIfInserts :: forall (m :: Type -> Type) a b. Monad m => Focus a m b -> Focus a m (b, Bool) #

Extends the output with a flag, signaling whether an item will be inserted. That is, it didn't exist before and a `Set` change is introduced.

testingSizeChange #

Arguments

:: forall (m :: Type -> Type) sizeChange a b. Monad m |
=> sizeChange | Decreased
-> sizeChange | Didn't change
-> sizeChange | Increased
-> Focus a m b |
-> Focus a m (b, sizeChange) |

Extend the output with a flag, signaling how the size will be affected by the change.

# STM

onTVarValue :: Focus a STM b -> Focus (TVar a) STM b #

Focus on the contents of a TVar.