relude
Safe, performant, user-friendly and lightweight Haskell Standard Library
https://github.com/kowainik/relude
Version on this page: | 1.1.0.0 |
LTS Haskell 22.40: | 1.2.2.0 |
Stackage Nightly 2024-11-02: | 1.2.2.0 |
Latest on Hackage: | 1.2.2.0 |
relude-1.1.0.0@sha256:fe82b67d4560b9eff8d7dd12c5e1f786b25d52d64f7302ad82a3bbec9a0bd55e,11747
Module documentation for 1.1.0.0
- Relude
- Relude.Applicative
- Relude.Base
- Relude.Bool
- Relude.Container
- Relude.Debug
- Relude.DeepSeq
- Relude.Enum
- Relude.Exception
- Relude.Extra
- Relude.File
- Relude.Foldable
- Relude.Function
- Relude.Functor
- Relude.Lifted
- Relude.List
- Relude.Monad
- Relude.Monoid
- Relude.Nub
- Relude.Numeric
- Relude.Print
- Relude.String
- Relude.Unsafe
relude
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
overString
, use space-leaks-free functions (e.g. our custom performantsum
andproduct
), 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 ofrelude
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
andbytestring
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 toMonadIO
- No need to add
-
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. Anyone should be able to quickly migrate to
relude
. Only some basic familiarity with the common libraries liketext
andcontainers
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 withExtra.*
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. Withrelude
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
inbase
, it’s also calledfoo
inrelude
. 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
.
For guiding development principles behind relude
and comparison with
base
, check out the following talk:
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 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
.
When to use an alternative prelude?
[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:
- 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 defaultPrelude
.
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.
Get started
[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.
Mixins
[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:
- Makes all modules of
base
available exceptPrelude
. - Renames the
Relude
module inrelude
toPrelude
. - 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.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.
base-noprelude
[Back to the Table of Contents] ↑
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 ofbase-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 theRelude
module. Or maybe you want to add something fromRelude.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.
NoImplicitPrelude
[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
Difference from Prelude
[Back to the Table of Contents] ↑
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 the 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 due to 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 brought into scope
- See the What’s new? section for a detailed overview.
- New reexports
- See the Reexports section for a detailed overview.
Reexports
[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
.
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 tosortWith
, 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 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
andsecond
functions apply a function to the first and second part of aBifunctor
(fst
andsnd
for tuples,Left
andRight
forEither
).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.
containers & unordered-containers
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:
- Transformers:
State[T]
,Reader[T]
,ExceptT
,MaybeT
. - Classes:
MonadReader
,MonadState
.
Deepseq
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
.
What’s new?
[Back to the Table of Contents] ↑
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 :: 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 getMaybe 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
andsortNub
are O(n log n) versions ofnub
(which is quadratic), also,hashNub
andunstableNub
are almost O(n) versions ofnub
, andintNub
for fastInt
s nub. -
whenM
,unlessM
,ifM
,guardM
— monadic guard combinators, that work with anyMonad
, 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_
andforM_
for loops.for_ files $ \file -> do ...
-
andM
,allM
,anyM
,orM
are monadic versions of the corresponding functions frombase
. -
Conversions between
Either
andMaybe
, e.g.rightToMaybe
andmaybeToLeft
with clear semantics. -
using(Reader|State)[T]
functions as aliases forflip run(Reader|State)[T]
. -
One
type class for creating singleton containers (even monomorphic ones likeText
). -
evaluateWHNF
andevaluateNF
functions as clearer and lifted aliases forevaluate
andevaluate . force
. -
MonadFail
instance forEither
.
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 likeshow
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 likeNonEmpty
. -
StaticMap
andDynamicMap
type classes as a general interface forMap
-like data structures. -
And much more!
Explore Extra
modules: Relude.Extra
Migration guide
[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.
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 described below ways:- 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 the function with its qualified usage:Unsafe.head
.
- Change
-
If you use
fromJust
or!!
you should import them fromimport qualified Relude.Unsafe as Unsafe
. -
If you use
foldr
orforM_
or similar for something likeMaybe a
orEither 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(<>)
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 import theText.Show
module if you want to implementShow
instance manually. This can be done in the following way:
import qualified Text.Show
data MyType = ...
instance Show MyType where
show :: MyType -> String
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/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:
Comparison with other alternative preludes
[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.
Relude vs Protolude
[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 remove redundant imports or find hints on 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 with less effort, even though it is already not an easy task.- One significant difference:
head
inprotolude
returnsMaybe a
while inrelude
it works withNonEmpty
. relude
uses type-level features to provide better error messages on the difference fromPrelude
, and also to forbidelem
andnotElem
functions forSet
andHashSet
(becauseelem
fromFoldable
runs in O(n) time and you can accidentally useelem
fromFoldable
but withrelude
you can’t).- Protolude supports older GHC versions (from GHC 7.6.1) while
relude
only supports from GHC 8.2.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 scary in some places as a consequence and it is more difficult to add, remove or change things there. relude
has much better documentation:- High-level overview of internal module structure
- 100% Haddock coverage
- Every function has usage examples and all examples are tested with
doctest
(which also sometimes hard to do due to the 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 fewer dependencies and is slightly lighter because of that but still is very powerful and useful.relude
is opt-in oriented and has a notion ofExtra.*
modules that are not exported by default from theRelude
module. That means that we do not spoil the 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 is a straightforward process to make them accessible package-wide with thebase-noprelude
trick!
For Developers
[Back to the Table of Contents] ↑
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 (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:
Producing dependency graph
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
Updating license headers
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'
Changes
Changelog
relude
uses PVP Versioning.
The changelog is available on GitHub.
1.1.0.0 — Jun 9, 2022
-
#388: Support GHC-9.2.
-
#363: Remove the
Option
type, reexported fromData.Semigroup
(which was removed inbase-4.16
, GHC 9.2)Migration guide: Use
Maybe
instead ofOption
. -
#372: Warn on usages of
readFileText
,readFileLText
,readFile
andreadFile'
.NOTE: This is a breaking change if you build with
-Werror
and use the above functions. UsereadFileBS
/readFileLBS
instead to convert toText
/LText
/String
usingdecodeUtf8
and similar functions. -
#394: Support
hashable-1.4
. -
#408: Switch benchmarks from
criterion
totasty-bench
. -
#404: Fix condidion for
ordNubOn
,intNub
,intNubOn
export forRelude.Nub
module. Use min version ofcontainers-0.6.0
instead of min version of GHC8.4
. -
Minor documentation improvements and fixes.
1.0.0.1 — Mar 15, 2021
- Minor documentation changes.
1.0.0.0 — Mar 12, 2021
-
#353: Reexport most common modules from the following libraries:
containers
unordered-containers
text
bytestring
Now, when using
relude
, you don’t need to add these libraries to your.cabal
file to enjoy their main API. Try removing them from your.cabal
file after upgrading to this version ofrelude
to see if you still need them.To utilise this feature, update the
mixin
part of your package configuration (if you’re using the mixins approach) to the following:mixins: base hiding (Prelude) , relude (Relude as Prelude) , relude
-
#345: Support GHC-9.0.
-
Upgrade minor GHC versions to GHC-8.10.4 and GHC-8.8.4.
-
#268: Drop support of GHC-8.0.2.
-
#270: Standardise
universe
,universeNonEmpty
andinverseMap
functions that previously were introduced in theRelude.Extra.Enum
module.Relude.Enum
module created that is exported in the mainRelude
module by default.Migration guide: If you were using any of these functions you can now remove
Relude.Extra.Enum
from your imports and explicitmixins
section as they are available for you with theRelude
module. -
Remove the
Eq
constraint onuniverseNonEmpty
-
#269: Remove the
Relude.Extra.Validation
module.Migration guide: If you use
Relude.Extra.Validation
in you project you need to:-
Add
validation-selective
into thebuild-depends
section of your.cabal
file. -
Change imports of
Relude.Extra.Validation
toValidation
:-- Was: import Relude.Extra.Validation (Validation (..), ..) -- Became: import Validation (Validation (..), ..)
-
-
#346, #347: Reimplement
ordNub
throughnubOrd
fromcontainers
. AddordNubOn
,intNub
andintNubOn
functions. -
#327: Add
infinitely
as more strictly typedforever
. -
#311: Add
maybeAt
function — the non-operator version of!!?
with its arguments flipped. -
#314: Add lifted versions of functions to work with
Handle
:hFlush
hIsEOF
hSetBuffering
hGetBuffering
-
#305: Add lifted versions of functions to work with environment:
getArgs
lookupEnv
-
Add lifted version of the
readFile'
function. -
Reexport the
BufferMode
type frombase
. -
#309: Reexport
span
fromData.List
. -
#319: Implement
partitionWith
. -
#307: Add
foldr1
toFoldable1
. -
#316: Add
average
andaverage1
— efficient functions for finding average on foldable structures. -
#306: Add
maximumOn1
andminimumOn1
toFoldable1
. -
#301: Add
traceShowWith
toRelude.Debug
. -
Updates to
relude
-specific.hlint
rules.
Thanks @googleson78, @sushi-shi, @rektrex, @aleator, @mjgpy3, @dalpd, @Bodigrim for helping with this release!
0.7.0.0 — May 14, 2020
-
#253: Support GHC-8.10. Upgrade GHC-8.8 to 8.8.3.
-
Significant documentation improvements:
- Add high-level description to each reexported module.
- Add String Conversion Table.
- Add
NonEmpty
lists functions tables. - Add
@since
annotations. - Improve README.
- Inline some external reexports into explicit lists of exports.
- Rewrite top-level
cabal
description.
-
#234: Reexport
scanl1
,scanr1
,scanl'
fromData.List
. -
#256: Make
cycle
total function. -
#233: Add
etaReaderT
toRelude.Monad.Trans
to help with performance. -
#294: Add
atomicModifyIORef_
andatomicModifyIORef'_
. -
#293: Add
memptyIfFalse
andmemptyIfTrue
functions. -
Reexport
NonEmpty
functions fromRelude.List.NonEmpty
instead ofRelude.List.Reexport
. -
#239: Reexport more STM functions that work with
TMVar
fromRelude.Lifted.Concurrent
. -
#227: Create
Relude.Extra
module -
#228: Add
universeNonEmpty
function. -
#249: Breaking change: Fix infix of the
Relude.Extra.Lens
(^.)
operator. Change it toinfixl 8
. -
Reexport partial
read
fromRelude.Unsafe
for consistency. -
#244: Remove deprecated functions:
prec
,dupe
andmapBoth
.Migration rules:
prec
: useprev
insteaddupe
: usedup
insteadmapBoth
: usebimapBoth
instead
-
#246: Deprecate
Relude.Extra.Validation
in favour ofvalidation-selective
Migration rules: If you use
Relude.Extra.Validation
in you project you need to:-
Add
validation-selective
into thebuild-depends
section of your.cabal
file. -
Change imports of
Relude.Extra.Validation
toValidation
:-- Was: import Relude.Extra.Validation (Validation (..), ..) -- Became: import Validation (Validation (..), ..)
-
-
#196: Deprecate
mapToFst
andmapToSnd
. IntroducetoFst
andtoSnd
inRelude.Extra.Tuple
as shorter aliases formapToFst
. ImplementfmapToFst
andfmapToSnd
. Add more HLint rules forRelude.Extra.Tuple
functions.Migration rules:
- Replace
mapToFst
withtoFst
- Replace
mapToSnd
withtoSnd
- You can now use
fmapToFst
andfmapToSnd
instead of[f]map (mapToFst f)
and[f]map (mapToSnd f)
- Replace
-
#286: Breaking change:
readEither
is not polymorphic over the first argument anymore. Now it takesString
.Migration rules: Use one of the conversion function from the
Relude.String.Conversion
module to covert your old input value intoString
.For example, if you had
readEither @Text @Int myText
Now it should become:
readEither @Int (toString myText)
-
#281: Move
One
property tests fromdoctest
tohedgehog
. Significant test time boost. -
#264: Support Dhall-16.0.0 in HLint rules.
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
. -
#63: 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.