diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# Intro: My current Haskell Prelude + +[![Hackage](https://img.shields.io/hackage/v/intro.svg)](https://hackage.haskell.org/package/intro) +[![Build Status](https://secure.travis-ci.org/minad/intro.png?branch=master)](http://travis-ci.org/minad/intro) + +Intro is a modern Prelude which provides safe alternatives +for most of the partial functions and follows other +best practices, e.g., Text is preferred over String. +For String overloading the extension 'OverloadedStrings' should be used. +Container types and Monad transformers are provided. + +Most important - this Prelude tries not to be too fancy. +This means it just reexports from base and commonly used libraries +and doesn't invent its own stuff. + +Furthermore the Prelude is +not scattered over multiple files to keep things simple. +Everything is exported explicitly to improve the quality of the documentation. + +List of design decisions: + +* Simplicity: Everything is in one file (Unfortunately we need Intro.Trustworthy for Safe Haskell) +* Conservative extension over the base Prelude +* Rely only on very common external libraries +* Avoid writing custom functions +* Export everything explicitly for good documentation +* Export only total functions or provide safe alternatives (Very few exceptions like div etc.) +* Prefer Text over String, provide ConvertibleStrings +* Provide Monad transformers +* Provide container types +* Prefer generic functions +* Debugging functions, like 'Intro.Trustworthy.trace' and 'undefined' are available but produce compile time warnings +* Don't provide error, only panic instead +* Compatibility with Control.Lens diff --git a/intro.cabal b/intro.cabal --- a/intro.cabal +++ b/intro.cabal @@ -3,9 +3,21 @@ -- see: https://github.com/sol/hpack name: intro -version: 0.1.0.2 +version: 0.1.0.3 synopsis: "Fixed Prelude" - Mostly total and safe, provides Text and Monad transformers -description: Modern Prelude which provides safe alternatives for most of the partial functions. Text is preferred over String. Container types and Monad transformers are provided. Most important - this Prelude avoids fanciness. This means it just reexports from base and commonly used libraries and doesn\'t invent its own stuff. Everything is in one file. +description: Intro is a modern Prelude which provides safe alternatives + for most of the partial functions and follows other + best practices, e.g., Text is preferred over String. + For String overloading the extension 'OverloadedStrings' should be used. + Container types and Monad transformers are provided. + . + Most important - this Prelude tries not to be too fancy. + This means it just reexports from base and commonly used libraries + and doesn\'t invent its own stuff. + . + Furthermore the Prelude is + not scattered over multiple files to keep things simple. + Everything is exported explicitly to improve the quality of the documentation. category: Prelude stability: experimental homepage: https://github.com/minad/intro#readme @@ -19,6 +31,9 @@ build-type: Simple cabal-version: >= 1.10 +extra-source-files: + README.md + source-repository head type: git location: https://github.com/minad/intro @@ -28,23 +43,23 @@ src ghc-options: -Wall build-depends: - base >= 4.8 && < 5.0 - , bifunctors >= 5.2 && < 5.5 - , binary >= 0.7 && < 0.9 - , bytestring >= 0.9 && < 0.11 - , containers >= 0.5 && < 0.6 - , deepseq >= 1.4 && < 1.5 - , dlist >= 0.7 && < 0.9 - , extra >= 1.5.1 && < 1.6 - , hashable >= 1.2 && < 1.3 - , mtl >= 2.2 && < 2.3 - , safe >= 0.3 && < 0.4 - , string-conversions >= 0.4 && < 0.5 - , tagged >= 0.8 && < 0.9 - , text >= 0.7 && < 1.3 - , transformers >= 0.4 && < 0.6 - , unordered-containers >= 0.2 && < 0.3 - , writer-cps-mtl >= 0.1 && < 0.2 + base >= 4.8 && < 5.0 + , bifunctors >= 5.2 && < 5.5 + , binary >= 0.7 && < 0.9 + , bytestring >= 0.9 && < 0.11 + , containers >= 0.5 && < 0.6 + , deepseq >= 1.4 && < 1.5 + , dlist >= 0.7 && < 0.9 + , extra >= 1.5.1 && < 1.6 + , hashable >= 1.2.5 && < 1.3 + , mtl >= 2.2 && < 2.3 + , safe >= 0.3 && < 0.4 + , string-conversions >= 0.4 && < 0.5 + , tagged >= 0.8 && < 0.9 + , text >= 0.7 && < 1.3 + , transformers >= 0.4 && < 0.6 + , unordered-containers >= 0.2 && < 0.3 + , writer-cps-mtl >= 0.1.1.2 && < 0.2 if impl(ghc < 8.0) build-depends: semigroups >= 0.9 && < 1 @@ -62,23 +77,23 @@ test ghc-options: -Wall build-depends: - base >= 4.8 && < 5.0 - , bifunctors >= 5.2 && < 5.5 - , binary >= 0.7 && < 0.9 - , bytestring >= 0.9 && < 0.11 - , containers >= 0.5 && < 0.6 - , deepseq >= 1.4 && < 1.5 - , dlist >= 0.7 && < 0.9 - , extra >= 1.5.1 && < 1.6 - , hashable >= 1.2 && < 1.3 - , mtl >= 2.2 && < 2.3 - , safe >= 0.3 && < 0.4 - , string-conversions >= 0.4 && < 0.5 - , tagged >= 0.8 && < 0.9 - , text >= 0.7 && < 1.3 - , transformers >= 0.4 && < 0.6 - , unordered-containers >= 0.2 && < 0.3 - , writer-cps-mtl >= 0.1 && < 0.2 + base >= 4.8 && < 5.0 + , bifunctors >= 5.2 && < 5.5 + , binary >= 0.7 && < 0.9 + , bytestring >= 0.9 && < 0.11 + , containers >= 0.5 && < 0.6 + , deepseq >= 1.4 && < 1.5 + , dlist >= 0.7 && < 0.9 + , extra >= 1.5.1 && < 1.6 + , hashable >= 1.2.5 && < 1.3 + , mtl >= 2.2 && < 2.3 + , safe >= 0.3 && < 0.4 + , string-conversions >= 0.4 && < 0.5 + , tagged >= 0.8 && < 0.9 + , text >= 0.7 && < 1.3 + , transformers >= 0.4 && < 0.6 + , unordered-containers >= 0.2 && < 0.3 + , writer-cps-mtl >= 0.1.1.2 && < 0.2 , intro , lens if impl(ghc < 8.0) diff --git a/src/Intro.hs b/src/Intro.hs --- a/src/Intro.hs +++ b/src/Intro.hs @@ -14,10 +14,36 @@ -- Stability : experimental -- Portability : portable -- --- Modern Prelude which provides safe alternatives for most of the partial functions and a focus on nice documentation. --- Text is preferred over String. Container types and Monad transformers are provided. --- Most important - this Prelude avoids fanciness. This means it just reexports from base and commonly used libraries and doesn\'t invent its own stuff. Everything is in one file. +-- Intro is a modern Prelude which provides safe alternatives +-- for most of the partial functions and follows other +-- best practices, e.g., Text is preferred over String. +-- For String overloading the extension 'OverloadedStrings' should be used. +-- Container types and Monad transformers are provided. -- +-- Most important - this Prelude tries not to be too fancy. +-- This means it just reexports from base and commonly used libraries +-- and doesn\'t invent its own stuff. +-- +-- Furthermore the Prelude is +-- not scattered over multiple files to keep things simple. +-- Everything is exported explicitly to improve the quality of the documentation. +-- +-- List of design decisions: +-- +-- * Simplicity: Everything is in one file (Unfortunately we need Intro.Trustworthy for Safe Haskell) +-- * Conservative extension over the base Prelude +-- * Rely only on very common external libraries +-- * Avoid writing custom functions +-- * Export everything explicitly for good documentation +-- * Export only total functions or provide safe alternatives (Very few exceptions like div etc.) +-- * Prefer Text over String, provide ConvertibleStrings +-- * Provide Monad transformers +-- * Provide container types +-- * Prefer generic functions +-- * Debugging functions, like 'Intro.Trustworthy.trace' and 'undefined' are available but produce compile time warnings +-- * Don't provide error, only panic instead +-- * Compatibility with Control.Lens +-- -- Some 'Prelude' functions are missing from 'Intro'. More general variants are available for the following functions: -- -- * '>>' = 'Control.Applicative.*>' @@ -215,6 +241,8 @@ , LHashMap , Data.HashSet.HashSet , Data.Hashable.Hashable + , Intro.Trustworthy.Hashable1 + , Intro.Trustworthy.Hashable2 -- ** Seq , Data.Sequence.Seq @@ -523,6 +551,7 @@ , Control.Monad.Writer.CPS.execWriter , Control.Monad.Writer.CPS.mapWriter , Control.Monad.Writer.CPS.WriterT + , Control.Monad.Writer.CPS.writerT , Control.Monad.Writer.CPS.runWriterT , Control.Monad.Writer.CPS.execWriterT , Control.Monad.Writer.CPS.mapWriterT @@ -552,6 +581,7 @@ , Control.Monad.RWS.CPS.execRWS , Control.Monad.RWS.CPS.mapRWS , Control.Monad.RWS.CPS.RWST + , Control.Monad.RWS.CPS.rwsT , Control.Monad.RWS.CPS.runRWST , Control.Monad.RWS.CPS.evalRWST , Control.Monad.RWS.CPS.execRWST diff --git a/src/Intro/Trustworthy.hs b/src/Intro/Trustworthy.hs --- a/src/Intro/Trustworthy.hs +++ b/src/Intro/Trustworthy.hs @@ -28,9 +28,10 @@ , traceM , traceShow , traceShowM + , Data.Hashable.Lifted.Hashable1 + , Data.Hashable.Lifted.Hashable2 ) where -import Control.Applicative (Applicative) import Control.Monad.Trans (MonadIO(liftIO)) import Data.Function ((.)) import Data.Text (Text) @@ -39,12 +40,14 @@ import qualified Data.Text import qualified Debug.Trace import qualified GHC.Exts +import qualified Data.Hashable.Lifted #if MIN_VERSION_base(4,9,0) +import Control.Applicative (Applicative) #define APPLICATIVE Applicative #else -#define APPLICATIVE Monad import Control.Monad (Monad) +#define APPLICATIVE Monad #endif -- | The 'trace' function outputs the trace message given as its first argument,