diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,93 @@ +0.2.3 +===== + +* GHC 8.6.1 support +* Expose `fromLeft` and `fromRight`. +* Mask `always` and `alwaysSucceeds` 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` and `catchE`. +* Add `transformers-compat` for old versions of transformers that require + `throwE`, `catchE`. +* Fix `safe` version bounds for new versions. +* Add `mapExceptT and `withExceptT`. +* Export `scanl'` and provide shim for backwards compatability. +* Add `putErrLn`. +* Expose `RealFloat`. +* Expose `GHC.Records` exports for GHC 8.2 and above. + +0.2 +==== + +* Expose `Symbol` and `Nat` types from `GHC.TypeLits` by default. +* Switch exported `(<>)` to be from `Data.Monoid` instead of Semigroup. +* Expose `putByteString` and `putLByteString` monomorphic versions of `putStrLn` functions +* Export `genericLength` and other generic list return functions. +* Rename `msg` to `fatalErrorMessage`. +* Export `ExceptT`, `ReaderT`, and `StateT` 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` and `minimumMay`. +* Mask `Type` export from `Data.Kind`. +* Wrap `die` to take `Text` argument instead of `[Char]`. +* Export constructors `GHC.Generics`: `(:+:)`, `(:*:)`, and `(:.:)`. +* Expose `StablePtr`, `IntPtr` and `WordPtr` types. + +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 +===== + +* Exports monadic ``(>>)`` operator by default. +* Adds ``traceId`` and ``traceShowId`` functions. +* Exports``reader`` and ``state`` functions by default. +* Export lifted ``throwIO`` and ``throwTo`` functions. + +0.1.6 +===== + +* Adds uncatchable panic exception throwing using Text message. +* Removes ``printf`` +* Removes ``string-conv`` dependency so Stack build works without ``extra-deps``. +* Brings ``Callstack`` machinery in for GHC 8.x. +* Removes ``throw`` and ``assert`` from ``Control.Exception`` exports. +* Removes ``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. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,176 @@ +Protolude +========= + +[![Build Status](https://travis-ci.org/sdiehl/protolude.svg?branch=master)](https://travis-ci.org/sdiehl/protolude) +[![Hackage](https://img.shields.io/hackage/v/protolude.svg)](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 + +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 is given in the [Symbols.md](./Symbols.md) file. Haddock +unfortunately breaks in the presence of module reexports and is unable to render +documentation. + +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`` and ``error`` 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-2018, Stephen Diehl diff --git a/protolude.cabal b/protolude.cabal --- a/protolude.cabal +++ b/protolude.cabal @@ -1,5 +1,5 @@ name: protolude -version: 0.2.2 +version: 0.2.3 synopsis: A small prelude. description: A sensible set of defaults for writing custom Preludes. homepage: https://github.com/sdiehl/protolude @@ -25,7 +25,9 @@ GHC == 7.10.3, GHC == 8.0.1, GHC == 8.2.1, - GHC == 8.4.1 + GHC == 8.4.1, + GHC == 8.6.1 +extra-source-files: README.md CHANGES.md Source-Repository head type: git @@ -64,16 +66,16 @@ -fwarn-implicit-prelude build-depends: - base >= 4.6 && <4.12, + base >= 4.6 && <4.13, array >= 0.4 && <0.6, ghc-prim >= 0.3 && <0.6, async >= 2.0 && <2.3, deepseq >= 1.3 && <1.5, - containers >= 0.5 && <0.6, + containers >= 0.5 && <0.7, hashable >= 1.2 && <1.3, transformers >= 0.2 && <0.6, text >= 1.2 && <1.3, - stm >= 2.4 && <2.5, + stm >= 2.4 && <2.6, bytestring >= 0.10 && <0.11, mtl >= 2.1 && <2.3, mtl-compat >= 0.2 && <0.3, diff --git a/src/Protolude.hs b/src/Protolude.hs --- a/src/Protolude.hs +++ b/src/Protolude.hs @@ -492,8 +492,10 @@ import Control.Monad.STM as X ( STM , atomically +#if !(MIN_VERSION_stm(2,5,0)) , always , alwaysSucceeds +#endif , retry , orElse , check diff --git a/src/Protolude/Base.hs b/src/Protolude/Base.hs --- a/src/Protolude/Base.hs +++ b/src/Protolude/Base.hs @@ -122,7 +122,10 @@ #if ( __GLASGOW_HASKELL__ >= 800 ) import Data.Kind as X ( - type (*) + type Type +#if ( __GLASGOW_HASKELL__ < 805 ) + , type (*) +#endif , type Type ) #endif diff --git a/src/Protolude/Either.hs b/src/Protolude/Either.hs --- a/src/Protolude/Either.hs +++ b/src/Protolude/Either.hs @@ -1,3 +1,4 @@ +{-# LANGUAGE CPP #-} {-# LANGUAGE Safe #-} {-# LANGUAGE NoImplicitPrelude #-} @@ -8,12 +9,27 @@ , rightToMaybe , maybeEmpty , maybeToEither +, fromLeft +, fromRight ) where import Data.Function (const) import Data.Monoid (Monoid, mempty) import Data.Maybe (Maybe(..), maybe) import Data.Either (Either(..), either) +#if MIN_VERSION_base(4,10,0) +import Data.Either (fromLeft, fromRight) +#else +-- | Return the contents of a 'Right'-value or a default value otherwise. +fromLeft :: a -> Either a b -> a +fromLeft _ (Left a) = a +fromLeft a _ = a + +-- | Return the contents of a 'Right'-value or a default value otherwise. +fromRight :: b -> Either a b -> b +fromRight _ (Right b) = b +fromRight b _ = b +#endif leftToMaybe :: Either l r -> Maybe l leftToMaybe = either Just (const Nothing) diff --git a/src/Protolude/Functor.hs b/src/Protolude/Functor.hs --- a/src/Protolude/Functor.hs +++ b/src/Protolude/Functor.hs @@ -53,7 +53,7 @@ #if !MIN_VERSION_base(4,11,0) -- | Infix version of foreach. -- --- @<&>@ is to '<$>' what '&' is to '$'. +-- '<&>' is to '<$>' what '&' is to '$'. infixl 1 <&> (<&>) :: Functor f => f a -> (a -> b) -> f b diff --git a/src/Protolude/List.hs b/src/Protolude/List.hs --- a/src/Protolude/List.hs +++ b/src/Protolude/List.hs @@ -7,10 +7,11 @@ sortOn, list, product, - sum + sum, + groupBy, ) where -import Data.List (sortBy) +import Data.List (sortBy, groupBy) import Data.Maybe (Maybe(..)) import Data.Ord (Ord, comparing) import Data.Foldable (Foldable, foldr, foldl')