Add new public function Pkg.satisfies_compat(::VersionNumber, ::String), and add (to docs) some examples of checking [compat] entries

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

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)
 

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

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 #

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