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.
  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 work with NonEmpty a instead of [a].
  • Safe analogue for head function: 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.
  • 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.

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.

  • first and second functions apply a function to first/second part of a tuple (for tuples).
  • bimap takes two functions and applies them to first and second parts respectively.

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.

  • uncons splits a list at the first element.

  • ordNub and sortNub are O(n log n) versions of nub (which is quadratic) and hashNub and unstableNub are almost O(n) versions of nub.

  • (&) – reverse application. x & f & g instead of g $ f $ x is useful sometimes.

  • whenM, unlessM, ifM, guardM are available and do what you expect them to do (e.g. whenM (doesFileExist "foo")).

  • Very generalized version of concatMapM, too, is available and does what expected.

  • readMaybe and readEither are like read but total and give either Maybe or Either with parse error.

  • when(Just|Nothing|Left|Right|NotEmpty)[M][_] let you conditionally execute something. Before:

    case mbX of
        Nothing -> return ()
        Just x  -> ... x ...
    

    After:

    whenJust mbX $ \x ->
        ... x ...
    
  • for_ for loops. There’s also forM_ but for_ looks a bit nicer.

    for_ [1..10] $ \i -> do
        ...
    
  • andM, allM, anyM, orM are monadic version of corresponding functions from base.

  • Type operator $ for writing types like Maybe $ Either String $ Maybe Int.

  • Each type family. So this:

    f :: Each [Show, Read] [a, b] => a -> b -> String
    

    translates into this:

    f :: (Show a, Show b, Read a, Read b) => a -> b -> String
    
  • With type operator. So this:

    a :: With [Show, Read] a => a -> a
    

    translates into this:

    a :: (Show a, Read a) => a -> a
    
  • Variadic composition operator (...). So you can write:

    ghci> (show ... (+)) 1 2
    "3"
    ghci> show ... 5
    "5"
    ghci> (null ... zip5) [1] [2] [3] [] [5]
    True
    ghci> let process = map (+3) ... filter
    ghci> process even [1..5]
    [5,7]
    
  • Conversions between Either and Maybe like rightToMaybe and maybeToLeft with clear semantic.

  • using(Reader|State)[T] functions as aliases for flip run(Reader|State)[T].

  • One type class for creating singleton containers. Even monomorhpic ones like Text.

  • evaluateWHNF and evaluateNF functions as clearer and lifted aliases for evaluate and evaluate . force.

  • ToPairs type class for data types that can be converted to list of pairs (like Map or HashMap or IntMap).

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

Please submit a PR if you are using Universum!

λ
cardano-report-server
cardano-sl
importify
log-warper
orgstat
tintin
require
ariadne

Changes

Unreleased

1.5.0

  • Make error’s stacktrace exclude site of the error function itself.

  • #200: Implemented a lifted version of withFile and added hClose to Universum.Lifted.File as discussed previously in #186.

  • #204: Make trace non-polymorphic over text argument, add traceIdWith and traceShowIdWith.

  • #197 hPutStr, hPutStrLn and hPrint added to Universum.Print. The interface for the backing typeclass Universum.Print.Print changed. It was also moved to the internal module Universum.Print.Internal and should be considered unstable.

    Migration guide: The interface for the Print class should be considered internal and may be subject to sudden change. If you must implement your own instances, then import Universum.Print.Internal (be aware that there are name clashes in the functions from Universum.Print and Universum.Print.Internal)

  • #201 Generalized the type of Universum.Lifted.Env.die. Should not break existing code, apart from, perhaps, type inference.

1.4.0

  • #167: identity has been removed.

    Migration guide: use Universum.id instead.

  • #177: The mask_ reexport from safe-exceptions has been removed.

    Migration guide: use Control.Exception.Safe.mask_ from safe-exceptions instead.

  • #178: getArgs has been removed.

    Migration guide: use liftIO directly with System.Environment.getArgs from base.

  • #179: getContents and interact have been removed.

    Migration guide: use liftIO directly with Data.Text.Lazy.IO.getContents and Data.Text.Lazy.IO.interact, both from the text package.

  • #180: The Lifted.ST module has been removed.

    Migration guide: use liftIO directly with functions from Control.Monad.ST instead.

  • #181: list has removed.

1.3.0

  • #167: identity has been deprecated.

    Migration guide: use Universum.id instead.

  • #170: Remove ElementConstraint from the Container class.

    Migration guide: remove ElementConstraint from every instance and every type signature.

  • #174 The type-operators dependency has been removed.

  • #177: The mask_ reexport from safe-exceptions has been deprecated.

    Migration_guide: use Control.Exception.Safe.mask_ from safe-exceptions instead.

  • #178: getArgs has been deprecated. To be removed in a future version.

    Migration guide: use liftIO directly with System.Environment.getArgs from base.

  • #179: getContents and interact have been deprecated.

    Migration guide: use liftIO directly with Data.Text.Lazy.IO.getContents and Data.Text.Lazy.IO.interact, both from the text package.

  • #180: The Lifted.ST module has been deprecated. To be removed in a future version.

    Migration guide: use liftIO directly with functions from Control.Monad.ST instead.

  • #181: list has been deprecated. To be removed in a future version.

1.2.0

  • #159 Breaking change: Remove text-format dependency.

    Migration guide: import Buildable type class either from text-format or formatting or fmt library. There is no direct replacement for pretty and prettyL in popular libraries. You can define prettyL = Data.Text.Lazy.Builder.toLazyText . build and pretty = Data.Text.Lazy.toStrict . prettyL`.

  • #164: Don’t reexport log :: Floating a => a -> a.

1.1.1

  • #148: Add CODEOWNERS and contributing guide.
  • #135: Add documentation regarding internal module structure.
  • #113: Annotate at function from Unsafe module and ordNub function from Nub module with liquidhaskell.
  • #73: Add more examples to docs and fix warnings where possible.
  • Move reexport of NonEmpty to Universum.List module.

1.1.0

  • #144: Add Exc pattern synonym.
  • #60: Reexport Natural type from Numeric.Natura module.
  • #118: Reexport Type from Data.Kind module.
  • #130: Merge ToList and Container type classes into single type class Container.
  • #15: Add ?: function to Universum.Monad.Maybe.
  • #128: Add Unsafe module with unsafe functions to works with lists and Maybe.
  • #129: Reexport id.
  • #136: Change foldl' type back, add flipfoldl' instead.

1.0.4.1

  • #127: Fix doctest for text-1.2.3.

1.0.4

  • #53: Add doctest to universum. Also imporove and fix documentation.
  • #117: Drop the support of GHC-8.0.1.
  • #104: Reexport hashWithSalt from Data.Hashable.
  • #95: Reexport Compose from Data.Functor.Compose.
  • #124: Export methods of class Exception.

1.0.3

  • #114: Reexport more functions from safe-exceptions.

1.0.2

  • #91: Change argument order of foldl'.
  • #97: Add ToPairs type class with the ability to have list of pairs.

1.0.1

  • #100: Add bug function = impureThrow.

1.0.0

  • #90: Improve project structure.
  • #89: Add export of Universum.Nub module to Universum.
  • Add listToMaybe to Universum.Monad.Reexport.
  • #81: Make putText and putLText to be versions of putStr. Add putTextLn and putLTextLn – versions of putStrLn.
  • #5: Add safe versions of head, tail, init, last functions for NonEmpty list. Old head (which returns Maybe) is renamed to safeHead. Reexports from safe are removed.
  • Remove unsnoc (this function is very slow and shouldn’t be used).
  • #88: Add HasCallStack => to error and undefined functions.
  • #58: Make Element type family be associated type family. Remove {-# OVERLAPPABLE #-} instance for ToList and Container. Add default instances for basic types. Remove WrappedList newtype because it’s not needed anymore. Remove NontrivialContainer constraint alias.
  • #56: Make elem and notElem faster for Set and HashSet by introducing ElementConstraint associated type family.
  • Remove Unsafe module. Though, see issue #128 for disuccion regarding possible return of this module.

0.9.1

  • Change base version to be < 5.

0.9.0

  • #79: Import ‘(<>)’ from Semigroup, not Monoid.
  • Improve travis configartion.
  • #80: Rename Container to ToList, NontrivialContainer to Container. Keep NontrivialContainer as type alias.
  • Rename Containers module to Container.Class.
  • Move all container-related reexports from Universum to Container.Reexport.
  • Add default implementation of null function.
  • Add WrappedList newtype with instance of Container.
  • Improve compile time error messages for disallowed instances.

0.8.0

  • #83: Change the order of types in show and print functions.
  • Move string related reexports and functions to Conv module.
  • Rename Conv module to String.
  • Move print function to Print module.
  • #77: Add modify' function to export list.

0.7.1.1

  • #69: Document SuperComposition operator (...).

0.7.1

  • #68: Separate all ‘nub’ functions to Nub module, add sortNub and unstableNub there.
  • #54: Reorganize .cabal.
  • #21: Add benchmarks.
  • #65: Use TypeNats instead of TypeLits when possible.

0.7.0

  • #47: Reexport put and get for MonadState.
  • #48: Export boxed Vector type.
  • #49: Export IdentityT and runIdentityT.
  • #51: Add fromRight and fromLeft that behave like fromMaybe but for Either.
  • #52: Add maybeToMonoid :: Monoid m => Maybe m -> m.
  • Remove Symbol-related types for sure.
  • Return back seems to be useful function guardM removed in v0.3.
  • Add notElem for NonTrivialContainer.

0.6.1

  • Fixed version number bug (it had 4 numbers).

0.6.0.0

  • #62: Export exceptions-related functions from ‘safe-exceptions’.

0.5.1

  • Fix an infinite loop in decodeUtf8 from Text to ByteString.Lazy.

0.5

  • Export MonadTrans typeclass.
  • Remove Symbol-related exports from GHC.TypeLits.
  • Remove SrcLoc and Location reexports from GHC.ExecutionStack.
  • Add With type operator.
  • Add hashNub.
  • Export strict StateT instead of lazy.

0.4.3

  • Assign associativity and priority to (…), export typeclass itself.

0.4.2

  • #25: Add vararg functions composition operator (…).
  • Rewrite concatMapM & concatForM so that they allow traversed and returned-by-function container types differ.

0.4.1

  • Reexport sortWith from GHC.Exts.

0.4

  • Add haddock documentation with 100% coverage.
  • Rewrite README tutorial.
  • #37: Add generalized version of readEither.
  • #38: Add evaluateNF, evaluateNF_, evaluateWHNF, evaluateWHNF_.
  • #39: Add lifted versions of IORef functions.
  • Remove foreach
  • Reexport (&&&) from Control.Arrow.
  • Add lifted version of readTVarIO.
  • interact and getContents work with Lazy Text.
  • Reexport MaybeT, maybeToExceptT, exceptToMaybeT.

0.3

  • #28: Remove putByteString and putLByteString.
  • #29: Remove panic, FatalError and notImplemented. Rename NotImplemented into Undefined.
  • #32: Remove orAlt, orEmpty, liftAA2, eitherA, purer, <<*>>, traceIO, guardM, hush, tryIO, liftM', liftM2', applyN, guardedA, Bifunctor instances for tuples of length higher than 2. Generalize concatMapM, add concatForM and operator versions.
  • #35: Generalize andM, orM, allM, anyM over container type.

0.2.2

  • #33: Add ($) and Each type operators.

0.2.1

  • #24: Add whenNothing, whenNothing_, whenNothingM, whenNothingM_, whenLeft, whenLeftM, whenRight, whenRightM, whenNotNull, whenNotNullM.
  • #26: Add usingReader, usingReaderT, usingState, usingStateT, executingState, executingStateT, evaluatingState, evaluatingStateT.
  • Remove maybeToEither.

0.2

  • Add one (similar to singleton).
  • Expose Symbol and Nat types from GHC.TypeLits by default.
  • Export genericLength and other generic list return functions.
  • Rename msg to fatalErrorMessage.
  • Export ExceptT
  • Export ReaderT, and StateT constructors.
  • Export NonEmpty type and constructor for Base 4.9 only.
  • Export Data.Semigroup type and functions for Base 4.9 only.
  • Export String.

0.1.13

  • Add lenses from microlens.
  • Add (<&>).
  • Reexport (&) from Data.Function if it’s present there instead of always defining our own (this is actually done by reexporting it from Lens.Micro which does the right thing).
  • Fix a space leak in whenJust.

0.1.12

  • Use custom classes instead of Foldable. Thanks to this, length and similar functions can’t anymore be used on tuples or Maybe, but can be used on e.g. Text, ByteString and IntSet.

  • Add allM, anyM, andM, orM.

  • Reexport fail and MonadFail.

0.1.11

  • Expose putByteString and putLByteString monomorphic versions of putStrLn functions
  • Switch exported (<>) to be from Data.Monoid instead of Semigroup.
  • Export Hashable

0.1.10

  • Generalize most IO functions to MonadIO
  • Make die available for older versions of base

0.1.9

  • Make sum and product strict

0.1.8

  • foreach for applicative traversals.
  • hush function for error handling.
  • tryIO function for error handling.
  • pass function for noop applicative branches.
  • Mask Handler typeclass export.
  • Mask yield function export.

0.1.7

  • Export monadic (>>) operator by default.
  • Add traceId and traceShowId functions.
  • Exportreader and state functions by default.
  • Export lifted throwIO and throwTo functions.

0.1.6

  • Add uncatchable panic exception throwing using Text message.
  • Remove printf
  • Remove string-conv dependency so Stack build works without extra-deps.
  • Bring Callstack machinery in for GHC 8.x.
  • Remove throw and assert from Control.Exception exports.
  • Remove unsafeShiftL and unsafeShiftR from Data.Bits exports.
  • Reexport throw as unsafeThrow via Unsafe module.
  • Hides all Show class functions. Only the Class itself is exported. Forbids custom instances that are not GHC derived.
  • Export encodeUtf8 and decodeUtf8 functions by default.
  • Adds unsnoc function.

0.1.5

  • Initial release.