protolude
A small prelude.
https://github.com/sdiehl/protolude
LTS Haskell 22.33: | 0.3.4 |
Stackage Nightly 2024-09-07: | 0.3.4 |
Latest on Hackage: | 0.3.4 |
protolude-0.3.4@sha256:6787ea63ec2e8172f3d011e7f913cf831d9fdc44de233d479b2d5af06a69d559,2253
Module documentation for 0.3.4
- Protolude
- Protolude.Applicative
- Protolude.Base
- Protolude.Bifunctor
- Protolude.Bool
- Protolude.CallStack
- Protolude.Conv
- Protolude.ConvertText
- Protolude.Debug
- Protolude.Either
- Protolude.Error
- Protolude.Exceptions
- Protolude.Functor
- Protolude.List
- Protolude.Monad
- Protolude.Panic
- Protolude.Partial
- Protolude.Safe
- Protolude.Semiring
- Protolude.Show
- Protolude.Unsafe
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
andproduct
are strict by default.- Includes Semiring for GHC >= 7.6.
- Includes Bifunctor for GHC >= 7.6.
- Includes Semigroup for GHC >= 7.6.
Supports:
- GHC 7.6.3
- GHC 7.8.4
- GHC 7.10.3
- GHC 8.0.2
- GHC 8.2.2
- GHC 8.4.1
- GHC 8.4.4
- GHC 8.6.1
- GHC 8.6.4
- GHC 8.6.5
- GHC 8.8.1
- GHC 8.10.1
- GHC 9.0.1
- GHC 9.2.1
Stack LTS:
- lts-6.x
- lts-7.x
- lts-8.x
- lts-9.x
- lts-10.x
- lts-11.x
- lts-12.x
- lts-13.x
- lts-14.x
- lts-15.x
- lts-16.x
- lts-17.x
- lts-18.x
- lts-19.14 and higher
Usage
To try out standalone prelude at the interactive shell, from the Protolude project directory run.
$ stack repl
> import Protolude
Swapping out the old Prelude
Disable the built-in prelude at the top of your file:
{-# LANGUAGE NoImplicitPrelude #-}
Or directly in your project cabal file:
default-extensions: NoImplicitPrelude
Then in your modules:
import Protolude
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.16 |
bytestring | 0.10 | 0.11 |
containers | 0.5 | 0.7 |
deepseq | 1.3 | 1.5 |
ghc-prim | 0.3 | 0.7 |
hashable | 1.2 | 1.4 |
mtl | 2.1 | 2.3 |
stm | 2.4 | 2.6 |
text | 1.2 | 1.3 |
transformers | 0.4 | 0.6 |
fail | 4.9 | 4.10 |
Structure
Protolude’s main modules are the following:
FAQs
- My
putStrLn
andputStr
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
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 because it produces law-violating instances of Show. You probably want to use a pretty printer library for custom printing.
If backwards compatibility is needed then the base library can be imported manually.
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.
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.
- But what if I want the partial functions?
You if you need partial functions for backwards compatibility you can use the
Protolude.Partial
module and mask the safe definitions as needed.
import Protolude hiding (head)
import Protolude.Partial (head)
Development Tools
GHC Magic
To build the exports
management tool use:
$ cabal new-build exports --flag dev
$ cabal run exports
This tool uses GHC’s internal compile symbol table to generate a list of exports and keep the export list of protolude stable across different versions of GHC and base.
Continious Integration
There is a massive test suite that tests all versions of GHC 7.6 - GHC HEAD alongside all Stack resolvers to ensure no regressions. Any pull requests or patch has to pass the 47 integrity checks before being considered. Any pull request must keep the export list consistent across GHC and Base version and not have any accidental symbol dropping or drift without updating the export golden tests.
License
Released under the MIT License. Copyright (c) 2016-2022, Stephen Diehl
Changes
0.3.3
- GHC 9.4.4 support
0.3.2
- GHC 9.2.2 support
- Drop export executable
0.3.1
- GHC 9.0.1 and 9.2.1 support
- Add
HasCallStack
to unsafe* functions. - Banish
String
onreadMaybe
andreadEither
.
0.3.0
- GHC 8.10.1 support
- Use
Protolude.ConvertText
as the default string conversion class. This removes partial functions when converting to/from ByteStrings. - Provide
Protolude.Conv
as a compatibility layer for old string conversion interface. - Migrated
Debug
andUnsafe
toProtolude.Debug
andProtolude.Unsafe
. - Export Unicode functions:
intToDigit
isAlpha
isAlphaNum
isAscii
isControl
isDigit
isHexDigit
isLetter
isLower
isPrint
isSpace
isUpper
- Export
MonadFail
class. - Export
gcast
from Data.Typeable. - Export
typeOf
from Data.Typeable. - Export
Handler
from Control.Exception. - Export
yield
from Control.Concurrency. - Provide compatibility module
Protolude.Partial
as single export for unsafe partial functions with the same naming conventions as Prelude.
0.2.4
- GHC 8.8.1 support
0.2.3
- GHC 8.6.1 support
- Export
fromLeft
andfromRight
. - Mask
always
andalwaysSucceeds
from STM export for stm-2.5.
0.2.2
- Add explicit
witness
function for use as type witness without warnings. Makes undefined semantically distinguishable from type witnesses. - Backwards compatible
Protolude.Safe
module for explicit handling of partial list operations. - Export
minimumDef
,maximumDef
. - Looser lower-bound on Data.Kind export for GHC 8.0.x.
0.2.1
- Exposes
throwE
andcatchE
. - Add
transformers-compat
for old versions of transformers that requirethrowE
,catchE
. - Fix
safe
version bounds for new versions. - Add
mapExceptT and
withExceptT`. - Export
scanl'
and provide shim for backwards compatibility. - Add
putErrLn
. - Expose
RealFloat
. - Expose
GHC.Records
exports for GHC 8.2 and above.
0.2
- Expose
Symbol
andNat
types fromGHC.TypeLits
by default. - Switch exported
(<>)
to be fromData.Monoid
instead of Semigroup. - Expose
putByteString
andputLByteString
monomorphic versions ofputStrLn
functions - Export
genericLength
and other generic list return functions. - Rename
msg
tofatalErrorMessage
. - Export
ExceptT
,ReaderT
, andStateT
constructors. - Mask
displayException
from default exports. - Mask
stToIO
from default exports. - Export
NonEmpty
type and constructor for Base 4.9 only. - Export
Data.Semigroup
type and functions for Base 4.9 only. - Restrict exported symbols from
async
to set available in 2.0. - Add
(&&^)
,(||^)
,(<&&>)
,(<||>)
- Expose
unzip
. - Export
maximumMay
andminimumMay
. - Mask
Type
export fromData.Kind
. - Wrap
die
to takeText
argument instead of[Char]
. - Export constructors
GHC.Generics
:(:+:)
,(:*:)
, and(:.:)
. - Expose
StablePtr
,IntPtr
andWordPtr
types.
0.1.9
- Make
sum
andproduct
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
- Exports monadic
(>>)
operator by default. - Adds
traceId
andtraceShowId
functions. - Exports
reader
andstate
functions by default. - Export lifted
throwIO
andthrowTo
functions.
0.1.6
- Adds uncatchable panic exception throwing using Text message.
- Removes
printf
- Removes
string-conv
dependency so Stack build works withoutextra-deps
. - Brings
Callstack
machinery in for GHC 8.x. - Removes
throw
andassert
fromControl.Exception
exports. - Removes
unsafeShiftL
andunsafeShiftR
fromData.Bits
exports. - Reexport
throw
asunsafeThrow
via Unsafe module. - Hides all Show class functions. Only the Class itself is exported. Forbids custom instances that are not GHC derived.
- Export
encodeUtf8
anddecodeUtf8
functions by default. - Adds
unsnoc
function.
0.1.5
- Initial release.