Awesome
Universum
universum
is a custom prelude used in @Serokell that has:
- Excellent documentation: tutorial, migration guide from
Prelude
, Haddock with examples for (almost) every function, all examples are tested withdoctest
, documentation regarding internal module structure. universum
-specific HLint rules:.hlint.yaml
- Focus on safety, convenience and efficiency.
What is this file about?
This README contains introduction to Universum
and a tutorial on how to use it.
Structure of this tutorial
This tutorial has several parts:
- Philosophy and motivation.
- How to use
universum
. - Changes in
Prelude
(some gotchas). - Already known things that weren't in
Prelude
brought into scope. - New things added.
- Migration guide from
Prelude
.
This is neither a tutorial on Haskell nor tutorial on each function contained in Universum. For detailed documentation of every function together with examples and usage, see Haddock documentation.
Why another custom Prelude? ↑
Motivation
At Serokell, we strive to be as productive as possible. That's why we are using Haskell. This choice of language implies
that we're restricted to use Prelude
:
implicit import of basic functions, type classes and data types. Unfortunately, the default Prelude
is considered to be not so good
due to some historical reasons.
This is why we decided to use a better tool. Luckily, Haskell provides us with the ability
to replace default Prelude
with an alternative. All we had to do is to implement a
new basic set of defaults. There already were plenty of preludes,
so we didn't plan to implement everything from scratch.
After some long, hot discussions, our team decided to base our custom prelude on
protolude
. If you're not familiar with it,
you can read a tutorial about protolude
.
The next section explains why we've made this choice and what we are willing to do.
This tutorial doesn't cover the differences from protolude
. Instead, it explains how Universum is different from regular Prelude
.
Main goals
While creating and maintaining a custom prelude, we are pursuing the following goals:
- Avoid all partial functions.
We like total and exception-free functions.
You can still use some unsafe functions from
Universum.Unsafe
module, but they are not exported by default. - Use more efficient string representations.
String
type is crushingly inefficient. All our functions either try to be polymorphic over string type or useText
as the default string type. Because the community is evolving slowly, some libraries still useString
type, soString
type alias is still reexported. We recommend to avoidString
as much as you can! - Try to not reinvent the wheel. We're not trying to rebuild whole type hierarchy from scratch,
as it's done in
classy-prelude
. Instead, we reexport common and well-known things frombase
and some other libraries that are used in everyday production programming in Haskell.Note: well, we did end up inventing some new things.
- Export more useful and commonly used functions. Hello, my name is Dmitry. I was
coding Haskell for 3 years but still hoogling which module
liftIO
comes from. Things likeliftIO
,ReaderT
type,MVar
-related functions have unambiguous names, are used in almost every non-trivial project, and it's really tedious to import them manually every time. - Make changes only when there are enough good reasons to make these changes. We have a code modification policy which semi-formally describes pre-conditions for different types of changes.
Unlike protolude
, we are:
- Not trying to be as general as possible (thus we don't export much from
GHC.Generics
). - Not trying to maintain every version of
ghc
compiler (but at least the latest 3). - Trying to make writing production code easier (see enhancements and fixes).
How to use Universum ↑
Okay, enough philosophy. If you want to just start using universum
and
explore it with the help of compiler, set everything up according to the instructions below.
Disable the built-in prelude at the top of your file:
{-# LANGUAGE NoImplicitPrelude #-}
Or directly in your project .cabal
file, if you want to use in every module by default:
default-extensions: NoImplicitPrelude
Then add the following import to your modules:
import Universum
If you're using Emacs and don't want to
type import Universum
manually every time, you can
modify your configs
a little bit.
If you want to get familiar with universum
internal structure, you can just
read top-level documentation for
Universum
module.
Gotchas ↑
head
,tail
,last
,init
,foldl1
,minimum
and other were-partial functions work withNonEmpty a
instead of[a]
.- Safe analogue for
head
,foldl1
,foldr1
,minimum
,maximum
functions, for instance:safeHead :: [a] -> Maybe a
. undefined
triggers a compiler warning, which is probably not what you want. Either usethrowIO
,Except
,error
orbug
.map
isfmap
now.- Multiple sorting functions are available without imports:
sortBy :: (a -> a -> Ordering) -> [a] -> [a]
: sorts list using given custom comparator.sortWith :: Ord b => (a -> b) -> [a] -> [a]
: sorts a list based on some property of its elements.sortOn :: Ord b => (a -> b) -> [a] -> [a]
: just likesortWith
, but more time-efficient if function is calculated slowly (though less space-efficient). So you should writesortOn length
(would sort elements by length) butsortWith fst
(would sort list of pairs by first element).
- Functions
sum
andproduct
are strict now, which makes them more efficient. - If you try to do something like
putStrLn "hi"
, you'll get an error message ifOverloadedStrings
is enabled – it happens because the compiler doesn't know what type to infer for the string. UseputTextLn
in this case. - Since
show
doesn't come fromShow
anymore, you can't writeShow
instances easily. See migration guide for details. - You can't call some
Foldable
methods overMaybe
and some other types.Foldable
generalization is useful but potentially error-prone. Instead we created our own fully compatible withFoldable
Container
type class but that restricts the usage of functions likelength
overMaybe
,Either
,Identity
and tuples. We're also using GHC 8 feature of custom compile-time errors to produce more helpful messages. - As a consequence of previous point, some functions like
traverse_
,forM_
,sequenceA_
, etc. are generalized overContainer
type classes. error
takesText
.- We are exporting a rewrite rule which replaces
toString . toText :: Text -> Text
withid
. Note that this changes semantics in some corner cases.
Things that you were already using, but now you don't have to import them explicitly ↑
Commonly used libraries
First of all, we reexport some generally useful modules: Control.Applicative
,
Data.Traversable
, Data.Monoid
, Control.DeepSeq
, Data.List
, and lots of others.
Just remove unneeded imports after importing Universum
(GHC should tell you which ones).
Then, some commonly used types: Map/HashMap/IntMap
, Set/HashSet/IntSet
, Seq
, Text
and ByteString
(as well as synonyms LText
and LByteString
for lazy versions).
liftIO
and MonadIO
are exported by default. A lot of IO
functions are generalized to MonadIO
.
deepseq
is exported. For instance, if you want to force deep evaluation of some value (in IO),
you can write evaluateNF a
. WHNF evaluation is possible with evaluateWHNF a
.
We also reexport big chunks of these libraries: mtl
, stm
, microlens
, microlens-mtl
.
Bifunctor
type class with useful instances is exported.
first
andsecond
functions apply a function to first/second part of a tuple (for tuples).bimap
takes two functions and applies them to first and second parts respectively.
Text
We export Text
and LText
, and some functions work with Text
instead of String
–
specifically, IO functions (readFile
, putStrLn
, etc) and show
. In fact, show
is polymorphic and can produce strict or lazy Text
, String
, or ByteString
.
Also, toText/toLText/toString
can convert Text|LText|String
types to Text/LText/String
. If you want to convert to and from ByteString
use encodeUtf8/decodeUtf8
functions.
Debugging and undefined
s
trace
, traceM
, traceShow
, etc. are available by default. GHC will warn you
if you accidentally leave them in code, however (same for undefined
).
We also have data Undefined = Undefined
(which, too, comes with warnings).
Exceptions
We use safe-exceptions
library for exceptions handling. Don't import Control.Exceptions
module explicitly. Instead use functionality from safe-exceptions
provided by universum
or import Control.Exceptions.Safe
module.
What's new? ↑
Finally, we can move to part describing the new cool features we bring with universum
.
-
uncons
splits a list at the first element. -
ordNub
andsortNub
are O(n log n) versions ofnub
(which is quadratic) andhashNub
andunstableNub
are almost O(n) versions ofnub
. -
(&)
– reverse application.x & f & g
instead ofg $ f $ x
is useful sometimes. -
whenM
,unlessM
,ifM
,guardM
are available and do what you expect them to do (e.g.whenM (doesFileExist "foo")
). -
Very generalized version of
concatMapM
, too, is available and does what expected. -
readMaybe
andreadEither
are likeread
but total and give eitherMaybe
orEither
with parse error. -
when(Just|Nothing|Left|Right|NotEmpty)[M][_]
let you conditionally execute something. Before:case mbX of Nothing -> return () Just x -> ... x ...
After:
whenJust mbX $ \x -> ... x ...
-
for_
for loops. There's alsoforM_
butfor_
looks a bit nicer.for_ [1..10] $ \i -> do ...
-
andM
,allM
,anyM
,orM
are monadic version of corresponding functions frombase
. -
Type operator
$
for writing types likeMaybe $ Either String $ Maybe Int
. -
Each
type family. So this:f :: Each [Show, Read] [a, b] => a -> b -> String
translates into this:
f :: (Show a, Show b, Read a, Read b) => a -> b -> String
-
With
type operator. So this:a :: With [Show, Read] a => a -> a
translates into this:
a :: (Show a, Read a) => a -> a
-
Variadic composition operator
(...)
. So you can write:ghci> (show ... (+)) 1 2 "3" ghci> show ... 5 "5" ghci> (null ... zip5) [1] [2] [3] [] [5] True ghci> let process = map (+3) ... filter ghci> process even [1..5] [5,7]
-
Conversions between
Either
andMaybe
likerightToMaybe
andmaybeToLeft
with clear semantic. -
using(Reader|State)[T]
functions as aliases forflip run(Reader|State)[T]
. -
One
type class for creating singleton containers. Even monomorhpic ones likeText
. -
evaluateWHNF
andevaluateNF
functions as clearer and lifted aliases forevaluate
andevaluate . force
. -
ToPairs
type class for data types that can be converted to list of pairs (likeMap
orHashMap
orIntMap
).
Migration guide from Prelude ↑
In order to replace default Prelude
with universum
you should start with instructions given in
how to use universum section.
This section describes what you need to change to make your code compile with universum
.
-
Enable
-XOverloadedStrings
and-XTypeFamilies
extension by default for your project. -
Since
head
,tail
,minimum
and some other functions work forNonEmpty
you should refactor your code in one of the multiple ways described below:- Change
[a]
toNonEmpty a
where it makes sense. - Use functions which return
Maybe
. They can be implemented usingnonEmpty
function. Likehead <$> nonEmpty l
.head <$> nonEmpty l
issafeHead l
tail
isdrop 1
. It's almost never a good idea to usetail
fromPrelude
.
- Add
import qualified Universum.Unsafe as Unsafe
and replace function with qualified usage.
- Change
-
If you use
fromJust
or!!
you should use them fromimport qualified Universum.Unsafe as Unsafe
. -
Derive or implement
Container
instances for your data types which implementFoldable
instances. This can be done in a single line becauseContainer
type class automatically derives fromFoldable
. -
Container
type class fromuniversum
replacesFoldable
and doesn't have instances forMaybe a
,(a, b)
,Identity a
andEither a b
. If you usefoldr
orforM_
or similar for something likeMaybe a
you should replace usages of such function with monomorhpic alternatives:-
Maybe
(?:) :: Maybe a -> a -> a
fromMaybe :: a -> Maybe a -> a
maybeToList :: Maybe a -> [a]
maybeToMonoid :: Monoid m => Maybe m -> m
maybe :: b -> (a -> b) -> Maybe a -> b
whenJust :: Applicative f => Maybe a -> (a -> f ()) -> f ()
whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()
-
Either
fromLeft :: a -> Either a b -> a
fromRight :: b -> Either a b -> b
either :: (a -> c) -> (b -> c) -> Either a b -> c
whenRight :: Applicative f => Either l r -> (r -> f ()) -> f ()
whenRightM :: Monad m => m (Either l r) -> (r -> m ()) -> m ()
-
-
If you have types like
foo :: Foldable f => f a -> a -> a
you should chose one of the following:Right
: Modify types forContainer
likefoo :: (Container t, Element t ~ a) => t -> a -> a
.Left
: ImportData.Foldable
modulequalified
and use everythingFoldable
-related qualified.
-
Forget about
String
type.- Replace
putStr
andputStrLn
withputText
andputTextLn
. - Replace
(++)
with(<>)
forString
-like types. - Try to use
fmt
library if you need to construct messages. - Use
toText/toLText/toString
functions to convert toText/LazyText/String
types. - Use
encodeUtf8/decodeUtf8
to convert to/fromByteString
.
- Replace
-
Run
hlint
using.hlint.yaml
file fromuniversum
package to cleanup code and imports. -
Since vanilla
show
from theShow
class is not available, your customShow
instances will fail to compile. You canimport qualified Text.Show
to bring vanillashow
to scope with qualified name. It will not conflict withshow
fromuniversum
and yourShow
instances will compile successfully.