@hackage base-compat0.14.1
A compatibility layer for base
Categories
License
MIT
Maintainer
Simon Hengel <sol@typeful.net>, João Cristóvão <jmacristovao@gmail.com>, Ryan Scott <ryan.gl.scott@gmail.com>
Links
Versions
Installation
Tested Compilers
Dependencies (3)
Dependents (215)
@hackage/rest-wai, @hackage/mockery, @hackage/monad-markov, @hackage/microformats2-parser, @hackage/criterion-measurement, @hackage/getopt-generics, Show all…
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.:
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 asPrelude
frombase-4.9.0.0
System.IO.Error.catch
is not re-exported fromPrelude.Compat
for older versions ofbase
Text.Read.Compat.readMaybe
Text.Read.Compat.readEither
Data.Monoid.Compat.<>
- Added
bitDefault
,testBitDefault
,popCountDefault
,(.^.)
,(.>>.)
,(.<<.)
,(!>>.)
, and(!<<.)
toData.Bits.Compat
- Added
toIntegralSized
andoneBits
toData.Bits.Compat
(if usingbase-4.7
or later) - Added
firstA
andsecondA
toData.Bitraversable.Compat
- Added
bool
function toData.Bool.Compat
- Added
isLeft
,isRight
,fromLeft
, andfromRight
toData.Either.Compat
- Added
forkFinally
toControl.Concurrent.Compat
- Added
withMVarMasked
function toControl.Concurrent.MVar.Compat
- Added
(<$!>)
function toControl.Monad.Compat
- Weakened
RealFloat
constraints onrealPart
,imagPart
,conjugate
,mkPolar
, andcis
inData.Complex.Compat
- Added more efficient
maximumBy
/minimumBy
toData.Foldable.Compat
- Added
($>)
andvoid
functions toData.Functor.Compat
(&)
andapplyWhen
functions toData.Function.Compat
($>)
andvoid
functions toData.Functor.Compat
modifyIORef'
,atomicModifyIORef'
andatomicWriteIORef
toData.IORef.Compat
dropWhileEnd
,isSubsequenceOf
,sortOn
, anduncons
functions toData.List.Compat
- Correct versions of
nub
,nubBy
,union
, andunionBy
toData.List.Compat
inits1
andtails1
toData.List.Compat
compareLength
toData.List.Compat
andData.List.NonEmpty.Compat
asProxyTypeOf
with a generalized type signature toData.Proxy.Compat
modifySTRef'
toData.STRef.Compat
String
,lines
,words
,unlines
, andunwords
toData.String.Compat
gcoerceWith
toData.Type.Coercion.Compat
makeVersion
function toData.Version.Compat
traceId
,traceShowId
,traceM
,traceShowM
,traceWith
,traceShowWith
, andtraceEventWith
functions toDebug.Trace.Compat
byteSwap16
,byteSwap32
, andbyteSwap64
toData.Word.Compat
plusForeignPtr
toForeign.ForeignPtr.Compat
calloc
andcallocBytes
functions toForeign.Marshal.Alloc.Compat
callocArray
andcallocArray0
functions toForeign.Marshal.Array.Compat
fillBytes
toForeign.Marshal.Utils.Compat
- Added
Data.List.Compat.scanl'
showFFloatAlt
,showGFloatAlt
,readBin
, andshowBin
toNumeric.Compat
lookupEnv
,setEnv
andunsetEnv
toSystem.Environment.Compat
unsafeFixIO
andunsafeDupablePerformIO
toSystem.IO.Unsafe.IO
RuntimeRep
-polymorphic($!)
toPrelude.Compat
liftA2
is re-exported fromPrelude.Compat
foldl'
is re-exported fromPrelude.Compat
RuntimeRep
-polymorphicthrow
toControl.Exception.Compat
isResourceVanishedError
,resourceVanishedErrorType
, andisResourceVanishedErrorType
toSystem.IO.Error.Compat
singleton
toData.List.Compat
andData.List.NonEmpty.Compat
inits1
andtails1
toData.List.NonEmpty.Compat
permutations
,permutations1
, andsortOn
toData.List.NonEmpty.Compat
hGetContents'
,getContents'
, andreadFile'
toSystem.IO.Compat
readBinP
toText.Read.Lex.Compat
withTypeable
andpattern TypeRep
toType.Reflection.Compat
minusNaturalMaybe
toNumeric.Natural.Compat
mapAccumM
andforAccumM
toData.Traversable.Compat
heqT
toData.Typeable.Compat
unzip
toData.Functor.Compat
(!?)
andunsnoc
toData.List.Compat
List
toData.List.Compat
(when building with GHC 9.6 or later)getSolo
toData.Tuple.Compat
decT
andhdecT
toData.Typeable.Compat
decTypeRep
toType.Reflection.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:
class Bits b => FiniteBits b where
finiteBitSize :: b -> Int
However, in base-4.8.0.0
,
FiniteBits
gained additional functions:
class Bits b => FiniteBits b where
finiteBitSize :: b -> Int
countLeadingZeros :: b -> Int -- ^ @since 4.8.0.0
countTrailingZeros :: b -> Int -- ^ @since 4.8.0.0
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:
instance FiniteBits Foo where
finiteBitSize = ...
#if MIN_VERSION_base(4,8,0) || !(MIN_VERSION_base(4,7,0))
countLeadingZeros = ...
countTrailingZeros = ...
#endif
Another approach is to backport the API from base-4.7.0.0
and to declare
additional methods outside of the class:
#if MIN_VERSION_base(4,7,0) && !(MIN_VERSION_base(4,8,0))
countLeadingZeros :: FiniteBits b => b -> Int
countLeadingZeros = {- default implementation #-}
#endif
The situation is only slightly better for classes which exist across all versions of base
,
but have grown their API. For example, it's tempting to define
#if !(MIN_VERSION_base(4,8,0))
displayException :: Exception e => e -> String
displayException = show
#endif
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:
bifunctor-classes-compat
for theBifoldable
andBitraversable
type classes, introduced inbase-4.10.0.0
contravariant
for theContravariant
type class, introduced inbase-4.12.0.0
.foldable1-classes-compat
for theFoldable1
andBifoldable1
type classes, introduced inbase-4.18.0.0
OneTuple
for theSolo
data type, introduced inghc-prim-0.7.0
Version policy
This package follows the Haskell Package Versioning
Policy. As such, if a new base-compat
release only
adds new exports, then as a general rule, we will release it with a minor
version bump. Moreover, since base-compat
does not backport data type or
class definitions (see the "What is not covered" section above), base-compat
usually has fewer major version bumps than base
itself.
An exception to the general rule about adding new exports is the
Prelude.Compat
module. If a new base-compat
release adds any new exports,
then it will always be accompanied by a major version bump, even if there are
no other API changes. This is because of the special nature of
Prelude.Compat
, which is designed to be imported unqualified. Pre-emptively
bumping the major version number is meant to signal to downstream libraries
that they should check to see if the new Prelude.Compat
additions will clash
with identifiers of the same names in their code.
Supported versions of GHC/base
ghc-9.12.*
/base-4.21.*
ghc-9.10.*
/base-4.20.*
ghc-9.8.*
/base-4.19.*
ghc-9.6.*
/base-4.18.*
ghc-9.4.*
/base-4.17.*
ghc-9.2.*
/base-4.16.*
ghc-9.0.*
/base-4.15.*
ghc-8.10.*
/base-4.14.*
ghc-8.8.*
/base-4.13.*
ghc-8.6.*
/base-4.12.*
ghc-8.4.*
/base-4.11.*
ghc-8.2.*
/base-4.10.*
ghc-8.0.*
/base-4.9.*
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!