• Stars
    star
    176
  • Rank 216,987 (Top 5 %)
  • Language
    Haskell
  • License
    MIT License
  • Created over 8 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🌌 Prelude written in @Serokell

Universum

GitHub CI 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, 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. 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, 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 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, minimum and some other functions 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.

  9. Since vanilla show from the Show class is not available, your custom Show instances will fail to compile. You can import qualified Text.Show to bring vanilla show to scope with qualified name. It will not conflict with show from universum and your Show instances will compile successfully.

More Repositories

1

deploy-rs

A simple multi-profile Nix-flake deploy tool.
Rust
1,358
star
2

importify

πŸ‘Ύ Importi.fy β€” it's like Uber, but for Haskell modules.
Haskell
105
star
3

nix-npm-buildpackage

Build nix packages that use npm/yarn
Nix
101
star
4

vault-secrets

NixOS tooling for Hashicorp Vault
Nix
71
star
5

tezos-packaging

Various forms of Tezos software distribution for Linux and macOS.
Python
60
star
6

haskell-with-utf8

Get your IO right on the first try
Haskell
52
star
7

xrefcheck

Check cross-references in repository documents
Haskell
51
star
8

o-clock

βŒ› Type-safe time units in Haskell
Haskell
49
star
9

nix-templates

Nix Flake templates for various languages
Nix
48
star
10

serokell-util

Various functions which are used across multiple @serokell packages
Haskell
44
star
11

ariadne

An open source Ada wallet for users who need more
Haskell
40
star
12

systemd-nix

Generate systemd units from NixOS-style descriptions
Nix
38
star
13

servant-util

Servant servers utilities
Haskell
34
star
14

foundry

Morte IDE
Haskell
28
star
15

update-daemon

Nix Flake Update daemon
Rust
25
star
16

serokell.nix

Serokell Nix infrastructure library
Nix
24
star
17

hackage-search

An application that lets you search for anything on Hackage
Haskell
24
star
18

ghc.dev

The https://ghc.dev Website Generator
Haskell
21
star
19

hse-haskell-course-src

Haskell course in the Higher School of Economics
TeX
21
star
20

log-warper

Logging library to provide more convenient, extremely configurable but simple monadic interface with pretty output
Haskell
19
star
21

nixcon2020-talk

NixCon 2020 talk about Nix flakes
Lua
18
star
22

time-warp

Distributed systems execution emulation
Haskell
18
star
23

notion-to-markdown

Export your Notion.so page as markdown
Python
17
star
24

blog-posts

The place for submitting new articles to the Serokell blog.
Haskell
16
star
25

gemini-infra

Internal Services Cluster
Nix
16
star
26

nix-pandoc

An expression to build Pandoc documents with Nix
Nix
16
star
27

haskell-crypto

Haskell cryptography done right
Haskell
15
star
28

fift-asm-dsl

A Haskell eDSL for the TON VM Assembler
Haskell
14
star
29

deploy

(WIP) Simple deploy of multi-profile systems using flakes
Shell
13
star
30

edna

An open-source tool for data analysis aimed to help researchers with their experiments.
Haskell
13
star
31

avl-plus

AVL+ tree
Haskell
12
star
32

style

Collection of programming style guides used in Serokell
12
star
33

cardano-sl

Cryptographic currency implementing Ouroboros PoS protocol
Haskell
12
star
34

upload-daemon

A daemon that asynchronously copies paths to a remote store.
Haskell
11
star
35

blockchain-util

Haskell
10
star
36

private-tezos-blockchain

Scripts for running private Tezos blockchain
Shell
10
star
37

qtah

Qt bindings for Haskell.
Haskell
9
star
38

rscoin

Moved to https://github.com/input-output-hk/rscoin-haskell
9
star
39

mix-to-nix

Generate sandbox buildable Nix expression from Mix lock file
Nix
9
star
40

tzbot

Timezone bot for Slack
Haskell
7
star
41

derivery

Continuous integration and delivery hook for Nix projects
Erlang
7
star
42

tztime

Safe timezone-aware handling of time
Haskell
6
star
43

github-app

Haskell API for authenticating as a GitHub App
Haskell
6
star
44

lootbox

Toolbox for your cool project
Haskell
6
star
45

xrefcheck-action

GitHub action for xrefcheck
Shell
6
star
46

opam-nix

A handy nix library to package OCaml software from OPAM repositories
Haskell
5
star
47

stack-to-nix

Generate sandbox buildable Nix expression from Stack file
Nix
5
star
48

GPLVMHaskell

Gaussian Process Latent Variable Models implemented in Haskell
Haskell
4
star
49

hermetic

Slack bot that links to YouTrack issues
Elixir
4
star
50

coffer

Multi-backend password store with multiple frontends
Haskell
4
star
51

time-warp-nt

Moved to https://github.com/input-output-hk/cardano-sl/tree/master/networking
4
star
52

nyan-interpolation

Flexible and extensible interpolation for Haskell
Haskell
4
star
53

gui-haskell-app

An example of making a GUI app in Haskell
Haskell
4
star
54

pegasus-infra

Web App Cluster
Nix
4
star
55

aeson-options

Various options to configure field and constructor names in JSON
Haskell
4
star
56

srk-nixpkgs

Moved to https://github.com/input-output-hk/iohk-ops
3
star
57

lightning-network

A Haskell interface for the Lightning Network
Haskell
3
star
58

cobwebhook

Set of webhook Plug middleware
Elixir
3
star
59

ton-paychan

Fast and cheap off-chain micro-transactions for the Telegram Open Network
Makefile
3
star
60

metatemplates

A template repo with common files used in Serokell
Makefile
2
star
61

haskell-algorand-sdk

A Haskell SDK for the Algorand blockchain
Haskell
2
star
62

vendix

libc shim that proxies /nix/store FS calls to a vendored location
C
2
star
63

ton.nix

A Nix overlay for building the Telegram Open Network tools
Nix
2
star
64

nixage

Dismantle stack because who needs it when we have Nix and Stackage
Haskell
2
star
65

serokell-closure

Overlaid Nixpkgs closure for Serokell build systems
Nix
2
star
66

co-log-sys

Syslog implementation on top of co-log-core
Haskell
2
star
67

overcight

A tool that will tell you how well your CI pipelines exercise the files in the repository
Haskell
2
star
68

serokell-stackage

Stackage for your Nix
HTML
2
star
69

github-ops-access

Make sure a certain team always has admin access to all repositories in the organisation
Haskell
1
star
70

rebar3-to-nix

Generate buildable Nix expression from Rebar3 lock file
Erlang
1
star
71

junkscraper

GitHub pull request branch garbage collector
Erlang
1
star
72

avl-example

An example implementation of blockchain using AVL-plus
Haskell
1
star
73

serokell.github.io

Moved to https://serokell.io
1
star
74

tezos-globacap

Haskell
1
star
75

frontend-task

Description of the old test task for frontend developers
1
star
76

async-combinators

Async combinators
Haskell
1
star
77

weird-ghc

Reproduction of a bug in GHC: https://gitlab.haskell.org/ghc/ghc/-/issues/16608
Haskell
1
star
78

hsblst

Haskell bindings and high-level interface to BLST -- a BLS12-381 cryptography library
Haskell
1
star
79

lambda_cache

Polling zero-arity function cache
Elixir
1
star
80

mon

Serokell monitoring library
Haskell
1
star
81

nixos-packet

iPXE images and configuration tools for NixOS deployments on Packet
Nix
1
star
82

stakerdao-infra

Machines and resources for the part of the StakerDAO infrastructure operated by Serokell OÜ
HCL
1
star
83

zipp

Universal zipper (iterator)
Haskell
1
star
84

beamer-theme-serokell

a beamer theme that tries to conform to Serokell brand identity guide
TeX
1
star
85

zeromq-haskell

Fork of the https://gitlab.com/twittner/zeromq-haskell
Haskell
1
star
86

config_macro

Macro that defines Mix.Config.config/3 compatible getters
Elixir
1
star
87

haskell-nix-weeder

Nix library to run weeder on haskell projects built with haskell.nix
Nix
1
star
88

trac11042

Trac #11042 GHC bug reproduction
Nix
1
star
89

morley-zurihac

Hacking on developer tools for the smart contract language of Tezos with Serokell and TQ
CSS
1
star