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.

In addition, base-compat only backports functions. In particular, we
purposefully do not backport data types or type classes introduced in newer
versions of base. For more info, see the
Data types and type classes
section.

Basic usage

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

build-depends: base >= 4.3
, base-compat >= 0.9.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.:

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

unsafeFixIO and unsafeDupablePerformIO to System.IO.Unsafe.IO

What is not covered

Data types and type classes

base-compat purposefully does not export any data types or type classes that
were introduced in more recent versions of base. The main reasoning for this
policy is that it is not some data types and type classes have had their APIs
change in different versions of base, which makes having a consistent
compatibility API for them practically impossible.

As an example, consider the FiniteBits type class. It was introduced in
base-4.7.0.0
with the following API:

This raises the question: how can FiniteBits be backported consistently
across all versions of base? One approach is to backport the API exposed in
base-4.8.0.0 on versions prior to 4.7.0.0. The problem with this is that
countLeadingZeros and countTrailingZeros are not exposed in base-4.7.0.0,
so instances of FiniteBits would have to be declared like this:

This is a very unsatisfactory solution, and for this reason, we do not pursue
it. For similar reasons, we do not backport data types.

Other compatibility packages

If you really need your favorite data type or type class in base to be
backported, you might be in luck, since several data types have their own
compatibility packages on Hackage. Here is a list of such packages: