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
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:
No need to add containers, unordered-containers, text and
bytestring to dependencies in your .cabal file to use the
main API of these libraries
No need to import types like NonEmpty, Text, Set, Reader[T], MVar, STM
Functions like liftIO, fromMaybe, sortWith are available by default as well
IO actions are lifted to MonadIO
Excellent documentation.
Tutorial
Migration guide from Prelude
Haddock for every function with examples tested by
doctest
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:
Rewrite base from the ground up. With relude you don't need
to unlearn what you already knew, you can leverage existing
knowledge to achieve higher productivity.
Invent custom abstractions. Learning abstractions is hard, so
we do our best not to introduce new overwhelming concepts.
Rename common definitions. If something is called foo in
base, it's also called foo in relude. So, relude doesn't
rename any existing abstractions, but it may introduce a few new
ones, if their benefits outweigh learning curve.
This 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.
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.
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:
Increased entry threshold: you need to learn a different standard library.
relude tries to lower this threshold as much as possible: it comes with
the excellent documentation, no custom abstractions, and behavior is
changed only for a small subset of functions.
Extra dependencies: adding more libraries to dependencies increases build
times and maintenance burden.
relude depends only on the boot libraries (almost) which results in small
build time, follows PVP and cares about
backwards compatibility.
However, using an alternative prelude, specifically relude, has the following
advantages:
Increased code safety: no partial functions, no space-leak functions.
Increased productivity: no need to import common functions and data types,
more common idioms are provided.
Increased performance: some functions in relude are faster than in the
default Prelude.
Taking into consideration all the above points, we put together our
recommendations when to use relude:
When you develop an application (e.g. CLI tool, web-app). In that case,
greater productivity is more important than a low number of dependencies.
When writing a big framework. Some of them can be bigger than applications.
And when you may want to stay with the default standard:
When you write a small library that is supposed to be used by other people in
their projects.
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:
Makes all modules of base available except Prelude.
Renames the Relude module in relude to Prelude.
Additionally allows importing all other modules from relude
(extra modules and reexports from other libraries).
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.0libraryexposed-modules: Example
build-depends: base >=4.14&&<4.17
, relude ^>=1.1.0.0mixins: 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 the mixins
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 the stack repl at the moment. Please,
consider this before using this method of turning relude on in the project.
If having stack repl crucial for your workflow, see the following options of
how to use Relude in your project.
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:
modulePrelude
( moduleRelude
) whereimportRelude
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.
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:
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.
base
Multiple sorting functions are available for different use-cases:
sortBy :: (a -> a -> Ordering) -> [a] -> [a]: sorts a 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]: similar to sortWith, but more
time-efficient if function is calculated slowly (though less
space-efficient). So you should write sortOn length (would sort elements
by length) but sortWith 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 and
second part of a Bifunctor (fst and snd for tuples, Left and
Right 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.
The following types from these two packages are exported:
Maps: strict versions of Map, HashMap, IntMap.
Sets: Set, HashSet, IntSet.
Sequences: Seq.
text & bytestring
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.
transformers & mtl
The following parts of these two libraries are exported:
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.
Finally, let's move to part describing the new cool features we bring with
relude.
Available by default
Safe analogue for the list functions:
head::NonEmptya->a-- the first element of the listtail::NonEmptya-> [a] -- the list without the first elementlast::NonEmptya->a-- the last element of the listinit::NonEmptya-> [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]
Just1
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 Ints nub.
whenM, unlessM, ifM, guardM — monadic guard combinators, that work
with any Monad, e.g. whenM (doesFileExist "foo").
when(Just|Nothing|Left|Right|NotEmpty)[M][_] functions that
let you conditionally execute something.
Before:
case mbX ofNothing->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.
Extra bonuses
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:
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.
Code changes
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:
Change [a] to NonEmpty a where it makes sense.
Use functions which return Maybe. There is the viaNonEmpty function for this.
And you can use it like viaNonEmpty last l.
tail is drop 1. It's almost never a good idea to use tail from Prelude.
Add import qualified Relude.Unsafe as Unsafe and replace the function
with its qualified usage: Unsafe.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):
Replace (++) with (<>) for String-like types.
Use toText/toLText/toString functions to convert to Text/LazyText/String types.
Use encodeUtf8/decodeUtf8 to convert to/from ByteString.
Use (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:
Run hlint using .hlint.yaml file from relude package to cleanup code and imports.
Running HLint on CI
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:
Find the commit hash of the relude version you are using (can be found in releases).
Run the command that downloads .hlint.yaml for that version.
Run hlint using this file.
For the latest relude version, this can be achieved by executing the following
two commands on your CI:
客服电话
APP下载
官方微信
