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

Language | Haskell2010 |

Main module that reexports all functionality allowed to use
without importing any other modules. Just add next lines to your
module to replace default `Prelude`

with better one.

{-# LANGUAGE NoImplicitPrelude #-}importUniversum

This documentation section contains description of internal module structure to help navigate between modules, search for interesting functionalities and understand where you need to put your new changes.

Functions and types are distributed across multiple modules and grouped by
meaning or **theme**. Name of the module should give you hints regarding what
this module contains. Some *themes* contain a great amount of both reexported
functions and functions of our own. To make it easier to understand these huge
chunks of functions, all reexported stuff is moved into separate module with
name `Universum.SomeTheme.Reexport`

and our own functions and types are in
`Universum.SomeTheme.SomeName`

. For example, see modules
Universum.Container.Class and Universum.Container.Reexport.

Below is a short description of what you can find under different modules:

**Universum.Applicative**: reexports from Control.Applicative and some general-purpose applicative combinators.**Universum.Base**: different general types and type classes from`base`

package (`Int`

,`Num`

,`Generic`

, etc.) not exported by other modules.**Universum.Bool**:`Bool`

data type with different predicates and combinators.**Universum.Container**:`Foldable`

replacement, types from`containers`

and`unordered-containers`

and`vector`

packages.**Universum.Debug**:`trace`

-like debugging functions with compile-time warnings (so you don't forget to remove them)**Universum.DeepSeq**: reexports from Control.DeepSeq module and functions to evaluate expressions to weak-head normal form or normal form.**Universum.Exception**: reexports Control.Exception.Safe from`safe-exceptions`

package,`bug`

as better`error`

,`Exc`

pattern synonym for convenient pattern-matching on exceptions.**Universum.Function**: almost everything from Data.Function module.**Universum.Functor**: reexports from Data.Functor, Data.Bifunctor, other useful`Functor`

combinators.**Universum.Lifted**: lifted to`MonadIO`

functions to work with console, files,`IORef`

s,`MVar`

s, etc.**Universum.List**: big chunk of Data.List,`NonEmpty`

type and functions for this type (`head`

,`tail`

,`last`

,`init`

).**Universum.Monad**: monad transormers, combinators for`Maybe`

and`Either`

.**Universum.Monoid**: reexports from Data.Monoid and Data.Semigroup.**Universum.Nub**: better versions of`nub`

function for list.**Universum.Print**: polymorphic`putStrLn`

function and functions to print`Text`

.**Universum.String**: reexports from`text`

and`bytestring`

packages with conversion functions between different textual types.**Universum.TypeOps**: convenient and fancy type-level operators.**Universum.Unsafe**: unsafe functions (produce`error`

). Not exported by Universum module by default.**Universum.VarArg**: variadic composition operator`...`

.

## Synopsis

- module Universum.Applicative
- module Universum.Base
- module Universum.Bool
- module Universum.Container
- module Universum.Debug
- module Universum.DeepSeq
- module Universum.Exception
- module Universum.Function
- module Universum.Functor
- module Universum.Lifted
- module Universum.List
- module Universum.Monad
- module Universum.Monoid
- module Universum.Nub
- module Universum.Print
- module Universum.String
- module Universum.TypeOps
- module Universum.VarArg
- (&) :: a -> (a -> b) -> b
- (<&>) :: Functor f => f a -> (a -> b) -> f b
- (^?) :: s -> Getting (First a) s a -> Maybe a
- (^..) :: s -> Getting (Endo [a]) s a -> [a]
- (^.) :: s -> Getting a s a -> a
- set :: ASetter s t a b -> b -> s -> t
- (.~) :: ASetter s t a b -> b -> s -> t
- over :: ASetter s t a b -> (a -> b) -> s -> t
- (%~) :: ASetter s t a b -> (a -> b) -> s -> t
- _1 :: Field1 s t a b => Lens s t a b
- _2 :: Field2 s t a b => Lens s t a b
- _3 :: Field3 s t a b => Lens s t a b
- _4 :: Field4 s t a b => Lens s t a b
- _5 :: Field5 s t a b => Lens s t a b
- type Lens s t a b = forall (f :: Type -> Type). Functor f => (a -> f b) -> s -> f t
- type Lens' s a = Lens s s a a
- type Traversal s t a b = forall (f :: Type -> Type). Applicative f => (a -> f b) -> s -> f t
- type Traversal' s a = Traversal s s a a
- preuse :: MonadState s m => Getting (First a) s a -> m (Maybe a)
- use :: MonadState s m => Getting a s a -> m a
- preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a)
- view :: MonadReader s m => Getting a s a -> m a

# Reexports from base and from modules in this repo

module Universum.Applicative

module Universum.Base

module Universum.Bool

module Universum.Container

module Universum.Debug

module Universum.DeepSeq

module Universum.Exception

module Universum.Function

module Universum.Functor

module Universum.Lifted

module Universum.List

module Universum.Monad

module Universum.Monoid

module Universum.Nub

module Universum.Print

module Universum.String

module Universum.TypeOps

module Universum.VarArg

# Lenses

(^?) :: s -> Getting (First a) s a -> Maybe a infixl 8 #

`s ^? t`

returns the 1st element `t`

returns, or `Nothing`

if `t`

doesn't return anything. It's trivially implemented by passing the `First`

monoid to the getter.

Safe `head`

:

`>>>`

Nothing`[] ^? each`

`>>>`

Just 1`[1..3] ^? each`

`>>>`

Nothing`Left 1 ^? _Right`

`>>>`

Just 1`Right 1 ^? _Right`

A non-operator version of (`^?`

) is called `preview`

, and – like `view`

– it's a bit more general than (`^?`

) (it works in `MonadReader`

). If you need the general version, you can get it from microlens-mtl; otherwise there's `preview`

available in Lens.Micro.Extras.

(^..) :: s -> Getting (Endo [a]) s a -> [a] infixl 8 #

`s ^.. t`

returns the list of all values that `t`

gets from `s`

.

A `Maybe`

contains either 0 or 1 values:

`>>>`

[3]`Just 3 ^.. _Just`

Gathering all values in a list of tuples:

`>>>`

[1,2,3,4]`[(1,2),(3,4)] ^.. each.each`

(^.) :: s -> Getting a s a -> a infixl 8 #

(`^.`

) applies a getter to a value; in other words, it gets a value out of a structure using a getter (which can be a lens, traversal, fold, etc.).

Getting 1st field of a tuple:

(`^.`

`_1`

) :: (a, b) -> a (`^.`

`_1`

) =`fst`

When (`^.`

) is used with a traversal, it combines all results using the `Monoid`

instance for the resulting type. For instance, for lists it would be simple concatenation:

`>>>`

"string"`("str","ing") ^. each`

The reason for this is that traversals use `Applicative`

, and the `Applicative`

instance for `Const`

uses monoid concatenation to combine “effects” of `Const`

.

A non-operator version of (`^.`

) is called `view`

, and it's a bit more general than (`^.`

) (it works in `MonadReader`

). If you need the general version, you can get it from microlens-mtl; otherwise there's `view`

available in Lens.Micro.Extras.

over :: ASetter s t a b -> (a -> b) -> s -> t #

Getting `fmap`

in a roundabout way:

`over`

`mapped`

::`Functor`

f => (a -> b) -> f a -> f b`over`

`mapped`

=`fmap`

Applying a function to both components of a pair:

`over`

`both`

:: (a -> b) -> (a, a) -> (b, b)`over`

`both`

= \f t -> (f (fst t), f (snd t))

Using

as a replacement for `over`

`_2`

`second`

:

`>>>`

(10,"20")`over _2 show (10,20)`

(%~) :: ASetter s t a b -> (a -> b) -> s -> t infixr 4 #

(`%~`

) applies a function to the target; an alternative explanation is that it is an inverse of `sets`

, which turns a setter into an ordinary function.

is the same thing as `mapped`

`%~`

`reverse`

.`fmap`

`reverse`

See `over`

if you want a non-operator synonym.

Negating the 1st element of a pair:

`>>>`

(-1,2)`(1,2) & _1 %~ negate`

Turning all `Left`

s in a list to upper case:

`>>>`

[Left "FOO",Right "bar"]`(mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]`

_1 :: Field1 s t a b => Lens s t a b #

Gives access to the 1st field of a tuple (up to 5-tuples).

Getting the 1st component:

`>>>`

1`(1,2,3,4,5) ^. _1`

Setting the 1st component:

`>>>`

(10,2,3)`(1,2,3) & _1 .~ 10`

Note that this lens is lazy, and can set fields even of `undefined`

:

`>>>`

(10,*** Exception: Prelude.undefined`set _1 10 undefined :: (Int, Int)`

This is done to avoid violating a lens law stating that you can get back what you put:

`>>>`

10`view _1 . set _1 10 $ (undefined :: (Int, Int))`

The implementation (for 2-tuples) is:

`_1`

f t = (,)`<$>`

f (`fst`

t)`<*>`

`pure`

(`snd`

t)

or, alternatively,

`_1`

f ~(a,b) = (\a' -> (a',b))`<$>`

f a

(where `~`

means a lazy pattern).

type Lens s t a b = forall (f :: Type -> Type). Functor f => (a -> f b) -> s -> f t #

`Lens s t a b`

is the lowest common denominator of a setter and a getter, something that has the power of both; it has a `Functor`

constraint, and since both `Const`

and `Identity`

are functors, it can be used whenever a getter or a setter is needed.

`a`

is the type of the value inside of structure`b`

is the type of the replaced value`s`

is the type of the whole structure`t`

is the type of the structure after replacing`a`

in it with`b`

type Lens' s a = Lens s s a a #

This is a type alias for monomorphic lenses which don't change the type of the container (or of the value inside).

type Traversal s t a b = forall (f :: Type -> Type). Applicative f => (a -> f b) -> s -> f t #

`Traversal s t a b`

is a generalisation of `Lens`

which allows many targets (possibly 0). It's achieved by changing the constraint to `Applicative`

instead of `Functor`

– indeed, the point of `Applicative`

is that you can combine effects, which is just what we need to have many targets.

Ultimately, traversals should follow 2 laws:

t pure ≡ pure fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)

The 1st law states that you can't change the shape of the structure or do anything funny with elements (traverse elements which aren't in the structure, create new elements out of thin air, etc.). The 2nd law states that you should be able to fuse 2 identical traversals into one. For a more detailed explanation of the laws, see this blog post (if you prefer rambling blog posts), or The Essence Of The Iterator Pattern (if you prefer papers).

Traversing any value twice is a violation of traversal laws. You can, however, traverse values in any order.

type Traversal' s a = Traversal s s a a #

This is a type alias for monomorphic traversals which don't change the type of the container (or of the values inside).

use :: MonadState s m => Getting a s a -> m a #

`use`

is (`^.`

) (or `view`

) which implicitly operates on the state; for instance, if your state is a record containing a field `foo`

, you can write

`x <- ``use`

foo

to extract `foo`

from the state. In other words, `use`

is the same as `gets`

, but for getters instead of functions.

The implementation of `use`

is straightforward:

`use`

l =`gets`

(`view`

l)

If you need to extract something with a fold or traversal, you need `preuse`

.

preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a) #

`preview`

is a synonym for (`^?`

), generalised for `MonadReader`

(just like `view`

, which is a synonym for (`^.`

)).

`>>>`

Just 1`preview each [1..5]`

view :: MonadReader s m => Getting a s a -> m a #

`view`

is a synonym for (`^.`

), generalised for `MonadReader`

(we are able to use it instead of (`^.`

) since functions are instances of the `MonadReader`

class):

`>>>`

1`view _1 (1, 2)`

When you're using `Reader`

for config and your config type has lenses generated for it, most of the time you'll be using `view`

instead of `asks`

:

doSomething :: (`MonadReader`

Config m) => m Int doSomething = do thingy <-`view`

setting1 -- same as “`asks`

(`^.`

setting1)” anotherThingy <-`view`

setting2 ...