Compat Package for Julia
The Compat package is designed to ease interoperability between
older and newer versions of the Julia
language. In particular, in cases where it is
impossible to write code that works with both the latest Julia
master branch and older Julia versions, or impossible to write code
that doesn't generate a deprecation warning in some Julia version, the
Compat package provides a macro that lets you use the latest syntax
in a backwards-compatible way.
This is primarily intended for use by other Julia packages, where it is important to maintain cross-version compatibility.
To use Compat in your Julia package, add a line
Compat = "34da2185-b29b-5c13-b0c7-acf172513d20" in the
and a line
Compat = "..." in the
[compat]section to the
in your package directory. The version in the latter should be the minimum
version that supports all needed fatures (see list below), and (if applicable)
any newer major versions verified to be compatible. Then, in your package,
shortly after the
module statement a line like this:
and then as needed add
@compat ...compat syntax...
wherever you want to use syntax that differs in the latest Julia
master (the development version of Julia). The
compat syntax is usually
the syntax on Julia
master. However, in a few cases where this is not possible,
a slightly different syntax might be used.
Please check the list below for the specific syntax you need.
@inferred [AllowedType] f(x)is defined (#27516). (since Compat 3.12.0)
Search a character in a string with
findprev(#31664). (since Compat 3.12.0)
∘(f) = fis defined (#34251). (since Compat 3.11.0)
Base.OneTo(#35577). (since Compat 3.11.0)
AbstractArrays(#30268). (since Compat 3.10.0)
similar(::PermutedDimsArray)now uses the parent (#35304). (since Compat 3.9.0)
isdisjoint(l, r)indicates whether two collections are disjoint (#34427). (since Compat 3.9.0)
mergewith!(combine, dicts...)are like
merge!(combine, dicts...)but without the restriction that the argument
combinemust be a
Function(#34296). (since Compat 3.9.0).
@NamedTuplemacro for convenient
struct-like syntax for declaring
key::Typedeclarations (#34548). (since Compat 3.8.0)
evalpoly(x, (p1, p2, ...)), the function equivalent to
@evalpoly(x, p1, p2, ...)(#32753). (since Compat 3.7.0)
onenow defined (#34773). (since Compat 3.6.0)
I2are CartesianIndex values, constructs a CartesianIndices iterator (#29440). (Since Compat 3.5.0)
one(::CartesianIndex)(#29442). (Since Compat 3.5.0)
vis mutable (#34652). (since Compat 3.4.0)
uuid5generates a version 5 universally unique identifier (UUID), as specified by RFC 4122 (#28761). (since Compat 3.3.0)
dotnow has a 3-argument method
dot(x, A, y)without storing the intermediate result
A*y(#32739). (since Compat 3.2.0)
pkgdir(m)returns the root directory of the package that imported module
m(#33128). (since Compat 3.2.0)
filtercan now act on a
Tuple#32968. (since Compat 3.1.0)
Base.Order.ReverseOrderinghas a zero arg constructor #33736. (since Compat 3.0.0)
Function composition now supports multiple functions:
∘(f, g, h) = f ∘ g ∘ hand splatting
∘(fs...)for composing an iterable collection of functions (#33568). (since Compat 3.0.0)
only(x)returns the one-and-only element of a collection
x(#33129). (since Compat 2.2.0)
modnow accepts a unit range as the second argument (#32628). (since Compat 2.2.0)
eachsliceto iterate over first, second, or given dimension of an array (#29749). (since Compat 2.2.0)
isnothingfor testing if a variable is equal to
nothing(#29674). (since Compat 2.1.0)
hasfield(#28850). (since Compat 2.0.0)
mergemethods with one and
NamedTuples (#29259). (since Compat 2.0.0)
stopas positional argument (#28708). (since Compat 1.3.0)
One of the most important rules for
Compat.jl is to avoid breaking user code
whenever possible, especially on a released version.
Although the syntax used in the most recent Julia version
is the preferred compat syntax, there are cases where this shouldn't be used.
Examples include when the new syntax already has a different meaning
on previous versions of Julia, or when functions are removed from
Julia and the alternative cannot be easily implemented on previous versions.
In such cases, possible solutions are forcing the new feature to be used with
qualified name in
Compat.jl (e.g. use
reimplementing the old features on a later Julia version.
If you're adding additional compatibility code to this package, the
contrib/commit-name.sh script in the base Julia repository is useful for extracting the version number from a git commit SHA. For example, from the git repository of
julia, run something like this:
bash $ contrib/commit-name.sh a378b60fe483130d0d30206deb8ba662e93944da 0.5.0-dev+2023
This prints a version number corresponding to the specified commit of the form
X.Y.Z-aaa+NNNN, and you can then test whether Julia
is at least this version by
VERSION >= v"X.Y.Z-aaa+NNNN".
Tagging the correct minimum version of Compat
Note that you should specify the correct minimum version for
Compat in the
[compat] section of your
Project.toml, as given in above list.