178 lines
5.3 KiB
Markdown
178 lines
5.3 KiB
Markdown
Protolude
|
|
=========
|
|
|
|
[](https://travis-ci.org/sdiehl/protolude)
|
|
[](https://github.com/protolude/protolude/actions)
|
|
[](https://github.com/protolude/protolude/actions)
|
|
[](https://hackage.haskell.org/package/protolude)
|
|
|
|
A sensible starting Prelude for building custom Preludes.
|
|
|
|
Design points:
|
|
|
|
* Banishes String.
|
|
* Banishes partial functions.
|
|
* Compiler warning on bottoms.
|
|
* Polymorphic string IO functions.
|
|
* Polymorphic show.
|
|
* Automatic string conversions.
|
|
* Types for common data structures in scope.
|
|
* Types for all common string types (Text/ByteString) in scope.
|
|
* Banishes impure exception throwing outside of IO.
|
|
* StateT/ReaderT/ExceptT transformers in scope by default.
|
|
* Foldable / Traversable functions in scope by default.
|
|
* Unsafe functions are prefixed with "unsafe" in separate module.
|
|
* Compiler agnostic, GHC internal modules are abstracted out into Base.
|
|
* ``sum`` and ``product`` are strict by default.
|
|
* Compatibility with GHC 8.0.
|
|
* Includes Semiring for GHC >= 7.6.
|
|
* Includes Bifunctor for GHC >= 7.6.
|
|
* Includes Semigroup for GHC >= 7.6.
|
|
|
|
Supports:
|
|
|
|
* GHC 7.6.1
|
|
* GHC 7.6.2
|
|
* GHC 7.6.3
|
|
* GHC 7.8.1
|
|
* GHC 7.8.2
|
|
* GHC 7.8.3
|
|
* GHC 7.8.4
|
|
* GHC 7.10.1
|
|
* GHC 7.10.2
|
|
* GHC 7.10.3
|
|
* GHC 8.0.1
|
|
* GHC 8.0.2
|
|
* GHC 8.2.1
|
|
* GHC 8.4.1
|
|
* GHC 8.6.1
|
|
* GHC 8.8.1
|
|
|
|
Usage
|
|
-----
|
|
|
|
To try out standalone prelude at the interactive shell, from the Protolude
|
|
project directory run.
|
|
|
|
```haskell
|
|
$ stack exec ghci
|
|
> import Protolude
|
|
```
|
|
|
|
Swapping out the old Prelude
|
|
----------------------------
|
|
|
|
Disable the built-in prelude at the top of your file:
|
|
|
|
```haskell
|
|
{-# LANGUAGE NoImplicitPrelude #-}
|
|
```
|
|
|
|
Or directly in your project cabal file:
|
|
|
|
```haskell
|
|
default-extensions: NoImplicitPrelude
|
|
```
|
|
|
|
Then in your modules:
|
|
|
|
```haskell
|
|
import Protolude
|
|
```
|
|
|
|
Exported Functions
|
|
------------------
|
|
|
|
The list of exports can be browsed [here](http://hackage.haskell.org/package/protolude-0.2.3/docs/Protolude.html).
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
Protolude tries to be light on dependencies and only pulls in *essential*
|
|
libraries that are universally common across most real-world projects. Lower and
|
|
upper bounds are fully specified and compatible with both vanilla Cabal and
|
|
tracks Stack LTS resolver.
|
|
|
|
| Dependencies | Lower (>=) | Upper (<) |
|
|
| ----------- | -------- | -------- |
|
|
| array | 0.4 | 0.6 |
|
|
| async | 2.0 | 2.3 |
|
|
| base | 4.6 | 4.13 |
|
|
| bytestring | 0.10 | 0.11 |
|
|
| containers | 0.5 | 0.7 |
|
|
| deepseq | 1.3 | 1.5 |
|
|
| ghc-prim | 0.3 | 0.6 |
|
|
| hashable | 1.2 | 1.3 |
|
|
| mtl | 2.1 | 2.3 |
|
|
| stm | 2.4 | 2.6 |
|
|
| text | 1.2 | 1.3 |
|
|
| transformers | 0.4 | 0.6 |
|
|
| | | |
|
|
|
|
Structure
|
|
---------
|
|
|
|
Protolude's main modules are the following:
|
|
|
|
* [Protolude.hs](https://github.com/sdiehl/protolude/blob/master/src/Protolude.hs)
|
|
* [Base.hs](https://github.com/sdiehl/protolude/blob/master/src/Protolude/Base.hs)
|
|
* [Show.hs](https://github.com/sdiehl/protolude/blob/master/src/Protolude/Show.hs)
|
|
* [Conv.hs](https://github.com/sdiehl/protolude/blob/master/src/Protolude/Conv.hs)
|
|
|
|
FAQs
|
|
----
|
|
|
|
* **My ``putStrLn`` and ``putStr`` instances are no longer inferred in the presense
|
|
of the ``-XOverloadedStrings`` extension?**
|
|
|
|
Because the print functions are polymorphic the type of the print functions may
|
|
require annotations if the type is not fully specified by inference. To force a
|
|
specific type at the call site use either
|
|
|
|
```haskell
|
|
putText :: MonadIO m => T.Text -> m ()
|
|
putLText :: MonadIO m => TL.Text -> m ()
|
|
```
|
|
|
|
* **How do I write manual Show instances if ``show`` isn't provided?**
|
|
|
|
Generally speaking writing manual instances of Show is a [Haskell antipattern](
|
|
http://www.stephendiehl.com/posts/strings.html) because it produces
|
|
law-violating instances of Show. You probably want to use a [pretty
|
|
printer](https://hackage.haskell.org/package/wl-pprint-text) library for custom
|
|
printing.
|
|
|
|
If backwards compatibility is needed then the base library can be imported
|
|
manually.
|
|
|
|
```haskell
|
|
import GHC.Show (Show(..))
|
|
```
|
|
|
|
Automatic deriving of ``Show`` for your types is still supported since the class
|
|
is in scope by default.
|
|
|
|
* **Partial functions like ``undefined`` raise compiler warnings on
|
|
usage.**
|
|
|
|
This is by design. For fatal uncatchable errors use the provided ``panic``
|
|
function if you intend the program to immediately abort.
|
|
|
|
```haskell
|
|
panic "Thus I die. Thus, thus, thus. Now I am dead"
|
|
```
|
|
|
|
If inside of IO simply use ``throwIO`` for exception handling, or if in pure
|
|
business logic use well-typed checked exceptions of the ``ExceptT`` variety.
|
|
|
|
* **Why is ``id`` not in scope?**
|
|
|
|
It has been renamed to ``identity`` to reserve the ``id`` identifier for the
|
|
more common use case of business logic.
|
|
|
|
License
|
|
-------
|
|
|
|
Released under the MIT License.
|
|
Copyright (c) 2016-2019, Stephen Diehl
|