Repository files navigation

TheCompat package is designed to ease interoperability betweenolder and newer versions of theJulialanguage. In particular, in cases where it isimpossible to write code that works with both the latest Juliamaster branch and older Julia versions, or impossible to write codethat doesn't generate a deprecation warning in some Julia version, theCompat package provides a macro that lets you use thelatest syntaxin a backwards-compatible way.

This is primarily intended for use by otherJuliapackages, whereit is important to maintain cross-version compatibility.

To use Compat in your Julia package, add it as a dependency of your package using the package manager

pkg> add Compat

and add aversion specifier linesuch asCompat = "3.22, 4" in the[compat]section of theProject.toml filein your package directory. The version in the latter should be the minimumversion that supports all needed features (see list below). Note that Compat v4requires Julia v1.6, but some features may have been backported to Compat v3(see thefeature list of the release-3 branch).If you require any of those backported features, be sure to specify the correctcompatibility in yourProject.toml. E.g. if the feature from Compat v4.x hasbeen backported to v3.y, useCompat = 3.y, 4.x. If you use a feature that hadoriginally been added in Compat v3 (e.g. in 3.x), don't forget to also declarecompatibility with v4 withCompat = 3.x, 4 (unless you use one the very fewthings that got removed between Compat v3 and v4,which you most probably don't).

To minimize dependency conflicts between packages it is recommended that packagesallow for both appropriate v4 and v3 versions of Compat.jl in their Project.toml(except for rare cases of packages that support only v4 or v3 version of Compat.jl).

Then, in your package, shortly after themodule statement include a line likethis:

using Compat

and then as needed add

@compat...compat syntax...

wherever you want to usesyntax that differs in the latest Juliamaster (the development version of Julia). Thecompat syntax is usuallythe syntax on Juliamaster. 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.

Note that if you want to use afunctionnew_f defined in later Julia versions, it is redefined in Compat (asCompat.new_f) and exported, so you don't need to change anything to your code beyond the initial import.

Features in the development versions ofjulia may be added and released inCompat.jl. However, such features are considered experimental until therelevantjulia version is released. These features can be changed or removedwithout incrementing the major version of Compat.jl if necessary to matchchanges injulia.

• filter can now act on aNamedTuple#50795. (since Compat 4.17.0)

• insertdims(D; dims) is the opposite ofdropdims (#45793) (since Compat 4.16.0)

• Compat.Fix{N} which fixes an argument at theNth position (#54653) (since Compat 4.16.0)

• chopprefix(s, prefix) andchopsuffix(s, suffix) (#40995) (since Compat 4.15.0)

• logrange(lo, hi; length) is likerange but with a constant ratio, not difference. (#39071) (since Compat 4.14.0) Note that on Julia 1.8 and earlier, the version from Compat has slightly lower floating-point accuracy than the one in Base (Julia 1.11 and later).

• allequal(f, itr) andallunique(f, itr) methods. (#47679) (since Compat 4.13.0)

• Iterators.cycle(itr, n) is the lazy version ofrepeat(vector, n). (#47354) (since Compat 4.13.0)

• @compat public foo, bar marksfoo andbar as public in Julia 1.11+ and is a no-op in Julia 1.10 and earlier. (#50105) (since Compat 3.47.0, 4.10.0)

• redirect_stdio, for simple stream redirection. (#37978) (since Compat 4.8.0)

• trunc,floor,ceil, andround toBool. (#25085) (since Compat 4.7.0)

• splat(f) which is equivalent toargs -> f(args...). (#42717,#48038) (since Compat 4.6.0) (Note: for historical reasons,Compat on Julia before v1.9 also exportsSplat; its usage is discouraged, however.)

• Compat.@assume_effects setting... ex overrides the compiler's effect modeling for the method definitionex on Julia versions that support this feature. Julia version without support just pass backex. (#43852) (since Compat 4.4.0)

• div,lcm,gcd,/,rem, andmod willpromote heterogenousDates.Periods (@bdf9ead9). (since Compat 4.3.0)

• stack combines a collection of slices into one array (#43334). (since Compat 3.46.0, 4.2.0)

• keepat! removes the items at all the indices which are not given and returnsthe modified source (#36229,#42351). (since Compat 3.44.0, 4.1.0)

• @compat (; a, b) = (; c=1, b=2, a=3) supports property descturing assignment syntax (#39285).

• allequal, the opposite ofallunique (#43354). (since Compat 3.42.0)

• eachsplit for iteratively performing split(str). (#39245). (since Compat 3.41.0)

• ismutabletype(t::Type) check whether a type is mutable (the fieldmutable ofDataType was removed.#39037) (since Compat 3.40)

• convert(::Type{<:Period}, ::CompoundPeriod) can convertCompoundPeriods into the specifiedPeriod type (#40803) (since Compat 3.38.0)

• Compat.@inline andCompat.@noinline can be used at function callsites to encourage the compiler to (not) inline the function calls on Julia versions that support these features, and otherwise do not have any effects (#41312) (since Compat 3.37)

• Compat.@inline andCompat.@noinline can be used within function body to hint to the compiler the inlineability of the defined function (#41312) (since Compat 3.37)

• Compat.@constprop :aggressive ex andCompat.@constprop :none ex allow control over constant-propagation during inference on Julia versions that support this feature, and otherwise just pass backex. (#42125) (since Compat 3.36)

• Returns(value) returnsvalue for any arguments (#39794) (since Compat 3.35)

• The functioncurrent_exceptions() has been added to get the currentexception stack. Julia-1.0 lacks runtime support for full execption stacks,so we return only the most recent exception in that case. (#29901) (sinceCompat 3.34)

• Two argument methodsfindmax(f, domain),argmax(f, domain) and the correspondingmin versions (#35316,#41076) (since Compat 3.31.1)

• isunordered(x) returns true ifx is value that is normally unordered, such asNaN ormissing (#35316) (since Compat 3.31.1)

• get accepts tuples and numbers (#41007,#41032) (since Compat 3.31)

• @something and@coalesce as short-circuiting versions ofsomething andcoalesce (#40729) (since Compat 3.29)

• pkgversion(m::Module) returns the version of the package that loaded a given module (#45607) (since Compat 4.11)

• VersionNumber(::VersionNumber) defined as a no-op constructor (#45052) (since Compat 4.12)

One of the most important rules forCompat.jl is to avoid breaking user codewhenever possible, especially on a released version.

Although the syntax used in the most recent Julia versionis the preferred compat syntax, there are cases where this shouldn't be used.Examples include when the new syntax already has a different meaningon previous versions of Julia, or when functions are removed fromBaseJulia and the alternative cannot be easily implemented on previous versions.In such cases, possible solutions are forcing the new feature to be used withqualified name inCompat.jl (e.g. useCompat.<name>) orreimplementing the old features on a later Julia version.

If you're adding additional compatibility code to this package, thecontrib/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 ofjulia, run something like this:

bash $ contrib/commit-name.sh a378b60fe483130d0d30206deb8ba662e93944da0.5.0-dev+2023

This prints a version number corresponding to the specified commit of the formX.Y.Z-aaa+NNNN, and you can then test whether Juliais at least this version byVERSION >= v"X.Y.Z-aaa+NNNN".

Note that you should specify the correct minimum version forCompat in the[compat] section of yourProject.toml, as given in above list.