universum: Custom prelude used in Serokell

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]

See README.md file for more details.


[Skip to Readme]

Properties

Versions 0.1.8, 0.1.12, 0.2, 0.2.1, 0.2.2, 0.3, 0.4, 0.4.1, 0.4.2, 0.4.3, 0.5, 0.5.1, 0.5.1.1, 0.6.0.0, 0.6.1, 0.7.0, 0.7.1, 0.7.1.1, 0.8.0, 0.9.0, 0.9.1, 0.9.2, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.4.1, 1.1.0, 1.1.1, 1.2.0, 1.2.0, 1.3.0, 1.4.0, 1.5.0, 1.6.0, 1.6.1, 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.8.0, 1.8.1, 1.8.1.1, 1.8.2, 1.8.2.1, 1.8.2.2
Change log CHANGES.md
Dependencies base (>=4.8 && <5), bytestring, containers, deepseq, ghc-prim (>=0.4.0.0), hashable, microlens, microlens-mtl, mtl, safe-exceptions, stm, text, transformers, type-operators, unordered-containers, utf8-string, vector [details]
License MIT
Copyright 2016 Stephen Diehl, 2016-2018 Serokell
Author Stephen Diehl, @serokell
Maintainer Serokell <hi@serokell.io>
Category Prelude
Home page https://github.com/serokell/universum
Bug tracker https://github.com/serokell/universum/issues
Source repo head: git clone git@github.com:serokell/universum.git
Uploaded by shersh at 2018-05-02T17:37:00Z

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for universum-1.2.0

[back to package description]

Universum

Build Status Windows build status Hackage Stackage LTS Stackage Nightly License: MIT

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, documenation regarding internal module structure.
  2. universum-specific HLint rules: .hlint.yaml
  3. Only a few LiquidHaskell properties right now, but LiquidHaskell is on Travis CI and other properties are just waiting to be added!
  4. 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. If you're not familiar with it, you can read a tutorial about 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. Hello, my name is Dmitry. I was coding Haskell for 3 years but still hoogling which module liftIO comes from. 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.

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 (only 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

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 synonyms LText and LByteString for lazy versions).

liftIO and MonadIO are exported by default. A lot of IO functions are generalized to MonadIO.

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.

We also reexport big chunks of these libraries: mtl, stm, microlens, microlens-mtl.

Bifunctor type class with useful instances is exported.

Text

We export Text and LText, 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.

Debugging and undefineds

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).

Exceptions

We use safe-exceptions library for exceptions handling. Don't import Control.Exceptions module explicitly. Instead use functionality from safe-exceptions provided by universum or import Control.Exceptions.Safe module.

What's new?

Finally, we can move to part describing the new cool features we bring with universum.

Migration guide from Prelude

In order to replace default Prelude with universum you should start with instructions given in how to use universum section.

This section describes what you need to change to make your code compile with universum.

  1. Enable -XOverloadedStrings and -XTypeFamilies 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. They can be implemented using nonEmpty function. Like head <$> nonEmpty l.
      • head <$> nonEmpty l is safeHead l
      • tail is drop 1. It's almost never a good idea to use tail from Prelude.
    3. Add import qualified Universum.Unsafe as Unsafe and replace function with qualified usage.
  3. If you use fromJust or !! you should use them from import qualified Universum.Unsafe as Unsafe.

  4. Derive or implement Container instances for your data types which implement Foldable instances. This can be done in a single line because Container type class automatically derives from Foldable.

  5. Container type class from universum replaces Foldable and doesn't have instances for Maybe a, (a, b), Identity a and Either a b. If you use foldr or forM_ or similar for something like Maybe a you should 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 ()
  6. If you have types like foo :: Foldable f => f a -> a -> a you should chose one of the following:

    • Right: Modify types for Container like foo :: (Container t, Element t ~ a) => t -> a -> a.
    • Left: Import Data.Foldable module qualified and use everything Foldable-related qualified.
  7. Forget about String type.

    • Replace putStr and putStrLn with putText and putTextLn.
    • Replace (++) with (<>) for String-like types.
    • Try to use fmt library if you need to construct messages.
    • Use toText/toLText/toString functions to convert to Text/LazyText/String types.
    • Use encodeUtf8/decodeUtf8 to convert to/from ByteString.
  8. Run hlint using .hlint.yaml file from universum package to cleanup code and imports.

Projects that use Universum