relude
is a custom prelude, an alternative to default Prelude
.
relude
tries to achieve the following goals:
-
Avoid all partial functions (like
head :: [a] -> a
). The types of partial functions lie about their behavior and usage of such functions can lead to the unexpected bugs. Though you can still use some unsafe functions fromRelude.Unsafe
module, but they are not exported by default. -
Type-safety. We like to make invalid states unrepresantable. And if it's possible to express this concept through the types then we will do it.
Example:
whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
instead of
whenNotNull :: Applicative f => [a] -> ([a] -> f ()) -> f ()
-
Performance. Prefer
Text
overString
, use spaceleak-free functions (like our customsum
andproduct
), introduce{-# INLINE #-}
and{-# SPECIALIZE #-}
pragmas where appropriate. -
Minimalism (low number of dependencies). We don't force users of
relude
to stick to some specific lens or text formatting or logging library. -
Convenience (like lifted to
MonadIO
functions, more reexports). But we want to bring common types and functions (likecontainers
andbytestring
) into scope because they are used in almost every application anyways. -
Provide excellent documentation.
- Tutorial
- Migration guide from
Prelude
- Haddock with examples for (almost) every function
(all examples are tested with
doctest
) - Documentation regarding internal module structure
relude
-specific HLint rules:.hlint.yaml
-
User-friendliness. Ability to quickly migrate to
relude
if you're familiar with the common libraries liketext
andcontainers
. -
Exploration. Experiment with new ideas and proposals without introducing breaking changes.
relude
uses the approach withExtra.*
modules which are not exported by default so it's quite easy to bring something new and let users decide to use it or not.
This README contains introduction to Relude
and a tutorial on how to use it.
This tutorial has several parts:
This is neither a tutorial on Haskell nor tutorial on each function contained
in Relude
. For detailed documentation of every function together with examples
and usage, see Haddock documentation.
Get started ↑
If you want to start using relude
in your project and explore it with the help
of compiler, set everything up according to the instructions below.
This is the recommended way to use custom prelude. It requires you to perform the following steps:
- Replace
base
dependency with corresponding version ofbase-noprelude
in your.cabal
file. - Add a
relude
dependency to your.cabal
file. - Add the following
Prelude
module to your project (both to filesystem and toexposed-modules
):module Prelude ( module Relude ) where import Relude
NOTE: if you use
summoner
to generate Haskell project, this tool can automatically create such structure for you when you specify custom prelude. - Optionally modify your
Prelude
to include more or less functions. Probably you want to hide something fromRelude
module. Or maybe you want to add something fromRelude.Extra.*
modules!
This is a very convenient way to add a custom prelude to your project because
you don't need to import module manually inside each file and enable the
NoImplicitPrelude
extension.
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 Relude
Difference from Prelude ↑
head
,tail
,last
,init
work withNonEmpty a
instead of[a]
.undefined
triggers a compiler warning, because you probably don't want to leaveundefined
in your code. Either usethrowIO
,Except
,error
orbug
.- 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. - Since
show
doesn't come fromShow
anymore, you need to exportShow
fromText.Show
module if you want to implementShow
instance manually. - You can't call
elem
andnotElem
functions overSet
andHashSet
. These functions are forbidden for these two types because of the performance reasons. error
takesText
.lookup
for lists is not exported.
Reexports ↑
relude
reexports some parts of the following libraries:
base
containers
unordered-containers
text
bytestring
transformers
mtl
deepseq
stm
If you want to clean up imports after switching to relude
, you can use
relude
-specific .hlint.yaml
configuration for this task.
Some generally useful modules from base
package, like: Control.Applicative
,
Data.Traversable
, Data.Monoid
, Data.List
, and lots of others.
liftIO
and MonadIO
are exported by default. A lot of IO
functions are
generalized to MonadIO
.
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.
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).
relude
reexports Exception
type from the base
package and introduces the
bug
function as an alternative to error
. There's also a very convenient
Exc
pattern-synonym to handle exceptions of different types.
See Relude.Exception
module for details on exceptions.
The following types from these two packages are exported: Then, some commonly used types:
- Maps: strict versions of
Map
,HashMap
,IntMap
. - Sets:
Set
,HashSet
,IntSet
. - Sequences:
Seq
.
relude
exports Text
and ByteString
(as well as synonyms LText
and LByteString
for lazy versions) 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.
The following parts of these two libraries are exported:
- Transformers:
State[T]
,Reader[T]
,ExceptT
,MaybeT
. - Classes:
MonadReader
,MonadState
,MonadError
.
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
.
What's new? ↑
Finally, we can move to part describing the new cool features we bring with relude
.
-
Safe analogue for list functions: use
viaNonEmpty
function to getMaybe a
.viaNonEmpty head :: [a] -> Maybe a
-
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")
). -
General fold functions:
foldMapA :: (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b
-
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 -> f x
After:
whenJust mbX $ \x -> f 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
. -
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
. -
StaticMap
andDynamicMap
type classes as a general interface forMap
-like data structures. -
evaluateWHNF
andevaluateNF
functions as clearer and lifted aliases forevaluate
andevaluate . force
. -
MonadFail
instance forEither
.
-
Convenient functions to work with
(Bounded a, Enum a)
types:universe :: (Bounded a, Enum a) => [a
: get all values of the type.inverseMap :: (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a
: convert functions likeshow
to parsers.
-
Nice helpers to deal with
newtype
s in a more pleasant way:ghci> newtype Foo = Foo Bool deriving Show ghci> under not (Foo True) Foo False
-
Functions to operate with
CallStack
:>>> foo :: HasCallStack => String; foo = ownName >>> foo "foo"
-
Foldable1
typeclass that contains generalized interface for folding non-empty structures likeNonEmpty
. -
Validation
data type as an alternative toEither
when you want to combine all errors.
Explore Extra
modules: Relude.Extra
Migration guide ↑
In order to replace default Prelude
with relude
you should start with instructions given in
get started section.
This section describes what you need to change to make your code compile with relude
.
-
Enable
-XOverloadedStrings
extension by default for your project. -
Since
head
,tail
,last
andinit
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
. There is theviaNonEmpty
function for this. And you can use it likeviaNonEmpty last l
.tail
isdrop 1
. It's almost never a good idea to usetail
fromPrelude
.
- Add
import qualified Relude.Unsafe as Unsafe
and replace function with qualified usage.
- Change
-
If you use
fromJust
or!!
you should use them fromimport qualified Relude.Unsafe as Unsafe
. -
If you use
foldr
orforM_
or similar for something likeMaybe a
orEither a b
it's recommended to 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 ()
-
-
Forget about
String
type.- 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
. - Use
(putStr[Ln]|readFile|writeFile|appendFile)[Text|LText|BS|LBS]
functions.
- Replace
-
Run
hlint
using.hlint.yaml
file fromrelude
package to cleanup code and imports.
For Developers ↑
Note, that we are using custom hlint
setting which are Relude
specific. To
keep it up to date don't forget to reflect your changes in this file. We are
using Dhall
to maintain the configurations. To use it follow the steps below.
First time:
$ cabal new-install dhall-json
Dhall 3.0.0 is required, so make sure that the previous command installed dhall-json >= 1.2.4.
To generate hlint
file:
$ dhall-to-yaml --omitNull <<< './hlint/hlint.dhall' > .hlint.yaml
Check that you have generated valid .hlint.yaml
file without parse errors:
$ hlint test/Spec.hs
See our blog post where we describe the details of the implementation for this solution:
Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY.