Universum

universum is a custom prelude used in @Serokell that has:

1. Excellent documentation: tutorial, migration guide from Prelude, Haddock with examples for (almost) every function, all examples are tested with doctest, documentation regarding internal module structure.
2. universum-specific HLint rules: .hlint.yaml
3. Focus on safety, convenience and efficiency.

What is this file about?

This README contains introduction to Universum and a tutorial on how to use it.

Structure of this tutorial

This tutorial has several parts:

1. Philosophy and motivation.
2. How to use universum.
3. Changes in Prelude (some gotchas).
4. Already known things that weren't in Prelude brought into scope.
5. New things added.
6. Migration guide from Prelude.

This is neither a tutorial on Haskell nor tutorial on each function contained in Universum. For detailed documentation of every function together with examples and usage, see Haddock documentation.

Why another custom Prelude? ↑

Motivation

At Serokell, we strive to be as productive as possible. That's why we are using Haskell. This choice of language implies that we're restricted to use Prelude: implicit import of basic functions, type classes and data types. Unfortunately, the default Prelude is considered to be not so good due to some historical reasons.

This is why we decided to use a better tool. Luckily, Haskell provides us with the ability to replace default Prelude with an alternative. All we had to do is to implement a new basic set of defaults. There already were plenty of preludes, so we didn't plan to implement everything from scratch. After some long, hot discussions, our team decided to base our custom prelude on protolude.

The next section explains why we've made this choice and what we are willing to do. This tutorial doesn't cover the differences from protolude. Instead, it explains how Universum is different from regular Prelude.

Main goals

While creating and maintaining a custom prelude, we are pursuing the following goals:

1. Avoid all partial functions. We like total and exception-free functions. You can still use some unsafe functions from Universum.Unsafe module, but they are not exported by default.
2. Use more efficient string representations. String type is crushingly inefficient. All our functions either try to be polymorphic over string type or use Text as the default string type. Because the community is evolving slowly, some libraries still use String type, so String type alias is still reexported. We recommend to avoid String as much as you can!
3. Try to not reinvent the wheel. We're not trying to rebuild whole type hierarchy from scratch, as it's done in classy-prelude. Instead, we reexport common and well-known things from base and some other libraries that are used in everyday production programming in Haskell.

   Note: well, we did end up inventing some new things.

4. Export more useful and commonly used functions. Things like liftIO, ReaderT type, MVar-related functions have unambiguous names, are used in almost every non-trivial project, and it's really tedious to import them manually every time.
5. Make changes only when there are enough good reasons to make these changes. We have a code modification policy which semi-formally describes pre-conditions for different types of changes.

Unlike protolude, we are:

1. Not trying to be as general as possible (thus we don't export much from GHC.Generics).
2. Not trying to maintain every version of ghc compiler (but at least the latest 3).
3. Trying to make writing production code easier (see enhancements and fixes).

How to use Universum ↑

Okay, enough philosophy. If you want to just start using universum and explore it with the help of compiler, set everything up according to the instructions below.

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

Then add the following import to your modules:

import Universum

If you're using Emacs and don't want to type import Universum manually every time, you can modify your configs a little bit.

If you want to get familiar with universum internal structure, you can just read top-level documentation for Universum module.

Gotchas ↑

• head, tail, last, init, foldl1, minimum and other were-partial functions work with NonEmpty a instead of [a].
• Safe analogue for head, foldl1, foldr1, minimum, maximum functions, for instance: safeHead :: [a] -> Maybe a.
• undefined triggers a compiler warning, which is probably not what you want. Either use throwIO, Except, error or bug.
• map is fmap now.
• Multiple sorting functions are available without imports:
  • 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 like sortWith, but more time-efficient if function is calculated slowly (though less space-efficient). So you should write sortOn length (would sort elements by length) but sortWith fst (would sort list of pairs by first element).
• Functions sum and product are strict now, which makes them more efficient.
• If you try to do something like putStrLn "hi", you'll get an error message if OverloadedStrings is enabled – it happens because the compiler doesn't know what type to infer for the string. Use putTextLn in this case.
• Since show doesn't come from Show anymore, you can't write Show instances easily. See migration guide for details.
• You can't call some Foldable methods over Maybe and some other types. Foldable generalization is useful but potentially error-prone. Instead we created our own fully compatible with Foldable Container type class but that restricts the usage of functions like length over Maybe, Either, Identity and tuples. We're also using GHC 8 feature of custom compile-time errors to produce more helpful messages.
• As a consequence of previous point, some functions like traverse_, forM_, sequenceA_, etc. are generalized over Container type classes.
• error takes Text.
• We are exporting a rewrite rule which replaces toString . toText :: Text -> Text with id. Note that this changes semantics in some corner cases.

Things that you were already using, but now you don't have to import them explicitly ↑

Commonly used libraries

First of all, we reexport some generally useful modules: Control.Applicative, Data.Traversable, Data.Monoid, Control.DeepSeq, Data.List, and lots of others. Just remove unneeded imports after importing Universum (GHC should tell you which ones).

Then, some commonly used types: Map/HashMap/IntMap, Set/HashSet/IntSet, Seq, Text and ByteString (as well as