base-compat

A compatibility layer for base

Latest on Hackage:0.11.1

See all snapshots base-compat appears in

MIT licensed and maintained by Simon Hengel, João Cristóvão, Ryan Scott

Module documentation for 0.8.2

This version can be pinned in stack with:[email protected]:33e1ec007653de82e28dde3dad46769c97b180ea6700256f6af707b2dcba95e7,2743

A compatibility layer for base Hackage version Build Status

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 for that.

Basic usage

In your cabal file, you should have something like this:

  build-depends:      base              >= 4.3
                    , 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
  • Data.Monoid.Compat.<>
  • Added bitDefault, testBitDefault, and popCountDefault to Data.Bits.Compat
  • Added toIntegralSized to Data.Bits.Compat (if using base-4.7)
  • 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
  • Correct versions of nub, nubBy, union, and unionBy to Data.List.Compat
  • makeVersion function to Data.Version.Compat
  • traceId, traceShowId, traceM, and traceShowM functions to Debug.Trace.Compat
  • byteSwap16, byteSwap32, and byteSwap64 to Data.Word.Compat
  • calloc and callocBytes functions to Foreign.Marshal.Alloc.Compat
  • callocArray and callocArray0 functions to Foreign.Marshal.Array.Compat
  • fillBytes to Foreign.Marshal.Utils.Compat
  • Added Data.List.Compat.scanl'
  • showFFloatAlt and showGFloatAlt to Numeric.Compat
  • lookupEnv, setEnv and unsetEnv to System.Environment.Compat

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

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

Changes

Changes in 0.8.2

  • Backport bitDefault, testBitDefault, and popCountDefault in Data.Bits.Compat to all versions of base
    • Backport toIntegralSized to base-4.7
  • Backport nub and nubBy (as well as union and unionBy, which are implemented in terms of them) to fix logic error in Data.List.Compat
  • Backport byteSwap16, byteSwap32, and byteSwap64 to Data.Word.Compat
  • Backport fillBytes in Foreign.Marshal.Utils.Compat
  • Backport showFFloatAlt and showGFloatAlt to Numeric.Compat

Changes in 0.8.1.1

  • Fixed Windows build

Changes in 0.8.1

  • Implement setEnv and unsetEnv in System.Environment.Compat (which were ported from the setenv package). As a result, base-compat now depends on unix on POSIX-like operating systems.
  • Drop GHC 6.12 (and base-4.2.0.0) compatibility

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
  • base-compat no longer redefines the data types Down and Alt. See here 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 <>