diff --git a/CHANGELOG.md b/CHANGELOG.md index 5cab492167..e1a4be7deb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ Pkg v1.13 Release Notes - Project.toml environments now support a `readonly` field to mark environments as read-only, preventing modifications. ([#4284]) - Pkg now automatically adds entries to `[sources]` when packages are added by URL or devved, improving workflow consistency. ([#4225]) +- New public function `Pkg.satisfies_compat` for checking whether a VersionNumber satisfies a compat string definition. ([#4292]) Pkg v1.12 Release Notes ======================= diff --git a/docs/src/compatibility.md b/docs/src/compatibility.md index 8115eea833..01fb52218e 100644 --- a/docs/src/compatibility.md +++ b/docs/src/compatibility.md @@ -163,6 +163,40 @@ PkgA = "0.2 - 0.5" # 0.2.0 - 0.5.* = [0.2.0, 0.6.0) PkgA = "0.2 - 0" # 0.2.0 - 0.*.* = [0.2.0, 1.0.0) ``` +### Checking specifications + +You can check if a particular version of a package is contained in a particular +range by using the `Pkg.satisfies_compat` function. For example: + +```julia +julia> Pkg.satisfies_compat(v"0.1.0", "=0.1") +true + +julia> Pkg.satisfies_compat(v"0.1.0", "=0.1.1") +false + +julia> Pkg.satisfies_compat(v"0.1.0", "0.1 - 0.2") +true + +julia> Pkg.satisfies_compat(v"0.3.0", "~0.3.2") +false + +julia> Pkg.satisfies_compat(v"0.3.3", "0.1 - 0.2, ~0.3.2") +true + +julia> # Grid of versions: + versions = [[VersionNumber(major, minor, patch) for patch=0:8, minor=0:3, major=0:1]...]; + +julia> filter(v -> Pkg.satisfies_compat(v, "0.1.8 - 0.2.2, ^0.3.6"), versions) +7-element Vector{VersionNumber}: + v"0.1.8" + v"0.2.0" + v"0.2.1" + v"0.2.2" + v"0.3.6" + v"0.3.7" + v"0.3.8" +``` ## [Fixing conflicts](@id Fixing-conflicts) diff --git a/src/API.jl b/src/API.jl index d11ce3d453..e40f91e078 100644 --- a/src/API.jl +++ b/src/API.jl @@ -1641,4 +1641,27 @@ function auto_gc(on::Bool) return pstate end +""" + satisfies_compat(ver::VersionNumber, compat_entry::String) + +Check if a particular version is contained in a particular [compat] entry. + +## Examples + +```jldoctest; setup = :(import Pkg) +julia> Pkg.satisfies_compat(v"1.2.3", "1") +true + +julia> Pkg.satisfies_compat(v"1.2.3", "=1.2.3") +true + +julia> Pkg.satisfies_compat(v"1.2.3", "=1.2.4") +false +``` +""" +function satisfies_compat(ver::VersionNumber, compat_entry::AbstractString) + spec = Types.semver_spec(compat_entry) + return ver in spec +end + end # module diff --git a/src/Pkg.jl b/src/Pkg.jl index 399d9572cf..1be6789b97 100644 --- a/src/Pkg.jl +++ b/src/Pkg.jl @@ -23,7 +23,7 @@ export PreserveLevel, PRESERVE_TIERED_INSTALLED, PRESERVE_TIERED, PRESERVE_ALL_I export Registry, RegistrySpec public activate, add, build, compat, develop, free, gc, generate, instantiate, - pin, precompile, redo, rm, resolve, status, test, undo, update, why + pin, precompile, redo, rm, resolve, status, test, undo, update, why, satisfies_compat depots() = Base.DEPOT_PATH function depots1(depot_list::Union{String, Vector{String}}=depots()) @@ -885,6 +885,7 @@ function _auto_gc(ctx::Types.Context; collect_delay::Period = Day(7)) end end +const satisfies_compat = API.satisfies_compat ################## # Precompilation # diff --git a/test/api.jl b/test/api.jl index 242b5af2e5..0a52cfd9a0 100644 --- a/test/api.jl +++ b/test/api.jl @@ -313,4 +313,10 @@ end end end end +@testset "satisfies_compat()" begin + @test Pkg.satisfies_compat(v"1.2.3", "1") + @test Pkg.satisfies_compat(v"1.2.3", "=1.2.3") + @test !Pkg.satisfies_compat(v"1.2.3", "=1.2.4") +end + end # module APITests