Module documentation for 0.10.5

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

base-compat is intentionally designed to have zero dependencies. As a
consequence, there are some modules that can only be backported up to certain
versions of base. If an even wider support window is desired in these
scenarios, there also exists a base-compat-batteries package which augments
base-compat with certain compatibility package dependencies. For more info,
see the Dependencies 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

RuntimeRep-polymorphic ($!) to Prelude.Compat

RuntimeRep-polymorphic throw to Control.Exception.Compat

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:

As with the previous approach, you won’t be able to define new members of the type
class without CPP guards. In other words, the non-CPP approach would limit
uses to the lowest common denominator.

As neither approach is a very satisfactory solution, and to embrace
consistency, we do not pursue either approach. For similar reasons, we do not
backport data types.

Dependencies

base-compat is designed to have zero dependencies (besides libraries that
ship with GHC itself). A consequence of this choice is that there are certain
modules that have a “limited” support window. An important example of this is
Prelude.Compat, which backports the Semigroup class to versions of base
older than 4.11 (when it was added to the Prelude). Because Semigroup was
not added to base until base-4.9, base-compat cannot backport it to
any earlier version of base than this.

If you would instead desire to be able to use a version of Prelude.Compat
that does backport Semigroup to even older versions of base, even if it
means pulling in other dependencies, then you are in luck. There also exists
a base-compat-batteries package, which exposes a strict superset of the API
in base-compat. base-compat-batteries has all the same modules as
base-compat, but exposes more functionality on more versions of base by
reexporting things from compatibility libraries whenever necessary. (For
instance, base-compat-batteries exports the Semigroup class from the
semigroups library when built against versions of base older than 4.9.)

Because base-compat and base-compat-batteries have the same module names,
they are quite easy to switch out for one another in library projects, at the
expense of having clashing names if one tries to import them in GHCi. To
work around this issue, base-compat and base-compat-batteries also provide
copies of each module with the suffix .Repl (for base-compat) and
.Repl.Batteries (for base-compat-batteries) to give them globally unique
namespaces in the event one wants to import them into GHCi.

Here is a list of compatibility libraries that base-compat-batteries depends
on, paired with the things that each library backports:

We also make an attempt to keep base-compat building with GHC HEAD, but due
to its volatility, it may not work at any given point in time. If it doesn’t,
please report it!

Patches are welcome; add tests for new code!

Changes

Changes in 0.10.5 [2018.10.18]

Enable BangPatterns in Prelude.Compat.

Changes in 0.10.4 [2018.07.03]

Make more modules Trustworthy. In particular, fix a regression in which
Prelude.Compat was inferred as Unsafe by explicitly marking it as
Trustwothy.

Changes in 0.10.3 [2018.07.02]

Backport the proper fixity for ($!), which was accidentally omitted in
base-compat-0.10.2.

Changes in 0.10.2 [2018.07.02]

Sync with base-4.12/GHC 8.6

Backport RuntimeRep-polymorphic versions of ($!) and throw to
Prelude.Compat and Control.Exception.Compat, respectively
(if using base-4.10/GHC 8.2 or later).

Introduce the Data.Functor.Contravariant.Compat module, which reexports
Data.Functor.Contravariant if using base-4.12/GHC 8.6 or later.

See Data.Functor.Contravariant.Compat in the corresponding
base-compat-batteries release for a version with a wider support window.

Changes in 0.10.1 [2018.04.10]

Add Data.List.NonEmpty.Compat.

Reexport (Data.Semigroup.<>) from Data.Monoid.Compat back to base-4.9.

Changes in 0.10.0 [2018.04.05]

Sync with base-4.11/GHC 8.4

Backport Semigroup((<>)) to Prelude.Compat.

Note that the Semigroup class has only been in base since
base-4.9/GHC 8.0, so accordingly, this can only be backported back
to GHC 8.0. If you wish to have a version of Prelude.Compat that backports
Semigroup to older GHCs (by conditionally depending on the semigroups
library), use the Prelude.Compat module from the base-compat-batteries
package.

Backport (<&>) to Data.Functor.Compat

Backport iterate' to Data.List.Compat

Backport showHFloat to Numeric.Compat

Backport a RuntimeRep-polymorphic withTypeable function to
Type.Reflection.Compat. (This is only exported on base-4.10/GHC 8.2.)

Introduce the following modules, back until the oldest version of base
that can support backporting them. If you wish to use them in conjunction
with older versions of base, use the base-compat-batteries package.

Introduce versions of modules with the suffix .Repl. These simply reexport
the contents of their counterparts without the .Repl suffix to provide
a globally unique namespace to import from in the event one wants to import
base-compat modules into GHCi. (In base-compat-batteries, the
corresponding suffix is .Repl.Batteries.)

Changes in 0.9.3 [2017.04.10]

Sync with base-4.10/GHC 8.2

Backport fromLeft/fromRight to Data.Either.Compat

Backport implementations of maximumBy/minimumBy which use constant stack
space to Data.Foldable.Compat

Backport asProxyTypeOf with a generalized type signature to
Data.Proxy.Compat

Backport gcoerceWith to Data.Type.Coercion.Compat

Backport plusForeignPtr to Foreign.ForeignPtr.Compat

Changes in 0.9.2

Allow building on the HaLVM

Changes in 0.9.1

Use the more efficient version of replicateM and replicateM_ introduced
in base-4.9