relude
Custom prelude from Kowainik
https://github.com/kowainik/relude
Version on this page: | 0.6.0.0 |
LTS Haskell 22.39: | 1.2.2.0 |
Stackage Nightly 2024-10-31: | 1.2.2.0 |
Latest on Hackage: | 1.2.2.0 |
relude-0.6.0.0@sha256:094ad587b28fa8dcc78fd0fba8927b970e5e4a9bb10a3126c0ca32a7ee61f3ca,8681
Module documentation for 0.6.0.0
- Relude
relude
relude
is an alternative prelude library. If you find the default
Prelude
unsatisfying, despite its advantages, consider using relude
instead.
Below you can find key design principles behind relude
:
-
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 unrepresentable. And if it’s possible to express this concept through the types then we 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. If possible,relude
tries to depend only on boot libraries. Dependency graph ofrelude
can give you clearer picture. -
Convenience (e.g lifted to
MonadIO
functions, more reexports). Despite minimalism, 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 for every function with examples tested by
doctest
- Documentation on 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.
Structure of this tutorial
This tutorial has several parts:
- When to use an alternative prelude?
- Get started
- Difference from Prelude
- Reexports
- What’s new?
- Migration guide
- Comparison with other alternative preludes
- For developers
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.
When to use an alternative prelude? ↑
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 different set of available by default functions and data types.
Replacing default Prelude
from base
has the following disadvantages:
- Increased threshold entrance: you need to learn a different standard library.
relude
tries to lower this threshold as much as possible: excellent documentation, no custom abstractions, 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 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 provided.
- Increased performance: some functions in
relude
are faster than in defaultPrelude
.
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.
Get started ↑
If you want to start using relude
in your project and explore it with the help
of the compiler, set everything up according to one of the instructions below.
base-noprelude ↑
This is the recommended way to use custom prelude. It requires you to perform the following steps:
- Replace the
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.
Mixins ↑
You can use Cabal feature mixins
to replace the default Prelude
with Relude
without need to add extra dependencies or import Relude
manually each time.
See the following example:
NOTE: this requires Cabal version to be at least
2.2
cabal-version: 2.2
name: prelude-example
version: 0.0.0.0
library
exposed-modules: Example
build-depends: base >= 4.10 && < 4.13
, relude ^>= 0.4.0
mixins: base hiding (Prelude)
, relude (Relude as Prelude)
default-language: Haskell2010
If you want to be able to import Extra.*
modules when using mixins
approach,
you need to list those modules under mixins
field as well, like this:
mixins: base hiding (Prelude)
, relude (Relude as Prelude, Relude.Extra.Enum)
NoImplicitPrelude ↑
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
Add relude
as a dependency of your project. Then add the following import to
your modules:
import Relude
Difference from Prelude ↑
Main differences from Prelude
can be grouped into the following categories:
- Changed behavior of common functions
head
,tail
,last
,init
work withNonEmpty a
instead of[a]
.
lines
,unlines
,words
,unwords
work withText
instead ofString
.
show
is polymorphic over return type.- Functions
sum
andproduct
are strict now, which makes them more efficient. - You can’t call
elem
andnotElem
functions overSet
andHashSet
. These functions are forbidden for these two types because of the performance reasons. error
takesText
undefined
triggers a compiler warning, because you probably don’t want to leaveundefined
in your code. Either usethrowIO
,Except
,error
orbug
.
- Not reexported
read
lookup
for listslog
- Completely new functions are brougth into scope
- See What’s new? section for a detailed overview.
- New reexports
- See Reexports section for a detailed overview.
Reexports ↑
relude
reexports some parts of the following libraries:
If you want to clean up imports after switching to relude
, you can use
relude
-specific .hlint.yaml
configuration for this task.
base
Multiple sorting functions are available:
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).
readMaybe
and readEither
are like read
but total and give either Maybe
or Either
with parse error.
(&)
– reverse application. x & f & g
instead of g $ f $ x
is useful sometimes.
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.
containers & unordered-containers
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
.
text & bytestring
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.
transformers & mtl
The following parts of these two libraries are exported:
- Transformers:
State[T]
,Reader[T]
,ExceptT
,MaybeT
. - Classes:
MonadReader
,MonadState
,MonadError
.
Deepseq
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
.
Available by default
-
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
. -
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
-
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
. -
evaluateWHNF
andevaluateNF
functions as clearer and lifted aliases forevaluate
andevaluate . force
. -
MonadFail
instance forEither
.
Need to import explicitly
-
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. -
StaticMap
andDynamicMap
type classes as a general interface forMap
-like data structures.
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.
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
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. - 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
-
Since
show
doesn’t come fromShow
anymore, you need to exportText.Show
module if you want to implementShow
instance manually. This can be done like this:
import qualified Text.Show
- Run
hlint
using.hlint.yaml
file fromrelude
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:
curl https://raw.githubusercontent.com/kowainik/relude/v0.6.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 being used in Summoner.
Comparison with other alternative preludes ↑
There are quite a few libraries that can be used as alternative preludes in Haskell, let’s compare Relude with some of them.
Relude vs Protolude ↑
Protolude is one of the most popular alternative preludes. It’s also relatively small, but:
- Protolude supports older GHC versions (from GHC 7.6.1) while
relude
only supports from GHC 8.0.2. So if you aim ancient GHC versions,protolude
might be a better choice. But because of that it contains a lot of CPP, code is ugly in some places as a consequence and it’s more difficult to add, remove or change things there. relude
has much better documentation:- High-level overview of internal module structure
- 100% Haddock coverage
- Almost every function has usage examples and all examples are tested with
doctest
(which also sometimes hard to do because of multiple GHC versions support, but we try really hard) - Tutorial + migration guide from
Prelude
and just general description of the whole package and libraries it depends on.
relude
has custom HLint rules specific to it: you can use them to remove redundant imports or find hints how to use functions fromrelude
. Moreover, the HLint rules are generated using Dhall and there is a blog post about this technique. This allows to maintain HLint rules much easier because it’s already not an easy task.relude
has less dependencies and is slightly lighter because of that but still very powerful and useful.- One minor difference:
head
inprotolude
returnsMaybe a
while inrelude
it works withNonEmpty
. - Minor feature:
relude
uses type-level magic to forbidelem
andnotElem
functions forSet
andHashSet
(becauseelem
fromFoldable
run in O(n) time and you can accidentally useelem
fromFoldable
but withrelude
you can’t). relude
is opt-in oriented and has a notion ofExtra.*
modules that are not exported by default from theRelude
module. So we don’t spoil global namespace but still have a lot of useful features like polymorphic functions to work with everynewtype
,Enum/Bounded
-related useful utilities, functions to take a name of any type asText
and much more. It’s very easy to make them accessible package-wide withbase-noprelude
trick!
For Developers ↑
Generating .hlint.yaml
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 9.0.0 is required, so make sure that the previous command installed dhall-json >= 1.4.0.
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:
Changes
Changelog
relude
uses PVP Versioning.
The changelog is available on GitHub.
0.6.0.0 — Oct 30, 2019
-
#171: Add custom type errors to various functions and instances.
head
,tail
,last
,init
words
,unwords
,lines
,unlines
error
ToText
,ToLText
,ToString
instances for bytestringsFoldable1
instance for ordinary listsMonad
instance forValidation
-
#164: Reexport
ShortByteString
,toShort
/fromShort
functions. (by @vrom911) -
#168, #197: Improve documentation significantly (more and better examples, better wording). (by @chshersh, @vrom911, @Cmdv)
-
#167: Rename functions (and deprecate old versions):
prec
toprev
dupe
todup
-
#201: Implement
!!?
as a safe equivalent of!!
that returns aMaybe
. (by @kutyel) -
#203: Implement the
guarded
combinator. (by @JonathanLorimer) -
#174: Implement
bimapBoth
inRelude.Extra.Tuple
module, markmapBoth
as DEPRECATED. (by @astynax) -
#221: Improve documentation for the
Validation
module significantly. (by @chshersh) -
#176: Implement property-based tests for
Validation
laws. (by @astynax) -
#172: Add
Monoid
andSemigroup
instances for theValidation
type. (by @mauriciofierrom) -
#156: Implement helper type-level functions in
Relude.Extra.Type
. (by @TheMatten) -
#165: Re-export
GHC.Float.atan2
. (by @ethercrow) -
#155: Implement
foldlSC
— short-circuting list fold — inRelude.Extra.Foldable
. (by @josephcsible) -
#148: Migrate HLint rules to the latest Dhall spec. (by @vrom911)
-
#178: Made
die
be polymorphic in its return type. (by @ilyakooo0) -
#162, #189, #190, #191, #193, #194, #195: Various refactorings and code improvements:
- Breaking change: Reorder type parameters to
asumMap
- Implement
andM
,orM
,allM
, andanyM
in terms of&&^
and||^
- Use
foldr
instead of explicit recursion andtoList
- Use
mapToFst
instead ofzip
to improve list fusion ininverseMap
- Implement
foldMap1
forNonEmpty
in terms offoldr
- Use
$>
instead of*>
andpure
where possible - Implement
asumMap
andfoldMapA
by coercingfoldMap
- Return Failure early in
<*
and*>
too
(by @josephcsible)
- Breaking change: Reorder type parameters to
-
#187: Remove
tasty
andtasty-hedgehog
dependencies and their redundant imports. (by @dalpd)
0.5.0 — Mar 18, 2019
- #127:
Implement
Relude.Extra.Lens
module. - #125:
Moved many numerical functions and types in
Relude.Numeric
. ReexporttoIntegralSized
fromData.Bits
. AddintegerToBounded
andintegerToNatural
inRelude.Numeric
. - #121:
Reexport
Ap
fromData.Monoid
. Change definition offoldMapA
to useAp
. - #129:
Add
appliedTo
andchainedTo
as named versions of operators=<<
and<**>
. - #138:
Add
RealFloat
toRelude.Numeric
. - #144:
Add
traverseToSnd
and friends toRelude.Extra.Tuple
. - #140:
Improve text of custom compile-time error messages for
elem
functions. - #136:
Cover
Relude.Extra.*
modules with custom HLint rules. - #146:
Improve documentation for
Relude.File
file: be more explicit about system locale issues. - Improve documentation for
One
typeclass and add tests. - Support ghc-8.6.4 and ghc-8.4.4. Drop support for ghc-8.6.1 and ghc-8.4.3.
0.4.0 — Nov 6, 2018
- #70:
Reexport
Contravariant
for GHC >= 8.6.1. - #103:
Drop
utf8-string
dependency and improve performance of conversion functions. - #98:
Reexport
Bifoldable
related stuff frombase
. - #99:
Reexport
Bitraversable
related stuff frombase
. - #100:
Add
Relude.Extra.Validation
withValidation
data type. - #89:
Add
Relude.Extra.Type
module containing atypeName
function. - #92
Add
Relude.Extra.Tuple
module, containingdupe
,mapToFst
,mapToSnd
, andmapBoth
functions. - #97:
Add
(&&^)
and(||^)
operators. - #81:
Add
asumMap
toFoldable
functions. - #80:
Add hlint rules for
whenLeft
,whenLeftM
,whenRight
andwhenRightM
. - #79:
Add HLint rules for
One
typeclass. - Remove
openFile
andhClose
. - #83:
Make documentation for
nub
functions prettier. - #109: Use Dhall v3.0.0 for hlint file generation.
0.3.0
-
#41: Add
Foldable1
. -
#64: Remove
Print
typeclass. Addput[L]BS[Ln]
functions.trace
functions now takeString
as argument instead ofText
.Important: this is a breaking change. If you used polymorphic
putStrLn
you need to remove type application or switch to one of the monomorphic functions. Also, you can’t abstract overPrint
typeclass anymore. -
#66: Export
(>>>)
and(<<<)
fromControl.Category
. -
#59: Introduce
flap
function and its operator version??
. -
#64: Improve performance of functions from
Foldable1
. Addfoldl1'
function. -
Reexport
uncons
frombase
. -
Rewrite
die
implementation to usedie
frombase
. -
#19: Rewrite
.hlint.yaml
to Dhall. -
Move
stdin
- andstdout
-related functions to new moduleRelude.Lifted.Terminal
. -
#67: Add HLint rules for
put*
functions. -
#22:
readFile
,writeFile
andappendFile
now work withString
. Add lifted version ofhClose
. AddreadFile
,writeFile
andappendFile
alternatives forText
andByteString
. -
#61: Add
under2
andunderF2
functions toRelude.Extra.Newtype
. -
#60: Add
hoistMaybe
andhoistEither
functions.
0.2.0
- #43:
Implement
Relude.Extra.Newtype
module. - #46: Add a function that returns its own name.
- #48:
Export
<&>
frombase
. Also reexportfromLeft
andfromRight
frombase
where possible. - #49: Speed up and refactor property tests.
- #54:
Improve documentation.
Add more examples to documentation and more tests.
Reexport
withReader
andwithReaderT
. RemovesafeHead
. RenameRelude.List.Safe
toRelude.List.NonEmpty
.
0.1.1
- #44: Implement parser deriviation from pretty-printers.
0.1.0
- #7:
Remove
Container.Class.Container
. ExportFoldable
. - #2:
Remove
microlens
from dependencies. - #10:
Remove
VarArg
module. - #9:
Remove
safe-exceptions
from dependencies. ReexportException
andSomeException
fromControl.Exception
instead. - #11:
Remove
TypeOps
module andtype-operators
dependency. - #13:
Remove
list
,getContents
,interact
,getArgs
,note
functions. RemoveLifted.ST
module. RenameLifted.Env
toLifted.Exit
. - #16:
Rename
whenLeft
,whenRight
,whenLeftM
,whenRightM
towhenLeft_
andwhenRight_
,whenLeftM_
andwhenRightM_
. AddwhenLeft
,whenRight
,whenLeftM
,whenRightM
which return the value. - #18:
Add
LazyStrict
type class for conversions. map
is notfmap
anymore. Reexportmap
fromData.List
- #12:
Remove
liquid-haskell
support. - #20:
Add
viaNonEmpty
function. - #21:
Add
MonadFail
instance forEither
. - #17:
Add
foldMapA
andfoldMapM
functions. - #4:
Rename package to
Relude
. - #14:
Add
Relude.Extra.*
modules which are not exported by default but have useful functions. - #8:
Introduce
StaticMap
andDynamicMap
type classes as universal interface for Map-like structures.