Safe Haskell | Safe |
---|---|

Language | Haskell2010 |

## Synopsis

- examine :: Monoid e => Getting (e, a) s a -> s -> (e, a)
- examineList :: Monoid e => Getting (e, [a]) s a -> s -> (e, [a])
- preexamine :: Monoid e => Getting (e, First a) s a -> s -> Validation e a
- trySet :: LensLike (Validation e) s t a b -> b -> s -> Validation e t
- tryModify :: LensLike (Validation e) s t a b -> (a -> b) -> s -> Validation e t
- tryModify' :: LensLike (Validation e) s t a b -> (a -> Validation e b) -> s -> Validation e t
- (^&.) :: Monoid e => s -> Getting (e, a) s a -> (e, a)
- (^&..) :: Monoid e => s -> Getting (e, [a]) s a -> (e, [a])
- (^&?) :: Monoid e => s -> Getting (e, First a) s a -> Validation e a
- (.&~) :: LensLike (Validation e) s t a b -> b -> s -> Validation e t
- (%&~) :: LensLike (Validation e) s t a b -> (a -> b) -> s -> Validation e t
- (%%&~) :: LensLike (Validation e) s t a b -> (a -> Validation e b) -> s -> Validation e t
- fizzler :: (s -> Either e a) -> (s -> b -> Either e t) -> Fizzler e s t a b
- fizzleWhen :: e -> (s -> Bool) -> Fizzler' e s s
- fizzleUnless :: e -> (s -> Bool) -> Fizzler' e s s
- fizzleWith :: (s -> e) -> Fizzler e s t a b
- fizzleWithWhen :: (s -> e) -> (s -> Bool) -> Fizzler' e s s
- fizzleWithUnless :: (s -> e) -> (s -> Bool) -> Fizzler' e s s
- maybeFizzleWith :: (s -> Maybe e) -> Fizzler' e s s
- orFizzle :: (LensFail e f, Applicative f) => Traversing (->) f s t a b -> e -> LensLike f s t a b
- orFizzleWith :: (LensFail e f, Applicative f) => Traversing (->) f s t a b -> (s -> e) -> LensLike f s t a b
- adjustingErrors :: (e -> e) -> Fizzler' e s s
- adjustingErrorsWith :: (s -> e -> e) -> Fizzler' e s s
- type Fizzler e s t a b = forall f. (LensFail e f, Applicative f) => LensLike f s t a b
- type Fizzler' e s a = Fizzler e s s a a
- class LensFail e f | f -> e where
- fizzle :: e -> f a
- alterErrors :: (e -> e) -> f a -> f a
- joinErrors :: f (f a) -> f a

- module Data.Either.Validation

# Actions

examineList :: Monoid e => Getting (e, [a]) s a -> s -> (e, [a]) Source #

preexamine :: Monoid e => Getting (e, First a) s a -> s -> Validation e a Source #

See also `^&?`

Find the first element of a traversal; or return all errors found along the way.

`>>>`

Success 2`preexamine (traversed . fizzleWhen ["odd"] odd) [1, 2, 3, 4]`

`>>>`

Failure ["1 is too small","2 is too small","3 is too small","4 is too small"]`preexamine (traversed . fizzleWithWhen (\s -> [show s <> " is too small"]) (<10)) [1, 2, 3, 4]`

trySet :: LensLike (Validation e) s t a b -> b -> s -> Validation e t Source #

See also `.&~`

Set the focus of a lens/traversal. Returns a monoidal summary of failures or the altered structure.

`>>>`

Success ("hi",[1,42,3,4])`trySet (_2 . ix 1 . fizzleWhen ["shouldn't fail"] (const False)) 42 ("hi", [1, 2, 3, 4])`

`>>>`

Failure [2]`trySet (_2 . ix 1 . fizzleWithWhen (\n -> [n]) even) 42 ("hi", [1, 2, 3, 4])`

tryModify :: LensLike (Validation e) s t a b -> (a -> b) -> s -> Validation e t Source #

See also `%&~`

Modify the focus of a lens/traversal. Returns a monoidal summary of failures or the altered structure.

`>>>`

Success ("hi",[100,200,300,400])`tryModify (_2 . traversed . fizzleWhen ["shouldn't fail"] (const False)) (*100) ("hi", [1, 2, 3, 4])`

`>>>`

Failure [2,4]`tryModify (_2 . traversed . fizzleWithWhen (\n -> [n]) even) (*100) ("hi", [1, 2, 3, 4])`

tryModify' :: LensLike (Validation e) s t a b -> (a -> Validation e b) -> s -> Validation e t Source #

See also `%%&~`

Modify the focus of a lens/traversal with a function which may fail. Returns a monoidal summary of failures or the altered structure.

`>>>`

Failure [2,4]`tryModify' (_2 . traversed . fizzleWithWhen (\n -> [n]) even) (Success . (*100)) ("hi", [1, 2, 3, 4])`

`>>>`

Failure ["1 failed","2 failed","3 failed","4 failed"]`tryModify' (_2 . traversed) (\n -> Failure [show n <> " failed"]) ("hi", [1, 2, 3, 4])`

# Operators

(^&..) :: Monoid e => s -> Getting (e, [a]) s a -> (e, [a]) infixl 8 Source #

Operator alias of `examineList`

View the focuses of a traversal as a list.
Returns the elements and the monoidal sum of any errors encountered. Analogous to `^..`

with error collection.

`>>>`

(["2","4"],[1,3])`("hi", [1, 2, 3, 4]) ^&.. (_2 . traversed . fizzleWithWhen (\n -> [show n]) even)`

(^&?) :: Monoid e => s -> Getting (e, First a) s a -> Validation e a infixl 8 Source #

Operator alias of `preexamine`

Find the first element of a traversal; or return all errors found along the way.

`>>>`

Success 2`[1, 2, 3, 4] ^&? traversed . fizzleWhen ["odd"] odd`

`>>>`

Failure ["1 is too small","2 is too small","3 is too small","4 is too small"]`[1, 2, 3, 4] ^&? traversed . fizzleWithWhen (\s -> [show s <> " is too small"]) (<10)`

(.&~) :: LensLike (Validation e) s t a b -> b -> s -> Validation e t infixl 8 Source #

Operator alias of 'trySet

Set the focus of a lens/traversal. Returns a monoidal summary of failures or the altered structure.

`>>>`

Success ("hi",[1,42,3,4])`("hi", [1, 2, 3, 4]) & _2 . ix 1 . fizzleWhen ["shouldn't fail"] (const False) .&~ 42`

`>>>`

Failure [2]`("hi", [1, 2, 3, 4]) & _2 . ix 1 . fizzleWithWhen (\n -> [n]) even .&~ 42`

(%&~) :: LensLike (Validation e) s t a b -> (a -> b) -> s -> Validation e t infixl 8 Source #

Operator alias of `tryModify`

Modify the focus of a lens/traversal. Returns a monoidal summary of failures or the altered structure.

`>>>`

Success ("hi",[100,200,300,400])`("hi", [1, 2, 3, 4]) & _2 . traversed . fizzleWhen ["shouldn't fail"] (const False) %&~ (*100)`

`>>>`

Failure [2,4]`("hi", [1, 2, 3, 4]) & _2 . traversed . fizzleWithWhen (\n -> [n]) even %&~ (*100)`

(%%&~) :: LensLike (Validation e) s t a b -> (a -> Validation e b) -> s -> Validation e t infixl 8 Source #

Operator alias of `tryModify'`

Modify the focus of a lens/traversal with a function which may fail. Returns a monoidal summary of failures or the altered structure.

The definition of this function is actually just:

(%%&~) = (%%~)

But this combinator is provided for discoverability, completeness, and hoogle-ability.

`>>>`

Failure [2,4]`("hi", [1, 2, 3, 4]) & _2 . traversed . fizzleWithWhen (\n -> [n]) even %%&~ Success . (*100)`

`>>>`

Failure ["1 failed","2 failed","3 failed","4 failed"]`("hi", [1, 2, 3, 4]) & _2 . traversed %%&~ (\n -> Failure [show n <> " failed"])`

# Failing

fizzler :: (s -> Either e a) -> (s -> b -> Either e t) -> Fizzler e s t a b Source #

Construct a fizzler allowing failure both in the getter and setter.

fizzleWhen :: e -> (s -> Bool) -> Fizzler' e s s Source #

Cause the current traversal to fizzle with a failure when the focus matches a predicate

`>>>`

(["failure","failure"],[1,3])`("hi", [1, 2, 3, 4]) ^&.. _2 . traversed . fizzleWhen ["failure"] even :: ([String], [Int])`

fizzleUnless :: e -> (s -> Bool) -> Fizzler' e s s Source #

Cause the current traversal to fizzle with a failure when the focus fails a predicate

`>>>`

(["failure","failure"],[2,4])`("hi", [1, 2, 3, 4]) ^&.. _2 . traversed . fizzleUnless ["failure"] even`

fizzleWith :: (s -> e) -> Fizzler e s t a b Source #

Always fizzle with the given error builder >>> let p x = [show x] >>> ("hi", [1, 2, 3, 4]) ^&.. _2 . traversed . fizzleWith p (["1","2","3","4"],[])

fizzleWithWhen :: (s -> e) -> (s -> Bool) -> Fizzler' e s s Source #

Fizzle using the given error builder when the focus matches a predicate

`>>>`

`let p x = [show x <> " was even"]`

`>>>`

(["2 was even","4 was even"],[1,3])`("hi", [1, 2, 3, 4]) ^&.. _2 . traversed . fizzleWithWhen p even`

fizzleWithUnless :: (s -> e) -> (s -> Bool) -> Fizzler' e s s Source #

Fizzle using the given error builder when the focus fails a predicate

`>>>`

`let p x = [show x <> " was even"]`

`>>>`

(["2 was even","4 was even"],[1,3])`("hi", [1, 2, 3, 4]) ^&.. _2 . traversed . fizzleWithUnless p odd`

maybeFizzleWith :: (s -> Maybe e) -> Fizzler' e s s Source #

orFizzle :: (LensFail e f, Applicative f) => Traversing (->) f s t a b -> e -> LensLike f s t a b Source #

Fail with the given error when the provided traversal produces no elements.

`>>>`

(["nothing over 10"],[])`("hi", [1, 2, 3, 4]) ^&.. (_2 . traversed . filtered (> 10)) `orFizzle` ["nothing over 10"]`

orFizzleWith :: (LensFail e f, Applicative f) => Traversing (->) f s t a b -> (s -> e) -> LensLike f s t a b Source #

Fail using the given error builder when the provided traversal produces no elements.

`>>>`

(["searched 4 elements, no luck"],[])`("hi", [1, 2, 3, 4]) ^&.. (_2 . traversed . filtered (> 10)) `orFizzleWith` (\(_, xs) -> ["searched " <> show (length xs) <> " elements, no luck"])`

# Adjusting Errors

adjustingErrors :: (e -> e) -> Fizzler' e s s Source #

Adjust any errors which occur in the following branch. Note that we can't change the error type, but this can be helpful for adding context to errors if they occur at a position without enough context.

This is does nothing when no errors occur.

`>>>`

(["got 3!","got 4"],[1,2])`[1, 2, 3, 4 :: Int] ^&.. traversed . fizzleWhen ["got 4"] (== 4) . adjustingErrors (fmap (<> "!")) . fizzleWhen ["got 3"] (== 3)`

adjustingErrorsWith :: (s -> e -> e) -> Fizzler' e s s Source #

Adjust any errors which occur in the following branch, using the value available at the current position to add context.. Note that we can't change the error type, but this can be helpful for adding context to errors if they occur at a position without enough context.

This is does nothing when no errors occur.

`>>>`

(["3: fail","got 4"],[1,2])`[1, 2, 3, 4 :: Int] ^&.. traversed . fizzleWhen ["got 4"] (== 4) . adjustingErrorsWith (\n -> fmap (\e -> show n <> ": " <> e)) . fizzleWhen ["fail"] (== 3)`

# Types

type Fizzler e s t a b = forall f. (LensFail e f, Applicative f) => LensLike f s t a b Source #

Represents a lens-like which may fail with an error of type `e`

# Classes

class LensFail e f | f -> e where Source #

alterErrors :: (e -> e) -> f a -> f a Source #

joinErrors :: f (f a) -> f a Source #

## Instances

LensFail e (Validation e) Source # | |

Defined in Control.Lens.Error.Internal.LensFail fizzle :: e -> Validation e a Source # alterErrors :: (e -> e) -> Validation e a -> Validation e a Source # joinErrors :: Validation e (Validation e a) -> Validation e a Source # | |

LensFail e (Either e) Source # | |

LensFail e (Const (Validation e a) :: Type -> Type) Source # | |

Defined in Control.Lens.Error.Internal.LensFail fizzle :: e -> Const (Validation e a) a0 Source # alterErrors :: (e -> e) -> Const (Validation e a) a0 -> Const (Validation e a) a0 Source # joinErrors :: Const (Validation e a) (Const (Validation e a) a0) -> Const (Validation e a) a0 Source # | |

LensFail e (Const (Either e a) :: Type -> Type) Source # | |

Monoid a => LensFail e (Const (e, a) :: Type -> Type) Source # | |

# Re-exports

module Data.Either.Validation