🌀 Safe, performant, user-friendly and lightweight Haskell standard library
MIT License
relude
is a safe, performant, user-friendly and lightweight Haskell
standard library.
The default Prelude
is not perfect and doesn't always satisfy one's needs.
At this stage you may want to try an alternative prelude library. In this README
we are going to give you convincing reasons to consider using relude
as such
alternative in your next project.
relude
has some strong goals and principles that it sticks to. That principles
defines the library decisions and might tell you more about the priorities of
the library. So below you can find the key design principles behind relude
:
Productivity. You can be more productive with a "non-standard" standard
library, and relude
helps you with writing safer and more
efficient code faster.
Total programming. Usage of
partial functions
can lead to unexpected bugs and runtime exceptions in pure
code. The types of partial functions lie about their behaviour. And
even if it is not always possible to rely only on total functions,
relude
strives to encourage best-practices and reduce the
chances of introducing a bug.
Partial | Total |
---|---|
head :: [a] -> a |
head :: NonEmpty a -> a |
tail :: [a] -> [a] |
tail :: NonEmpty a -> [a] |
read :: Read a => String -> a |
readMaybe :: Read a => String -> Maybe a |
fromJust :: Maybe a -> a |
fromMaybe :: a -> Maybe a -> a |
Type-safety. We use the "make invalid states unrepresentable" motto as one of our guiding principles. If it is possible, we express this concept through the types.
Example: Here the function's name type and actions are aligned with each other
whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
While in here, the type could represent an unreachable state:
whenNotNull :: Applicative f => [a] -> ([a] -> f ()) -> f ()
Performance. We prefer Text
over String
,
use space-leaks-free functions (e.g. our custom performant sum
and product
), introduce
{-# INLINE #-}
and {-# SPECIALIZE #-}
pragmas where
appropriate, and make efficient container types
(e.g. Map
, HashMap
, Set
) more accessible.
Minimalism (low number of dependencies). We do not force users of
relude
to stick to any specific lens or text formatting or logging
library. Where possible, relude
depends only on boot libraries.
The Dependency graph
of relude
can give you a clearer picture.
Convenience. Despite minimalism, we want to bring commonly used types and functions into scope, and make available functions easier to use. Some examples of conveniences:
containers
, unordered-containers
, text
andbytestring
to dependencies in your .cabal
file to use theNonEmpty
, Text
, Set
, Reader[T]
, MVar
, STM
liftIO
, fromMaybe
, sortWith
are available by default as wellIO
actions are lifted to MonadIO
Excellent documentation.
Prelude
doctest
relude
-specific HLint rules:.hlint.yaml
User-friendliness. Anyone should be able to quickly migrate to relude
. Only
some basic familiarity with the common libraries like text
and containers
should be enough (but not necessary).
Exploration. We have space to experiment with new ideas and proposals
without introducing breaking changes. relude
uses the approach with
Extra.*
modules which are not exported by default. The chosen approach makes it quite
easy for us to provide new functionality without breaking anything and let
the users decide to use it or not.
In addition to our key design principles, the following list of
anti-goals describes what relude
is trying to avoid:
base
from the ground up. With relude
you don't needfoo
inbase
, it's also called foo
in relude
. So, relude
doesn'tThis README contains an introduction to relude
and a tutorial on how to use it.
For a general introduction to alternative preludes, check the excellent
blog post by Type Classes that highlights
relude
.
For guiding development principles behind relude
and comparison with
base
, check out the following talk:
This tutorial has several parts:
This is neither a tutorial on Haskell Standard Library nor a tutorial on each
function contained in relude
. For latter see the detailed documentation of
every data type, type class and function together with examples and usages in
the Haddock documentation for relude
.
[Back to the Table of Contents] ↑
The module with the name Prelude
is a module imported by default in every Haskell
source file of your project. If you want to use some data types or functions
which are not exposed by Prelude
, you need to import them, adding necessary
libraries to your project dependencies. Unlike ordinary libraries, alternative
preludes provide a different set of available by default functions and data
types by replacing the Prelude
module.
Replacing default Prelude
from base
has the following disadvantages:
relude
tries to lower this threshold as much as possible: it comes withrelude
depends only on the boot libraries (almost) which results in smallHowever, using an alternative prelude, specifically relude
, has the following
advantages:
relude
are faster than in thePrelude
.Taking into consideration all the above points, we put together our
recommendations when to use relude
:
And when you may want to stay with the default standard:
[Back to the Table of Contents] ↑
If you want to start using relude
in your project, you can set the library up
for you by one of the following ways.
[Back to the Table of Contents] ↑
This is the recommended way to use a custom prelude.
You can use the Cabal feature mixins
to replace the default Prelude
with
Relude
without the need to add extra dependencies or to import Relude
manually in each module.
For this you need to add the following lines into your .cabal
file:
mixins: base hiding (Prelude)
, relude (Relude as Prelude)
, relude
NOTE: this requires Cabal version to be at least
2.2
The above syntax does the following:
base
available except Prelude
.Relude
module in relude
to Prelude
.relude
See the following complete example of how your .cabal
file may look
like after the set up:
cabal-version: 2.2
name: prelude-example
version: 0.0.0.0
library
exposed-modules: Example
build-depends: base >= 4.14 && < 4.17
, relude ^>= 1.1.0.0
mixins: base hiding (Prelude)
, relude (Relude as Prelude)
, relude
default-language: Haskell2010
NOTE: if you use
summoner
to generate a Haskell project, the tool automatically creates themixins
field when you specify a custom prelude.
If you want to restrict allowed modules in relude
to a specific list
(e.g. use only Relude.Extra.Enum
or Relude.Unsafe
or Data.Text
from text
), you can alternatively list them explicitly under the
first mixins
entry field as well, like this:
mixins: base hiding (Prelude)
, relude (Relude as Prelude
, Relude.Extra.Enum
, Relude.Unsafe
, Data.Text
)
If you want to bring only all Extra.*
modules into scope, you can add
a single Relude.Extra
module to mixins
, and after that you can import all
extra functions and data types from Relude.Extra
. This is the
easiest way to bring all functions and types from relude
to your project
(excluding Relude.Unsafe
).
mixins: base hiding (Prelude)
, relude (Relude as Prelude
, Relude.Extra
)
NOTE: due to the existing stack issue,
mixins
technique doesn't work with thestack repl
at the moment. Please, consider this before using this method of turningrelude
on in the project.If having
stack repl
crucial for your workflow, see the following options of how to use Relude in your project.
[Back to the Table of Contents] ↑
For this option, you need to disable the default Prelude
module first.
To disable the built-in prelude on module basis, you can add the following
pragma at the top of your file:
{-# LANGUAGE NoImplicitPrelude #-}
if you want to disable the default Prelude
for every module by default, you
can specify this directly in your project .cabal
file:
default-extensions: NoImplicitPrelude
Then you need to add relude
as a dependency of your project.
After doing all above, you can now use Relude
in any module of your project by
adding a single import:
import Relude
[Back to the Table of Contents] ↑
⚠️ This strategy is not reccommended. The package base-noprelude
is currently not being maintained and its use is likely to cause issues with newer versions of ghc and libraries.
Alternatively, you can use the base-noprelude
trick to enable
alternative preludes. This approach can be helpful if you want to have
your own Prelude
module with some custom functions, not provided by
relude
. To use the trick, perform the following steps:
Replace the base
dependency with the corresponding version of base-noprelude
in
your .cabal
file.
Add the relude
dependency to your .cabal
file.
Create the file called Prelude.hs
in your source directory with
the following content:
module Prelude
( module Relude
) where
import Relude
Add this module to exposed-modules
in your .cabal
file:
exposed-modules: Prelude
Optionally modify your Prelude
module to include more or fewer functions.
Potentially, you can hide something from the Relude
module. Or maybe you
want to add something from Relude.Extra.*
modules!
Customize the module for your needs.
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.
[Back to the Table of Contents] ↑
Main differences from Prelude
can be grouped into the following categories:
head
, tail
, last
, init
work with NonEmpty a
instead of [a]
.lines
, unlines
, words
, unwords
work with Text
instead of String
.show
is polymorphic over the return type.sum
and product
are strict now, which makes them more efficient.elem
and notElem
functions over Set
and HashSet
.error
takes Text
.undefined
triggers a compiler warning, because you probably don't want toundefined
in your code. Either use throwIO
, Except
, error
orbug
.read
lookup
for listslog
[Back to the Table of Contents] ↑
relude
reexports some parts of the following libraries:
If you want to clean up your imports after switching to relude
, you can use
the relude
-specific
.hlint.yaml
configuration for this task. With this config, HLint
will produce
warnings and hints on how to have more benefits from relude
.
Multiple sorting functions are available for different use-cases:
sortBy :: (a -> a -> Ordering) -> [a] -> [a]
: sorts a list using givensortWith :: Ord b => (a -> b) -> [a] -> [a]
: sorts a list based on somesortOn :: Ord b => (a -> b) -> [a] -> [a]
: similar to sortWith
, but moresortOn length
(would sort elementssortWith fst
(would sort list of pairs by first element).readMaybe
and readEither
are similar to read
but unlike it, they are total
and return either Maybe
or Either
with a parse error.
(&)
is the reverse application. The following three expressions are
semantically equivalent:
g (f x)
g $ f $ x
x & f & g
Some generally useful modules from base
package are exported, e.g.
Control.Applicative
, Data.Traversable
, Data.Monoid
, Data.List
,
and many more.
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
and second
functions apply a function to the first andBifunctor
(fst
and snd
for tuples, Left
andRight
for Either
).bimap
takes two functions and applies them to the first and second parts respectively.trace
, traceM
, traceShow
, etc. are available by default. However, GHC will
warn you if you accidentally leave them in code. Same goes for the undefined
function.
We also have data Undefined = Undefined
(which also comes with the warning).
relude
reexports Exception
type from the base
package and introduces the
bug
function as an alternative to error
. There is 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:
Map
, HashMap
, IntMap
.Set
, HashSet
, IntSet
.Seq
.relude
exports Text
and ByteString
(as well as their lazy versions —
LText
and LByteString
).
Also, some functions now work
with Text
instead of String
– words
, lines
, etc.
In addition, relude
provides specialised versions of the IO
functions to
work with Text
and ByteString
— readFileText
, writeFileBS
, etc.
show
is polymorphic and can produce strict or lazy Text
or
ByteString
as well as String
.
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:
State[T]
, Reader[T]
, ExceptT
, MaybeT
.MonadReader
, MonadState
.All the main parts of the deepseq
library are exported.
For instance, if you want to force the deep evaluation of
some value (in IO
), you can write evaluateNF a
.
Additionally, the WHNF evaluation is possible
with provided evaluateWHNF
.
[Back to the Table of Contents] ↑
Finally, let's move to part describing the new cool features we bring with
relude
.
Safe analogue for the list functions:
head :: NonEmpty a -> a -- the first element of the list
tail :: NonEmpty a -> [a] -- the list without the first element
last :: NonEmpty a -> a -- the last element of the list
init :: NonEmpty a -> [a] -- the list without the last element
You can also still work with lists for these functions. Using viaNonEmpty
function you will get Maybe a
from the list:
-- viaNonEmpty head :: [a] -> Maybe a
ghci> viaNonEmpty head [1,2,3]
Just 1
ghci> viaNonEmpty head []
Nothing
uncons
splits a list at the first element.
ordNub
and sortNub
are O(n log n) versions of nub
(which is quadratic),
also, hashNub
and unstableNub
are almost O(n) versions of nub
,
and intNub
for fast Int
s nub.
whenM
, unlessM
, ifM
, guardM
— monadic guard combinators, that work
with any Monad
, 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
when(Just|Nothing|Left|Right|NotEmpty)[M][_]
functions that
let you conditionally execute something.
Before:
case mbX of
Nothing -> return ()
Just x -> f x
After:
whenJust mbX $ \x ->
f x
for_
and forM_
for loops.
for_ files $ \file -> do
...
andM
, allM
, anyM
, orM
are monadic versions of the corresponding
functions from base
.
Conversions between Either
and Maybe
, e.g. rightToMaybe
and maybeToLeft
with clear semantics.
using(Reader|State)[T]
functions as aliases for flip run(Reader|State)[T]
.
One
type class
for creating singleton containers (even monomorphic ones like Text
).
evaluateWHNF
and evaluateNF
functions as clearer and lifted aliases for
evaluate
and evaluate . force
.
MonadFail
instance for Either
.
relude
has a number of Extra
modules that are not exposed by default (they
are not a part of the Relude
module). You need to import such modules
separately.
These extra modules include the following functionality:
Convenient functions to work with (Bounded a, Enum a)
types:
universe :: (Bounded a, Enum a) => [a]
: get all values of the type.
ghci> universe @Bool
[True,False]
inverseMap :: (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a
:
convert functions like show
to parsers:
readMyEnums :: Text -> Maybe MyEnum
readMyEnums = inverseMap myShow
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
:
ghci> foo :: HasCallStack => String; foo = ownName
ghci> foo
"foo"
Foldable1
typeclass that contains generalized interface for folding
non-empty structures like NonEmpty
.
StaticMap
and DynamicMap
type classes as a
general interface for Map
-like data structures.
And much more!
Explore Extra
modules: Relude.Extra
[Back to the Table of Contents] ↑
This section of the guide helps to migrate your project from base
to the relude
library.
In order to replace the default Prelude
with relude
you should start with
instructions provided in the 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
and init
work for NonEmpty
you should
refactor your code in one of the described below ways:
[a]
to NonEmpty a
where it makes sense.Maybe
. There is the viaNonEmpty
function for this.viaNonEmpty last l
.
tail
is drop 1
. It's almost never a good idea to use tail
from Prelude
.import qualified Relude.Unsafe as Unsafe
and replace the functionUnsafe.head
.If you use fromJust
or !!
you should import them from import qualified Relude.Unsafe as Unsafe
.
If you use foldr
or forM_
or similar for something like Maybe a
or
Either a b
it is recommended to replace usages of such functions with the
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 ()
Replace the String
type with more efficient and suitable ones (e.g. Text
):
(++)
with (<>)
for String
-like types.toText/toLText/toString
functions to convert to Text/LazyText/String
types.encodeUtf8/decodeUtf8
to convert to/from ByteString
.(putStr[Ln]|readFile|writeFile|appendFile)[Text|LText|BS|LBS]
functions.Since show
doesn't come from Show
anymore, you need to import the
Text.Show
module if you want to implement Show
instance manually. This can be done in the following way:
import qualified Text.Show
data MyType = ...
instance Show MyType where
show :: MyType -> String
show = ...
hlint
using .hlint.yaml
file from relude
package to cleanup code and imports.Instead of storing a relude
-specific .hlint.yaml
file inside your repository,
you can run HLint with this file automatically on any CI service such as
Travis CI or Circle CI.
For this you need to:
relude
version you are using (can be found in releases)..hlint.yaml
for that version.hlint
using this file.For the latest relude
version, this can be achieved by executing the following
two commands on your CI:
curl https://raw.githubusercontent.com/kowainik/relude/v1.1.0.0/.hlint.yaml -o .hlint-relude.yaml
curl -sSL https://raw.github.com/ndmitchell/neil/master/misc/travis.sh | sh -s -- hlint -h .hlint-relude.yaml .
See an example of this feature described in the following blog post about Travis CI settings:
[Back to the Table of Contents] ↑
There are quite a few libraries that can be used as alternative preludes in Haskell, let's compare Relude with some of them.
[Back to the Table of Contents] ↑
Protolude is one of the most popular alternative preludes. It's also relatively small, but:
relude
has custom HLint rules specific to it: you can use them to removerelude
. Moreover,head
in protolude
returns Maybe a
while inrelude
it works with NonEmpty
.relude
uses type-level features to provide better error messagesPrelude
, and also to forbid elem
and notElem
Set
and HashSet
(because elem
from Foldable
runs inelem
from Foldable
but withrelude
you can't).relude
onlyprotolude
relude
has much better documentation:
doctest
(which also sometimes hard to do due to the multiple GHCPrelude
and just general description of the whole package and librariesrelude
has fewer dependencies and is slightly lighter because of that but stillrelude
is opt-in oriented and has a notion of Extra.*
modules that areRelude
module. That means that we do notnewtype
, Enum/Bounded
-relatedText
and muchbase-noprelude
trick![Back to the Table of Contents] ↑
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 (lang version 22.0.0). To
use it follow the steps below.
First time:
$ cabal v2-install dhall-yaml-1.2.10
To generate hlint
file:
$ dhall-to-yaml-ng <<< './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:
Install cabal-plan
first:
$ cabal v2-install cabal-plan
$ cabal-plan --version
cabal-plan 0.6.2.0
Then draw the graph only for the library dependencies:
cabal-plan dot --root lib:relude | dot -Tpng -o relude-dependency-graph.png
Install the headroom
tool and run it from this repository:
cabal v2-install headroom-0.4.3.0
headroom run
rg "SPDX-License-Identifier : MPL-2.0" --files-with-matches src/ | xargs sed -i 's/SPDX-License-Identifier : MPL-2.0/SPDX-License-Identifier : MIT/g'