{"id":13617082,"url":"https://github.com/kowainik/relude","last_synced_at":"2025-05-14T05:10:20.734Z","repository":{"id":37998389,"uuid":"141514439","full_name":"kowainik/relude","owner":"kowainik","description":"🌀 Safe, performant, user-friendly and lightweight Haskell standard library","archived":false,"fork":false,"pushed_at":"2025-05-03T07:31:00.000Z","size":3520,"stargazers_count":712,"open_issues_count":16,"forks_count":81,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-07T01:55:15.296Z","etag":null,"topics":["alternative-prelude","haskell","prelude","safe","standard-library","user-friendly"],"latest_commit_sha":null,"homepage":"https://kowainik.github.io/projects/relude","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kowainik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"ko_fi":"kowainik","github":["vrom911"]}},"created_at":"2018-07-19T02:31:07.000Z","updated_at":"2025-04-06T03:09:31.000Z","dependencies_parsed_at":"2023-02-09T11:16:11.026Z","dependency_job_id":"5d47b8cf-d307-4bb0-9b83-90d54acf3e2d","html_url":"https://github.com/kowainik/relude","commit_stats":{"total_commits":644,"total_committers":70,"mean_commits":9.2,"dds":0.68944099378882,"last_synced_commit":"e633cb33308d259d6e4ea058ef506eb496b12323"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kowainik%2Frelude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kowainik%2Frelude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kowainik%2Frelude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kowainik%2Frelude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kowainik","download_url":"https://codeload.github.com/kowainik/relude/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076849,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alternative-prelude","haskell","prelude","safe","standard-library","user-friendly"],"created_at":"2024-08-01T20:01:36.769Z","updated_at":"2025-05-14T05:10:20.679Z","avatar_url":"https://github.com/kowainik.png","language":"Haskell","funding_links":["https://ko-fi.com/kowainik","https://github.com/sponsors/vrom911"],"categories":["Haskell"],"sub_categories":[],"readme":"# relude\n\n![Logo](https://user-images.githubusercontent.com/8126674/67678250-9d8eab80-f99f-11e9-96ca-27883ceeefa6.png)\n\n[![GitHub CI](https://github.com/kowainik/relude/workflows/CI/badge.svg)](https://github.com/kowainik/relude/actions)\n[![Hackage](https://img.shields.io/hackage/v/relude.svg?logo=haskell)](https://hackage.haskell.org/package/relude)\n[![Stackage LTS](http://stackage.org/package/relude/badge/lts)](http://stackage.org/lts/package/relude)\n[![Stackage Nightly](http://stackage.org/package/relude/badge/nightly)](http://stackage.org/nightly/package/relude)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**`relude`** is a safe, performant, user-friendly and lightweight Haskell\nstandard library.\n\nThe default `Prelude` is not perfect and doesn't always satisfy one's needs.\nAt this stage you may want to try an alternative prelude library. In this README\nwe are going to give you convincing reasons to consider using `relude` as such\nalternative in your next project.\n\n`relude` has some strong goals and principles that it sticks to. That principles\ndefines the library decisions and might tell you more about the priorities of\nthe library. So below you can find the key design principles behind `relude`:\n\n1. **Productivity.** You can be more productive with a \"non-standard\" standard\n   library, and `relude` helps you with writing safer and more\n   efficient code faster.\n\n2. **Total programming**. Usage of\n   [_partial functions_](https://www.reddit.com/r/haskell/comments/5n51u3/why_are_partial_functions_as_in_head_tail_bad/)\n   can lead to unexpected bugs and runtime exceptions in pure\n   code. The types of partial functions lie about their behaviour. And\n   even if it is not always possible to rely only on total functions,\n   `relude` strives to encourage best-practices and reduce the\n   chances of introducing a bug.\n\n| **Partial**                     | **Total**                                  |\n| ------------------------------- | ------------------------------------------ |\n| `head :: [a] -\u003e a`              | `head :: NonEmpty a -\u003e a`                  |\n| `tail :: [a] -\u003e [a]`            | `tail :: NonEmpty a -\u003e [a]`                |\n| `read :: Read a =\u003e String -\u003e a` | `readMaybe :: Read a =\u003e String -\u003e Maybe a` |\n| `fromJust :: Maybe a -\u003e a`      | `fromMaybe :: a -\u003e Maybe a -\u003e a`           |\n\n3. **Type-safety**. We use the _\"make invalid states unrepresentable\"_ motto as one\n   of our guiding principles. If it is possible, we express this concept through the\n   types.\n\n   _Example:_ Here the function's name type and actions are aligned with each other\n\n   ```haskell\n   whenNotNull :: Applicative f =\u003e [a] -\u003e (NonEmpty a -\u003e f ()) -\u003e f ()\n   ```\n\n   While in here, the type could represent an unreachable state:\n\n   ```haskell\n   whenNotNull :: Applicative f =\u003e [a] -\u003e ([a] -\u003e f ()) -\u003e f ()\n   ```\n\n4. **Performance.** We prefer `Text` over [`String`](https://www.reddit.com/r/haskell/comments/29jw0s/whats_wrong_with_string/),\n   use space-leaks-free functions (e.g. our custom performant `sum` and `product`), introduce\n   `{-# INLINE #-}` and `{-# SPECIALIZE #-}` pragmas where\n   appropriate, and make efficient container types\n   (e.g. `Map`, `HashMap`, `Set`) more accessible.\n\n5. **Minimalism** (low number of dependencies). We do not force users of\n   `relude` to stick to any specific lens or text formatting or logging\n   library. Where possible, `relude` depends only on boot libraries.\n   The [Dependency graph](https://raw.githubusercontent.com/kowainik/relude/main/relude-dependency-graph.png)\n   of `relude` can give you a clearer picture.\n\n6. **Convenience**. Despite minimalism, we want to bring commonly used\n   types and functions into scope, and make available functions easier\n   to use. Some examples of conveniences:\n\n   - No need to add `containers`, `unordered-containers`, `text` and\n     `bytestring` to dependencies in your `.cabal` file to use the\n     main API of these libraries\n   - No need to import types like `NonEmpty`, `Text`, `Set`, `Reader[T]`, `MVar`, `STM`\n   - Functions like `liftIO`, `fromMaybe`, `sortWith` are available by default as well\n   - `IO` actions are lifted to `MonadIO`\n\n7. **Excellent documentation.**\n\n   - Tutorial\n   - Migration guide from `Prelude`\n   - Haddock for every function with examples tested by\n     [`doctest`](http://hackage.haskell.org/package/doctest)\n   - Documentation on [internal module structure](http://hackage.haskell.org/package/relude/docs/Relude.html)\n   - `relude`-specific [HLint](http://hackage.haskell.org/package/hlint) rules:\n     [`.hlint.yaml`](https://github.com/kowainik/relude/blob/main/.hlint.yaml)\n\n8. **User-friendliness.** Anyone should be able to quickly migrate to `relude`. Only\n   some basic familiarity with the common libraries like `text` and `containers`\n   should be enough (but not necessary).\n\n9. **Exploration.** We have space to experiment with new ideas and proposals\n   without introducing breaking changes. `relude` uses the approach with\n   `Extra.*` modules which are not exported by default. The chosen approach makes it quite\n   easy for us to provide new functionality without breaking anything and let\n   the users decide to use it or not.\n\nIn addition to our key design principles, the following list of\n**anti-goals** describes what `relude` is trying to avoid:\n\n1. **Rewrite `base` from the ground up.** With `relude` you don't need\n   to unlearn what you already knew, you can leverage existing\n   knowledge to achieve higher productivity.\n2. **Invent custom abstractions.** Learning abstractions is hard, so\n   we do our best not to introduce new overwhelming concepts.\n3. **Rename common definitions.** If something is called `foo` in\n   `base`, it's also called `foo` in `relude`. So, `relude` doesn't\n   rename any existing abstractions, but it may introduce a few new\n   ones, if their benefits outweigh learning curve.\n\nThis README contains an introduction to `relude` and a tutorial on how to use it.\n\nFor a general introduction to alternative preludes, check the excellent\nblog post by [Type Classes](https://typeclasses.com/) that highlights\n`relude`.\n\n- [No implicit Prelude](https://typeclasses.com/ghc/no-implicit-prelude)\n\nFor guiding development principles behind `relude` and comparison with\n`base`, check out the following talk:\n\n- [![Introduction to `relude` — an alternative Haskell prelude](https://img.youtube.com/vi/qwAmiJ5M_zM/0.jpg)](https://www.youtube.com/watch?v=qwAmiJ5M_zM)\n\n## Structure of this tutorial\n\nThis tutorial has several parts:\n\n1. [When to use an alternative prelude?](#when-to-use-an-alternative-prelude)\n2. [Get started](#get-started)\n   - [Mixins](#mixins)\n   - [NoImplicitPrelude](#noimplicitprelude)\n   - [base-noprelude (not recommended)](#base-noprelude)\n3. [Difference from Prelude](#difference-from-prelude)\n4. [Reexports](#reexports)\n5. [What's new?](#whats-new)\n6. [Migration guide](#migration-guide)\n7. [Comparison with other alternative preludes](#comparison-with-other-alternative-preludes)\n   - [Relude vs Protolude](#relude-vs-protolude)\n8. [For developers](#for-developers)\n\nThis is neither a tutorial on _Haskell Standard Library_ nor a tutorial on each\nfunction contained in `relude`. For latter see the detailed documentation of\nevery data type, type class and function together with examples and usages in\nthe [_Haddock documentation for `relude`_](http://hackage.haskell.org/package/relude).\n\n## When to use an alternative prelude?\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nThe module with the name `Prelude` is a module imported by default in every Haskell\nsource file of your project. If you want to use some data types or functions\nwhich are not exposed by `Prelude`, you need to import them, adding necessary\nlibraries to your project dependencies. Unlike ordinary libraries, alternative\npreludes provide a different set of available by default functions and data\ntypes by replacing the `Prelude` module.\n\nReplacing default `Prelude` from `base` has the following _disadvantages_:\n\n1. Increased entry threshold: you need to _learn_ a different standard library.\n   - `relude` tries to lower this threshold as much as possible: it comes with\n     the excellent documentation, no custom abstractions, and behavior is\n     changed only for a small subset of functions.\n2. Extra dependencies: adding more libraries to dependencies increases build\n   times and maintenance burden.\n   - `relude` depends only on the boot libraries (almost) which results in small\n     build time, follows [PVP](https://pvp.haskell.org/) and cares about\n     backwards compatibility.\n\nHowever, using an alternative prelude, specifically `relude`, has the following\n**advantages**:\n\n1. Increased code safety: no partial functions, no space-leak functions.\n2. Increased productivity: no need to import common functions and data types,\n   more common idioms are provided.\n3. Increased performance: some functions in `relude` are faster than in the\n   default `Prelude`.\n\nTaking into consideration all the above points, we put together our\nrecommendations when to use `relude`:\n\n1. When you develop an application (e.g. CLI tool, web-app). In that case,\n   greater productivity is more important than a low number of dependencies.\n2. When writing a big framework. Some of them can be bigger than applications.\n\nAnd when you may want to stay with the default standard:\n\n1. When you write a small library that is supposed to be used by other people in\n   their projects.\n\n## Get started\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nIf you want to start using `relude` in your project, you can set the library up\nfor you by one of the following ways.\n\n### Mixins\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nThis is the recommended way to use a custom prelude.\n\nYou can use the Cabal feature `mixins` to replace the default `Prelude` with\n`Relude` without the need to add extra dependencies or to import `Relude`\nmanually in each module.\nFor this you need to add the following lines into your `.cabal` file:\n\n```haskell\n  mixins:   base hiding (Prelude)\n          , relude (Relude as Prelude)\n          , relude\n```\n\n\u003e **NOTE:** this requires Cabal version to be at least `2.2`\n\nThe above syntax does the following:\n\n1. Makes all modules of `base` available except `Prelude`.\n2. Renames the `Relude` module in `relude` to `Prelude`.\n3. Additionally allows importing all other modules from `relude`\n   (extra modules and reexports from other libraries).\n\nSee the following complete example of how your `.cabal` file may look\nlike after the set up:\n\n```cabal\ncabal-version:       2.2\nname:                prelude-example\nversion:             0.0.0.0\n\nlibrary\n  exposed-modules:     Example\n  build-depends:       base \u003e= 4.14 \u0026\u0026 \u003c 4.17\n                     , relude ^\u003e= 1.1.0.0\n\n  mixins:              base hiding (Prelude)\n                     , relude (Relude as Prelude)\n                     , relude\n\n  default-language:    Haskell2010\n```\n\n\u003e **NOTE:** if you use [`summoner`](https://github.com/kowainik/summoner) to\n\u003e generate a Haskell project, the tool automatically creates the `mixins`\n\u003e field when you specify a custom prelude.\n\nIf you want to restrict allowed modules in `relude` to a specific list\n(e.g. use only `Relude.Extra.Enum` or `Relude.Unsafe` or `Data.Text`\nfrom `text`), you can alternatively list them explicitly under the\nfirst `mixins` entry field as well, like this:\n\n```cabal\n  mixins: base hiding (Prelude)\n        , relude (Relude as Prelude\n                 , Relude.Extra.Enum\n                 , Relude.Unsafe\n                 , Data.Text\n                 )\n```\n\nIf you want to bring only all `Extra.*` modules into scope, you can add\na single `Relude.Extra` module to `mixins`, and after that you can import all\nextra functions and data types from `Relude.Extra`. This is the\neasiest way to bring all functions and types from `relude` to your project\n(excluding `Relude.Unsafe`).\n\n```cabal\n  mixins: base hiding (Prelude)\n        , relude (Relude as Prelude\n                 , Relude.Extra\n                 )\n```\n\n\u003e **NOTE:** due to the existing [stack issue](https://github.com/commercialhaskell/stack/issues/5077),\n\u003e `mixins` technique doesn't work with the `stack repl` at the moment. Please,\n\u003e consider this before using this method of turning `relude` on in the project.\n\u003e\n\u003e If having `stack repl` crucial for your workflow, see the following options of\n\u003e how to use Relude in your project.\n\n### NoImplicitPrelude\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nFor this option, you need to disable the default `Prelude` module first.\nTo disable the built-in prelude on module basis, you can add the following\npragma at the top of your file:\n\n```haskell\n{-# LANGUAGE NoImplicitPrelude #-}\n```\n\nif you want to disable the default `Prelude` for every module by default, you\ncan specify this directly in your project `.cabal` file:\n\n```haskell\ndefault-extensions: NoImplicitPrelude\n```\n\nThen you need to add `relude` as a dependency of your project.\n\nAfter doing all above, you can now use `Relude` in any module of your project by\nadding a single import:\n\n```haskell\nimport Relude\n```\n\n### base-noprelude\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\n:warning: _This strategy is not reccommended. The package `base-noprelude` is currently not being maintained and its use is likely to cause issues with newer versions of ghc and libraries._\n\nAlternatively, you can use the `base-noprelude` trick to enable\nalternative preludes. This approach can be helpful if you want to have\nyour own `Prelude` module with some custom functions, not provided by\n`relude`. To use the trick, perform the following steps:\n\n1. Replace the `base` dependency with the corresponding version of `base-noprelude` in\n   your `.cabal` file.\n2. Add the `relude` dependency to your `.cabal` file.\n3. Create the file called `Prelude.hs` in your source directory with\n   the following content:\n\n   ```haskell\n   module Prelude\n       ( module Relude\n       ) where\n\n   import Relude\n   ```\n\n4. Add this module to `exposed-modules` in your `.cabal` file:\n   ```cabal\n   exposed-modules: Prelude\n   ```\n5. Optionally modify your `Prelude` module to include more or fewer functions.\n   Potentially, you can hide something from the `Relude` module. Or maybe you\n   want to add something from `Relude.Extra.*` modules!\n   Customize the module for your needs.\n\nThis is a very convenient way to add a custom prelude to your project because\nyou don't need to import module manually inside each file and enable the\n`NoImplicitPrelude` extension.\n\n## Difference from Prelude\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nMain differences from `Prelude` can be grouped into the following categories:\n\n- Changed behavior of common functions\n  - `head`, `tail`, `last`, `init` work with `NonEmpty a` instead of `[a]`.\n  * `lines`, `unlines`, `words`, `unwords` work with `Text` instead of `String`.\n  - `show` is polymorphic over the return type.\n  - Functions `sum` and `product` are strict now, which makes them more efficient.\n  - You can't call `elem` and `notElem` functions over `Set` and `HashSet`.\n    These functions are forbidden for these two types due to performance reasons.\n  - `error` takes `Text`.\n  - `undefined` triggers a compiler warning, because you probably don't want to\n    leave `undefined` in your code. Either use `throwIO`, `Except`, `error` or\n    `bug`.\n- Not reexported\n  - `read`\n  - `lookup` for lists\n  - `log`\n- Completely new functions are brought into scope\n  - See the [What's new?](#whats-new) section for a detailed overview.\n- New reexports\n  - See the [Reexports](#reexports) section for a detailed overview.\n\n## Reexports\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\n`relude` reexports some parts of the following libraries:\n\n- [`base`](http://hackage.haskell.org/package/base)\n- [`bytestring`](http://hackage.haskell.org/package/bytestring)\n- [`containers`](http://hackage.haskell.org/package/containers)\n- [`deepseq`](http://hackage.haskell.org/package/deepseq)\n- [`ghc-prim`](http://hackage.haskell.org/package/ghc-prim)\n- [`hashable`](http://hackage.haskell.org/package/hashable)\n- [`mtl`](http://hackage.haskell.org/package/mtl)\n- [`stm`](http://hackage.haskell.org/package/stm)\n- [`text`](http://hackage.haskell.org/package/text)\n- [`transformers`](http://hackage.haskell.org/package/transformers)\n- [`unordered-containers`](http://hackage.haskell.org/package/unordered-containers)\n\nIf you want to clean up your imports after switching to `relude`, you can use\nthe `relude`-specific\n[`.hlint.yaml`](https://github.com/kowainik/relude/blob/main/.hlint.yaml)\nconfiguration for this task. With this config, `HLint` will produce\nwarnings and hints on how to have more benefits from `relude`.\n\n### base\n\nMultiple sorting functions are available for different use-cases:\n\n- `sortBy :: (a -\u003e a -\u003e Ordering) -\u003e [a] -\u003e [a]`: sorts a list using given\n  custom comparator.\n- `sortWith :: Ord b =\u003e (a -\u003e b) -\u003e [a] -\u003e [a]`: sorts a list based on some\n  property of its elements.\n- `sortOn :: Ord b =\u003e (a -\u003e b) -\u003e [a] -\u003e [a]`: similar to `sortWith`, but more\n  time-efficient if function is calculated slowly (though less\n  space-efficient). So you should write `sortOn length` (would sort elements\n  by length) but `sortWith fst` (would sort list of pairs by first element).\n\n`readMaybe` and `readEither` are similar to `read` but unlike it, they are total\nand return either `Maybe` or `Either` with a parse error.\n\n`(\u0026)` is the reverse application. The following three expressions are\nsemantically equivalent:\n\n- `g (f x)`\n- `g $ f $ x`\n- `x \u0026 f \u0026 g`\n\nSome generally useful modules from `base` package are exported, e.g.\n`Control.Applicative`, `Data.Traversable`, `Data.Monoid`, `Data.List`,\nand many more.\n\n`liftIO` and `MonadIO` are exported by default. A lot of `IO` functions are\ngeneralized to `MonadIO`.\n\n[`Bifunctor`](http://hackage.haskell.org/package/base/docs/Data-Bifunctor.html)\ntype class with useful instances is exported.\n\n- `first` and `second` functions apply a function to the first and\n  second part of a `Bifunctor` (`fst` and `snd` for tuples, `Left` and\n  `Right` for `Either`).\n- `bimap` takes two functions and applies them to the first and second parts respectively.\n\n`trace`, `traceM`, `traceShow`, etc. are available by default. However, GHC will\nwarn you if you accidentally leave them in code. Same goes for the `undefined`\nfunction.\n\nWe also have `data Undefined = Undefined` (which also comes with the warning).\n\n`relude` reexports `Exception` type from the `base` package and introduces the\n`bug` function as an alternative to `error`. There is also a very convenient\n`Exc` pattern-synonym to handle exceptions of different types.\n\nSee\n[`Relude.Exception`](http://hackage.haskell.org/package/relude/docs/Relude-Exception.html)\nmodule for details on exceptions.\n\n### containers \u0026 unordered-containers\n\nThe following types from these two packages are exported:\n\n- Maps: strict versions of `Map`, `HashMap`, `IntMap`.\n- Sets: `Set`, `HashSet`, `IntSet`.\n- Sequences: `Seq`.\n\n### text \u0026 bytestring\n\n`relude` exports `Text` and `ByteString` (as well as their lazy versions —\n`LText` and `LByteString`).\n\nAlso, some functions now work\nwith `Text` instead of `String` – `words`, `lines`, etc.\n\nIn addition, `relude` provides specialised versions of the `IO` functions to\nwork with `Text` and `ByteString` — `readFileText`, `writeFileBS`, etc.\n\n`show` is polymorphic and can produce strict or lazy `Text` or\n`ByteString` as well as `String`.\n\nAlso, `toText|toLText|toString` can convert `Text|LText|String` types to\n`Text|LText|String`. If you want to convert to and from `ByteString` use\n`encodeUtf8|decodeUtf8` functions.\n\n### transformers \u0026 mtl\n\nThe following parts of these two libraries are exported:\n\n- Transformers: `State[T]`, `Reader[T]`, `ExceptT`, `MaybeT`.\n- Classes: `MonadReader`, `MonadState`.\n\n### Deepseq\n\nAll the main parts of the `deepseq` library are exported.\nFor instance, if you want to force the deep evaluation of\nsome value (in `IO`), you can write `evaluateNF a`.\nAdditionally, the WHNF evaluation is possible\nwith provided `evaluateWHNF`.\n\n## What's new?\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nFinally, let's move to part describing the new cool features we bring with\n`relude`.\n\n### Available by default\n\n- Safe analogue for the list functions:\n\n  ```haskell\n  head :: NonEmpty a -\u003e a    -- the first element of the list\n  tail :: NonEmpty a -\u003e [a]  -- the list without the first element\n  last :: NonEmpty a -\u003e a    -- the last element of the list\n  init :: NonEmpty a -\u003e [a]  -- the list without the last element\n  ```\n\n  You can also still work with lists for these functions. Using `viaNonEmpty`\n  function you will get `Maybe a` from the list:\n\n  ```haskell\n  -- viaNonEmpty head :: [a] -\u003e Maybe a\n  ghci\u003e viaNonEmpty head [1,2,3]\n  Just 1\n  ghci\u003e viaNonEmpty head []\n  Nothing\n  ```\n\n- `uncons` splits a list at the first element.\n- `ordNub` and `sortNub` are _O(n log n)_ versions of `nub` (which is quadratic),\n  also, `hashNub` and `unstableNub` are almost _O(n)_ versions of `nub`,\n  and `intNub` for fast `Int`s nub.\n- `whenM`, `unlessM`, `ifM`, `guardM` — monadic guard combinators, that work\n  with any `Monad`, e.g. `whenM (doesFileExist \"foo\")`.\n- General fold functions:\n  ```haskell\n  foldMapA :: (Monoid b, Applicative m, Foldable f) =\u003e (a -\u003e m b) -\u003e f a -\u003e m b\n  foldMapM :: (Monoid b, Monad m, Foldable f) =\u003e (a -\u003e m b) -\u003e f a -\u003e m b\n  ```\n- `when(Just|Nothing|Left|Right|NotEmpty)[M][_]` functions that\n  let you conditionally execute something.\n\n  **Before:**\n\n  ```haskell\n  case mbX of\n      Nothing -\u003e return ()\n      Just x  -\u003e f x\n  ```\n\n  **After:**\n\n  ```haskell\n  whenJust mbX $ \\x -\u003e\n      f x\n  ```\n\n- `for_` and `forM_` for loops.\n\n  ```haskell\n  for_ files $ \\file -\u003e do\n      ...\n  ```\n\n- `andM`, `allM`, `anyM`, `orM` are monadic versions of the corresponding\n  functions from `base`.\n- Conversions between `Either` and `Maybe`, e.g. `rightToMaybe` and `maybeToLeft`\n  with clear semantics.\n- `using(Reader|State)[T]` functions as aliases for `flip run(Reader|State)[T]`.\n- [`One` type class](http://hackage.haskell.org/package/relude/docs/Relude-Container-One.html)\n  for creating singleton containers (even monomorphic ones like `Text`).\n- `evaluateWHNF` and `evaluateNF` functions as clearer and lifted aliases for\n  `evaluate` and `evaluate . force`.\n- `MonadFail` instance for `Either`.\n\n### Extra bonuses\n\n`relude` has a number of `Extra` modules that are not exposed by default (they\nare not a part of the `Relude` module). You need to import such modules\nseparately.\n\nThese extra modules include the following functionality:\n\n- Convenient functions to work with `(Bounded a, Enum a)` types:\n\n  1. `universe :: (Bounded a, Enum a) =\u003e [a]`: get all values of the type.\n\n     ```haskell\n     ghci\u003e universe @Bool\n     [True,False]\n     ```\n\n  2. `inverseMap :: (Bounded a, Enum a, Ord k) =\u003e (a -\u003e k) -\u003e k -\u003e Maybe a`:\n     convert functions like `show` to parsers:\n\n     ```haskell\n     readMyEnums :: Text -\u003e Maybe MyEnum\n     readMyEnums = inverseMap myShow\n     ```\n\n- Nice helpers to deal with `newtype`s in a more pleasant way:\n\n  ```haskell\n  ghci\u003e newtype Foo = Foo Bool deriving Show\n  ghci\u003e under not (Foo True)\n  Foo False\n  ```\n\n- Functions to operate with `CallStack`:\n\n  ```haskell\n  ghci\u003e foo :: HasCallStack =\u003e String; foo = ownName\n  ghci\u003e foo\n  \"foo\"\n  ```\n\n- `Foldable1` typeclass that contains generalized interface for folding\n  non-empty structures like `NonEmpty`.\n- [`StaticMap` and `DynamicMap` type classes](https://github.com/kowainik/relude/blob/main/src/Relude/Extra/Map.hs) as a\n  general interface for `Map`-like data structures.\n- And much more!\n\nExplore `Extra` modules: [`Relude.Extra`](http://hackage.haskell.org/package/relude/docs/Relude-Extra.html)\n\n## Migration guide\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nThis section of the guide helps to migrate your project from `base`\nto the `relude` library.\n\nIn order to replace the default `Prelude` with `relude` you should start with\ninstructions provided in the [_Get Started_](#get-started) section.\n\n### Code changes\n\nThis section describes what you need to change to make your code compile with `relude`.\n\n1. Enable `-XOverloadedStrings` extension by default for your project.\n2. Since `head`, `tail`, `last` and `init` work for `NonEmpty` you should\n   refactor your code in one of the described below ways:\n   1. Change `[a]` to `NonEmpty a` where it makes sense.\n   2. Use functions which return `Maybe`. There is the `viaNonEmpty` function for this.\n      And you can use it like `viaNonEmpty last l`.\n      - `tail` is `drop 1`. It's almost never a good idea to use `tail` from `Prelude`.\n   3. Add `import qualified Relude.Unsafe as Unsafe` and replace the function\n      with its qualified usage: `Unsafe.head`.\n3. If you use `fromJust` or `!!` you should import them from `import qualified Relude.Unsafe as Unsafe`.\n4. If you use `foldr` or `forM_` or similar for something like `Maybe a` or\n   `Either a b` it is recommended to replace usages of such functions with the\n   monomorhpic alternatives:\n\n   - `Maybe`\n\n     - `(?:)          :: Maybe a -\u003e a -\u003e a`\n     - `fromMaybe     :: a -\u003e Maybe a -\u003e a`\n     - `maybeToList   :: Maybe a -\u003e [a]`\n     - `maybeToMonoid :: Monoid m =\u003e Maybe m -\u003e m`\n     - `maybe         :: b -\u003e (a -\u003e b) -\u003e Maybe a -\u003e b`\n     - `whenJust      :: Applicative f =\u003e Maybe a -\u003e (a -\u003e f ()) -\u003e f ()`\n     - `whenJustM     :: Monad m =\u003e m (Maybe a) -\u003e (a -\u003e m ()) -\u003e m ()`\n\n   - `Either`\n     - `fromLeft    :: a -\u003e Either a b -\u003e a`\n     - `fromRight   :: b -\u003e Either a b -\u003e b`\n     - `either      :: (a -\u003e c) -\u003e (b -\u003e c) -\u003e Either a b -\u003e c`\n     - `whenRight_  :: Applicative f =\u003e Either l r -\u003e (r -\u003e f ()) -\u003e f ()`\n     - `whenRightM_ :: Monad m =\u003e m (Either l r) -\u003e (r -\u003e m ()) -\u003e m ()`\n\n5. Replace the `String` type with more efficient and suitable ones (e.g. `Text`):\n\n   - Replace `(++)` with `(\u003c\u003e)` for `String`-like types.\n   - Use `toText/toLText/toString` functions to convert to `Text/LazyText/String` types.\n   - Use `encodeUtf8/decodeUtf8` to convert to/from `ByteString`.\n   - Use `(putStr[Ln]|readFile|writeFile|appendFile)[Text|LText|BS|LBS]` functions.\n\n6. Since `show` doesn't come from `Show` anymore, you need to import the\n   `Text.Show` module if you want to implement `Show` instance manually. This can be done in the following way:\n\n```haskell\nimport qualified Text.Show\n\ndata MyType = ...\n\ninstance Show MyType where\n    show :: MyType -\u003e String\n    show = ...\n```\n\n7. Run `hlint` using `.hlint.yaml` file from `relude` package to cleanup code and imports.\n\n### Running HLint on CI\n\nInstead of storing a `relude`-specific `.hlint.yaml` file inside your repository,\nyou can run HLint with this file automatically on any CI service such as\n[Travis CI](https://travis-ci.org/) or [Circle CI](https://circleci.com/).\nFor this you need to:\n\n1. Find the commit hash of the `relude` version you are using (can be found in [releases](https://github.com/kowainik/relude/releases)).\n2. Run the command that downloads `.hlint.yaml` for that version.\n3. Run `hlint` using this file.\n\nFor the latest `relude` version, this can be achieved by executing the following\ntwo commands on your CI:\n\n```yaml\ncurl https://raw.githubusercontent.com/kowainik/relude/v1.1.0.0/.hlint.yaml -o .hlint-relude.yaml\ncurl -sSL https://raw.github.com/ndmitchell/neil/master/misc/travis.sh | sh -s -- hlint -h .hlint-relude.yaml .\n```\n\nSee an example of this feature described in the following blog post\nabout Travis CI settings:\n\n- [Kodimensional: Dead simple Haskell Travis settings for cabal and stack](https://kodimensional.dev/posts/2019-02-25-haskell-travis#customization-hlint)\n\n## Comparison with other alternative preludes\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\nThere are quite a few libraries that can be used as alternative preludes in\nHaskell, let's compare Relude with some of them.\n\n### Relude vs Protolude\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\n[Protolude](https://github.com/sdiehl/protolude) is one of the most popular\nalternative preludes. It's also relatively small, but:\n\n1. `relude` has custom HLint rules specific to it: you can use them to remove\n   redundant imports or find hints on how to use functions from `relude`. Moreover,\n   the HLint rules are generated using Dhall and there is [a blog post about\n   this technique](https://kowainik.github.io/posts/2018-09-09-dhall-to-hlint).\n   This allows to maintain HLint rules with less effort, even though it is\n   already not an easy task.\n2. One significant difference: `head` in `protolude` returns `Maybe a` while in\n   `relude` it works with `NonEmpty`.\n3. `relude` uses type-level features to provide better error messages\n   on the difference from `Prelude`, and also to forbid `elem` and `notElem`\n   functions for `Set` and `HashSet` (because `elem` from `Foldable` runs in\n   _O(n)_ time and you can accidentally use `elem` from `Foldable` but with\n   `relude` you can't).\n4. Protolude supports older GHC versions (from GHC 7.6.1) while `relude` only\n   supports from GHC 8.4. So if you aim ancient GHC versions, `protolude`\n   might be a better choice. But because of that it contains a lot of CPP, code\n   is scary in some places as a consequence and it is more difficult to add,\n   remove or change things there.\n5. `relude` has much better documentation:\n   - [High-level overview of internal module structure](http://hackage.haskell.org/package/relude/docs/Relude.html)\n   - 100% Haddock coverage\n   - Every function has usage examples and all examples are tested with\n     `doctest` (which also sometimes hard to do due to the multiple GHC\n     versions support, but we try really hard)\n   - [Tutorial + migration guide](#structure-of-this-tutorial) from\n     `Prelude` and just general description of the whole package and libraries\n     it depends on.\n6. `relude` has fewer dependencies and is slightly lighter because of that but still\n   is very powerful and useful.\n7. `relude` is opt-in oriented and has a notion of `Extra.*` modules that are\n   not exported by default from the `Relude` module. That means that we do not\n   spoil the global namespace but still have a lot of useful features, like\n   polymorphic functions to work with every `newtype`, `Enum/Bounded`-related\n   useful utilities, functions to take a name of any type as `Text` and much\n   more. It is a straightforward process to make them accessible package-wide\n   with the `base-noprelude` trick!\n\n## For Developers\n\n[[Back to the Table of Contents] ↑](#structure-of-this-tutorial)\n\n### Generating .hlint.yaml\n\nNote, that we are using custom `hlint` setting which are `Relude` specific. To\nkeep it up to date don't forget to reflect your changes in this file. We are\nusing `Dhall` to maintain the configurations (lang version 22.0.0). To\nuse it follow the steps below.\n\nFirst time:\n\n```shell\n$ cabal v2-install dhall-yaml-1.2.10\n```\n\nTo generate `hlint` file:\n\n```shell\n$ dhall-to-yaml-ng \u003c\u003c\u003c './hlint/hlint.dhall' \u003e .hlint.yaml\n```\n\nCheck that you have generated valid `.hlint.yaml` file without parse errors:\n\n```shell\n$ hlint test/Spec.hs\n```\n\nSee our blog post where we describe the details of the implementation for this solution:\n\n- [Dhall To HLint](https://kowainik.github.io/posts/2018-09-09-dhall-to-hlint)\n\n### Producing dependency graph\n\nInstall `cabal-plan` first:\n\n```shell\n$ cabal v2-install cabal-plan\n$ cabal-plan --version\ncabal-plan 0.6.2.0\n```\n\nThen draw the graph only for the library dependencies:\n\n```shell\ncabal-plan dot --root lib:relude | dot -Tpng -o relude-dependency-graph.png\n```\n\n### Updating license headers\n\nInstall the `headroom` tool and run it from this repository:\n\n```shell\ncabal v2-install headroom-0.4.3.0\nheadroom run\nrg \"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'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkowainik%2Frelude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkowainik%2Frelude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkowainik%2Frelude/lists"}