diff --git a/CHANGES.markdown b/CHANGES.markdown new file mode 100644 --- /dev/null +++ b/CHANGES.markdown @@ -0,0 +1,58 @@ +## Changes in 0.8.0.1 + - Retrospective version bump updating the changelog to reflect the changes + made in 0.8.0 + +## Changes 0.8.0 + - All orphan instances were split off into a separate package, + [`base-orphans`](https://github.com/haskell-compat/base-orphans) + - `base-compat` no longer redefines the data types `Down` and `Alt`. See + [here](https://github.com/haskell-compat/base-compat/issues/17) for + the discussion that led to this change. + - Update `Control.Monad.Compat` for `base-4.8.0.0` + - Update `Data.List.Compat` for `base-4.8.0.0` + - Update `Data.Foldable.Compat` for `base-4.8.0.0` + +## Changes in 0.7.1 + - Backported `Alt` to `Data.Monoid.Compat` + - Backported `Down` to `Data.Ord.Compat` + +## Changes in 0.7.0 + - Add functions and orphan instances introduced by changes to + `base-4.7.0.0` and `base-4.8.0.0` + +## Changes in 0.6.0 + - Update `Prelude.Compat` for `base-4.8.0.0` and AMP + +## Changes in 0.5.0 + - Remove Control.Exception.Base.Compat and GHC.Exception.Compat + - Add System.Exit.Compat.die + - Compatibility with base-4.7.1 + +## Changes in 0.4.1 + - Add `setEnv` and `unsetEnv` to `System.Environment.Compat` + +## Changes in 0.4.0 + - Major refactoring: base-compat no longer aims to replace all base, + only new code is included in module .Compat + - Removed stubbed modules + - Removed generation scripts + +## Changes in 0.3 + - Added functions from Base 4.7 (bool, isLeft, isRight) + - Added instances from Base 4.7 (Either Foldable, Traversable,...) + +## Changes in 0.2.1 + - Fix build on windows + +## Changes in 0.2.0 + - Re-export everything from base + - provides access to `VERSION_base` and `MIN_VERSION_base` CPP macros (with + `#include "base-compat.h"`) + - Do not re-export `System.IO.Error.catch` from `Prelude` for `base` < 4.6.0 + - Add `Eq`/`Ord` instance for `ErrorCall` + - Remove `GHC.IOBase`, `GHC.Handle`, `Control.Concurrent.QSem`, + `Control.Concurrent.QSemN`, `Control.Concurrent.SampleVar`, `Data.HashTable` + +## Changes in 0.1.0 + - Remove getExecutablePath, it did not work with GHC < 7.2 (patches welcome!) + - Add `<>` diff --git a/README.markdown b/README.markdown new file mode 100644 --- /dev/null +++ b/README.markdown @@ -0,0 +1,141 @@ +# A compatibility layer for `base` +## Scope + +The scope of `base-compat` is to provide functions available in later versions +of base to a wider (older) range of compilers. + +In addition, successful library proposals that have been accepted to be part of +upcoming versions of `base` are also included. This package is not intended to +replace `base`, but to complement it. + +Note that `base-compat` does not add any orphan instances. There is a separate +package [`base-orphans`](https://github.com/haskell-compat/base-orphans) for +that. + +## Basic usage + +In your cabal file, you should have something like this: + +``` + build-depends: base == 4.* + , base-compat >= 0.8.0 +``` + +Then, lets say you want to use the `isRight` function introduced with +`base-4.7.0.0`. Replace: + +``` +import Data.Either +``` + +with + +``` +import Data.Either.Compat +``` + +_Note (1)_: There is no need to import both unqualified. The `.Compat` modules +re-exports the original module. + +_Note (2)_: If a given module `.Compat` version is not defined, that either +means that: + +* The module has not changed in recent base versions, thus no `.Compat` is + needed. +* The module has changed, but the changes depend on newer versions of GHC, and + thus are not portable. +* The module has changed, but those changes have not yet been merged in + `base-compat`: patches are welcomed! + +## Using `Prelude.Compat` + +If you want to use `Prelude.Compat` (which provides all the +AMP/Traversable/Foldable changes from `base-4.8.0.0`), it's best to hide +`Prelude`, e.g.: + + import Prelude () + import Prelude.Compat + + main :: IO () + main = mapM_ print (Just 23) + +Alternatively, you can use the `NoImplicitPrelude` language extension: + + {-# LANGUAGE NoImplicitPrelude #-} + import Prelude.Compat + + main :: IO () + main = mapM_ print (Just 23) + +Note that we use + + mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () + +from `Data.Foldable` here, which is only exposed from `Prelude` since +`base-4.8.0.0`. + +Using this approach allows you to write code that works seamlessly with all +versions of GHC that are supported by `base-compat`. + +## What is covered +So far the following is covered. + +### For compatibility with the latest released version of `base` + + * `Prelude.Compat` incorporates the AMP/Foldable/Traversable changes and + exposes the same interface as `Prelude` from `base-4.8.0.0` + * `System.IO.Error.catch` is not re-exported from `Prelude.Compat` for older + versions of `base` + * `Text.Read.Compat.readMaybe` + * `Text.Read.Compat.readEither` + * `System.Environment.Compat.lookupEnv` + * `Data.Monoid.Compat.<>` + * Added `bool` function to `Data.Bool.Compat` + * Added `isLeft` and `isRight` to `Data.Either.Compat` + * Added `withMVarMasked` function to `Control.Concurrent.MVar.Compat` + * Added `(<$!>)` function to `Control.Monad.Compat` + * Added `($>)` and `void` functions to `Data.Functor.Compat` + * `(&)` function to `Data.Function.Compat` + * `($>)` and `void` functions to `Data.Functor.Compat` + * `dropWhileEnd`, `isSubsequenceOf`, `sortOn`, and `uncons` functions to `Data.List.Compat` + * `makeVersion` function to `Data.Version.Compat` + * `traceId`, `traceShowId`, `traceM`, and `traceShowM` functions to `Debug.Trace.Compat` + * `calloc` and `callocBytes` functions to `Foreign.Marshal.Alloc.Compat` + * `callocArray` and `callocArray0` functions to `Foreign.Marshal.Array.Compat` + * Added `Data.List.Compat.scanl'` + +## Supported versions of GHC/base + + * `ghc-7.10.1` / `base-4.8.0.0` + * `ghc-7.8.4` / `base-4.7.0.2` + * `ghc-7.8.3` / `base-4.7.0.1` + * `ghc-7.8.2` / `base-4.7.0.0` + * `ghc-7.8.1` / `base-4.7.0.0` + * `ghc-7.6.3` / `base-4.6.0.1` + * `ghc-7.6.2` / `base-4.6.0.1` + * `ghc-7.6.1` / `base-4.6.0.0` + * `ghc-7.4.2` / `base-4.5.1.0` + * `ghc-7.4.1` / `base-4.5.0.0` + * `ghc-7.2.2` / `base-4.4.1.0` + * `ghc-7.2.1` / `base-4.4.0.0` + * `ghc-7.0.4` / `base-4.3.1.0` + * `ghc-7.0.3` / `base-4.3.1.0` + * `ghc-7.0.2` / `base-4.3.1.0` + * `ghc-7.0.1` / `base-4.3.0.0` + * `ghc-6.12.3` / `base-4.2.0.2` + * `ghc-6.12.2` / `base-4.2.0.1` + * `ghc-6.12.1` / `base-4.2.0.0` + +Patches are welcome; add tests for new code! + +## Development + +For `Prelude.Compat` there is an `Prelude.index` file that was generated from +the output of + + ghc --show-iface Prelude.hi + +To verify that `Prelude.Compat` matches the specification given in +`Prelude.types` run: + + ./check-Prelude.sh diff --git a/base-compat.cabal b/base-compat.cabal --- a/base-compat.cabal +++ b/base-compat.cabal @@ -1,5 +1,5 @@ name: base-compat -version: 0.8.0 +version: 0.8.0.1 license: MIT license-file: LICENSE copyright: (c) 2012-2015 Simon Hengel, @@ -15,8 +15,19 @@ cabal-version: >= 1.8 category: System synopsis: A compatibility layer for base -description: Ban CPP from your code. See the README for what is covered: - +description: Provides functions available in later versions of @base@ to + a wider range of compilers, without requiring you to use CPP + pragmas in your code. See the + + for what is covered. Also see the + + for recent changes. + . + Note that @base-compat@ does not add any orphan instances. + There is a separate package + @@ + for that. +extra-source-files: CHANGES.markdown, README.markdown source-repository head type: git