relude: Custom prelude from Kowainik

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Goals

  1. Tutorial

  2. Migration guide from Prelude

  3. Haddock with examples for (almost) every function (all examples are tested with <code>doctest</code>)

  4. Documentation regarding internal module structure)

  5. relude-specific HLint rules: .hlint.yaml


[Skip to Readme]

Properties

Versions 0.1.0, 0.1.1, 0.2.0, 0.3.0, 0.4.0, 0.5.0, 0.5.0, 0.6.0.0, 0.7.0.0, 1.0.0.0, 1.0.0.1, 1.1.0.0, 1.2.0.0, 1.2.1.0
Change log CHANGELOG.md
Dependencies base (>=4.9 && <5), bytestring (>=0.10 && <0.11), containers (>=0.5.7 && <0.7), deepseq (>=1.4 && <1.5), ghc-prim (>=0.4.0.0 && <0.6), hashable (>=1.2 && <1.3), mtl (>=2.2 && <2.3), stm (>=2.4 && <2.6), text (>=1.2 && <1.3), transformers (>=0.5 && <0.6), unordered-containers (>=0.2.7 && <0.3) [details]
License MIT
Copyright 2016 Stephen Diehl, 2016-2018 Serokell, 2018-2019 Kowainik
Author Kowainik, Stephen Diehl, Serokell
Maintainer Kowainik <xrom.xkov@gmail.com>
Category Prelude
Home page https://github.com/kowainik/relude
Bug tracker https://github.com/kowainik/relude/issues
Source repo head: git clone git@github.com:kowainik/relude.git
Uploaded by shersh at 2019-03-18T02:01:24Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for relude-0.5.0

[back to package description]

Relude

Relude: cyclone logo Build Status Hackage Stackage LTS Stackage Nightly Hackage-Deps License: MIT

relude is a custom prelude, an alternative to default Prelude. relude tries to achieve the following goals:

  1. 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 from Relude.Unsafe module, but they are not exported by default.

  2. Type-safety. We like to make invalid states unrepresentable. And if it's possible to express this concept through the types then we will do it.

    Example:

    whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
    

    instead of

    whenNotNull :: Applicative f => [a] -> ([a] -> f ()) -> f ()
    
  3. Performance. Prefer Text over String, use spaceleak-free functions (like our custom sum and product), introduce {-# INLINE #-} and {-# SPECIALIZE #-} pragmas where appropriate.

  4. Minimalism (low number of dependencies). We don't force users of relude to stick to some specific lens or text formatting or logging library.

  5. Convenience (like lifted to MonadIO functions, more reexports). But we want to bring common types and functions (like containers and bytestring) into scope because they are used in almost every application anyways.

  6. Provide excellent documentation.

  7. User-friendliness. Ability to quickly migrate to relude if you're familiar with the common libraries like text and containers.

  8. Exploration. Experiment with new ideas and proposals without introducing breaking changes. relude uses the approach with Extra.* 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:

  1. Get started
  2. Difference from Prelude
  3. Reexports
  4. What's new?
  5. Migration guide
  6. Comparison with other alternative preludes
  7. 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.

Get started

If you want to start using relude in your project and explore it with the help of compiler, set everything up according to one of the instructions below.

base-noprelude

This is the recommended way to use custom prelude. It requires you to perform the following steps:

  1. Replace base dependency with corresponding version of base-noprelude in your .cabal file.
  2. Add a relude dependency to your .cabal file.
  3. Add the following Prelude module to your project (both to filesystem and to exposed-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.

  4. Optionally modify your Prelude to include more or less functions. Probably you want to hide something from Relude module. Or maybe you want to add something from Relude.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

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

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.

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:

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:

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

Need to import explicitly

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.

  1. Enable -XOverloadedStrings extension by default for your project.

  2. Since head, tail, last and init work for NonEmpty you should refactor your code in one of the multiple ways described below:

    1. Change [a] to NonEmpty a where it makes sense.
    2. 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.
    3. Add import qualified Relude.Unsafe as Unsafe and replace function with qualified usage.
  3. If you use fromJust or !! you should use them from import qualified Relude.Unsafe as Unsafe.

  4. If you use foldr or forM_ or similar for something like Maybe a or Either 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 ()
  5. Forget about String type.

    • 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.
  6. 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:

  1. Find the commit hash of the relude version you are using (can be found in releases).
  2. Run the command that downloads .hlint.yaml for that version.
  3. 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/55968311244690f5cc8b4484a37a63d988ea2ec4/.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:

  1. 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.
  2. 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.
  3. relude has custom HLint rules specific to it: you can use them to remove redundant imports or find hints how to use functions from relude. 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.
  4. relude has less dependencies and is slightly lighter because of that but still very powerful and useful.
  5. One minor difference: head in protolude returns Maybe a while in relude it works with NonEmpty.
  6. Minor feature: relude uses type-level magic to forbid elem and notElem functions for Set and HashSet (because elem from Foldable run in O(n) time and you can accidentally use elem from Foldable but with relude you can't).
  7. relude is opt-in oriented and has a notion of Extra.* modules that are not exported by default from the Relude module. So we don't spoil global namespace but still have a lot of useful features like polymorphic functions to work with every newtype, Enum/Bounded-related useful utilities, functions to take a name of any type as Text and much more. It's very easy to make them accessible package-wide with base-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 3.0.0 is required, so make sure that the previous command installed dhall-json >= 1.2.4.

To generate hlint file:

$ dhall-to-yaml --omitNull <<< './hlint/hlint.dhall' > .hlint.yaml

Check that you have generated valid .hlint.yaml file without parse errors:

$ hlint test/Spec.hs

See our blog post where we describe the details of the implementation for this solution:

Acknowledgement

Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY.