Deprecate exists to haskey and names to keys and bump minor version i…

…n prep for HDF5 release (#290)

* Deprecate exists to haskey

* Deprecate names to keys and fixup deprecations

* Add depwarn to CI

.github/workflows/CI.yml

@@ -40,7 +40,7 @@ jobs:
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
       - run: |
-          julia --project --code-coverage=user -e "
+          julia --project --depwarn=yes --code-coverage=user -e "
             using Pkg
             url = \"https://github.com/JuliaIO/JLDArchives.jl.git\"
             if VERSION >= v\"1.4\"

Project.toml

@@ -1,6 +1,6 @@
 name = "JLD"
 uuid = "4138dd39-2aa7-5051-a626-17a0bb65d9c8"
-version = "0.11.1"
+version = "0.12.0"
 
 [deps]
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"

doc/jld.md

@@ -29,7 +29,7 @@ b = file["a"][20:30]
 close(file)
 ```
 
-You can use the `names` function to get an array of the dataset or group names in you `*.jld` file ( useful if you forgot your dataset structure and doesn't want to load the entire dataset in memory ). It can be applied on `JldFile` and `JldGroup` types. Consider the following example :
+You can use the `keys` function to get an array of the dataset or group names in you `*.jld` file ( useful if you forgot your dataset structure and doesn't want to load the entire dataset in memory ). It can be applied on `JldFile` and `JldGroup` types. Consider the following example :
 
 ```julia
 file = jldopen("mydata.jld","w")
@@ -41,18 +41,18 @@ close(file)
 
 ```julia
 julia> file = jldopen("mydata.jld","r")
-julia> names(file)
+julia> keys(file)
 2-element Array{String,1}:
  "dataset"
  "group"
-julia> names(file["group"])
+julia> keys(file["group"])
 2-element Array{String,1}:
  "dataset0"
  "dataset1"
 julia> read(file["group/dataset0"])
 1:7
-julia> names(file["dataset"])
-ERROR: MethodError: no method matching names(::JLD.JldDataset)...
+julia> keys(file["dataset"])
+ERROR: MethodError: no method matching keys(::JLD.JldDataset)...
 julia> typeof(file["dataset"])
 JLD.JldDataset
 ```

src/JLD.jl

@@ -4,8 +4,7 @@ using HDF5, FileIO
 
 import HDF5: file, create_group, open_group, delete_object, name, ismmappable, readmmap
 import Base: close, convert, datatype_pointerfree, delete!, dump, eltype, getindex, iterate,
-             length, names, ndims, read, setindex!, show, size, sizeof, unsafe_convert,
-             write
+             length, ndims, read, setindex!, show, size, sizeof, unsafe_convert, write
 
 @noinline gcuse(x) = x # because of use of `pointer`, need to mark gc-use end explicitly
 
@@ -346,7 +345,7 @@ ismmappable(obj::JldDataset) = ismmappable(obj.plain)
 readmmap(obj::JldDataset, args...) = readmmap(obj.plain, args...)
 setindex!(parent::Union{JldFile, JldGroup}, val, path::String) = write(parent, path, val)
 
-Base.iterate(parent::Union{JldFile, JldGroup}, state=(names(parent), 1)) = state[2] > length(state[1]) ? nothing :
+Base.iterate(parent::Union{JldFile, JldGroup}, state=(keys(parent), 1)) = state[2] > length(state[1]) ? nothing :
                                                      (parent[state[1][state[2]]], (state[1], state[2]+1))
 
 
@@ -368,7 +367,7 @@ end
 read(parent::Union{JldFile,JldGroup}, name::Symbol) = read(parent, String(string(name)))
 
 function read(obj::JldGroup)
-    nms = names(obj)
+    nms = keys(obj)
     val = Dict{String, Any}()
     for nm in nms
         val[nm] = read(obj[nm])
@@ -810,7 +809,7 @@ end
 getindex(dset::JldDataset, I::Union{AbstractRange{Int},Integer,Colon}...) = getindex(dset, ntuple(i-> isa(I[i], Colon) ? (1:size(dset,i)) : I[i], length(I))...)
 setindex!(dset::JldDataset, x, I::Union{AbstractRange{Int},Integer,Colon}...) = setindex!(dset, x, ntuple(i-> isa(I[i], Colon) ? (1:size(dset,i)) : I[i], length(I))...)
 
-length(x::Union{JldFile, JldGroup}) = length(names(x))
+length(x::Union{JldFile, JldGroup}) = length(keys(x))
 
 ### Custom serialization
 
@@ -1147,7 +1146,7 @@ function truncate_module_path(file::JldFile, mod::Module)
     push!(file.truncatemodules, string(mod))
 end
 
-function names(parent::Union{JldFile, JldGroup})
+function Base.keys(parent::Union{JldFile, JldGroup})
     n = keys(parent.plain)
     keep = trues(length(n))
     reserved = [pathrefs[2:end], pathtypes[2:end], pathrequire[2:end], pathcreator[2:end]]
@@ -1214,7 +1213,7 @@ macro load(filename, vars...)
         vars = Symbol[]
         f = jldopen(filename)
         try
-            for n in names(f)
+            for n in keys(f)
                 obj = f[n]
                 try
                     if isa(obj, JldDataset)
@@ -1269,7 +1268,7 @@ FileIO.save(f::File{format"JLD"}, value...; kwargs...) = error("Must supply a na
 # load with just a filename returns a dictionary containing all the variables
 function FileIO.load(f::File{format"JLD"})
     jldopen(FileIO.filename(f), "r") do file
-        Dict{String,Any}([(var, read(file, var)) for var in names(file)])
+        Dict{String,Any}([(var, read(file, var)) for var in keys(file)])
     end
 end
 # When called with explicitly requested variable names, return each one
@@ -1318,15 +1317,9 @@ function path2modsym(filename::AbstractString)
     Symbol(bname)
 end
 
-# deprecated for HDF5 v0.14+, but use deprecated binding to have common function with
-# e.g. MAT.jl
-import HDF5: exists
-exists(p::Union{JldFile, JldGroup, JldDataset}, path::String) = haskey(p, path)
-
 export
     addrequire,
     creator,
-    exists,
     ismmappable,
     jldopen,
     delete_object,
@@ -1355,4 +1348,21 @@ function __init__()
 end
 
 include("JLD00.jl")
+
+###
+### v0.12.0 deprecations
+###
+
+import HDF5: exists
+export exists
+@noinline function exists(p::Union{JldFile, JldGroup, JldDataset}, path::String)
+    Base.depwarn("`exists(p, path)` is deprecated, use `haskey(p, path)` instead.", :exists)
+    return haskey(p, path)
+end
+
+@noinline function Base.names(parent::Union{JldFile, JldGroup})
+    Base.depwarn("`names(parent)` is deprecated, use `keys(parent)` instead.", :names)
+    return keys(parent)
+end
+
 end

src/JLD00.jl

@@ -7,8 +7,7 @@ using Printf
 using HDF5
 # Add methods to...
 import HDF5: file, create_group, open_group, delete_object, name, ismmappable, readmmap
-import Base: close, dump, getindex, iterate, length, names, read, setindex!, size, show, delete!,
-             write
+import Base: close, dump, getindex, iterate, length, read, setindex!, size, show, delete!, write
 import ..JLD: JLD, _joinpath
 
 # See julia issue #8907
@@ -233,7 +232,7 @@ ismmappable(obj::JldDataset) = ismmappable(obj.plain)
 readmmap(obj::JldDataset, args...) = readmmap(obj.plain, args...)
 setindex!(parent::Union{JldFile, JldGroup}, val, path::String) = write(parent, path, val)
 
-Base.iterate(parent::Union{JldFile, JldGroup}, state=(names(parent), 1)) = state[2] > length(state[1]) ? nothing :
+Base.iterate(parent::Union{JldFile, JldGroup}, state=(keys(parent), 1)) = state[2] > length(state[1]) ? nothing :
                                                      (parent[state[1][state[2]]], (state[1], state[2]+1))
 
 
@@ -901,11 +900,11 @@ function setindex!(dset::JldDataset, X::Array, indices::Base.RangeIndex...)
     HDF5._setindex!(dset, T, X, indices...)
 end
 
-length(x::Union{JldFile, JldGroup}) = length(names(x))
+length(x::Union{JldFile, JldGroup}) = length(keys(x))
 
 ### Dump ###
 function dump(io::IO, parent::Union{JldFile, JldGroup}, n::Int, indent)
-    nms = names(parent)
+    nms = keys(parent)
     println(io, typeof(parent), " len ", length(nms))
     if n > 0
         i = 1
@@ -1019,7 +1018,7 @@ function isversionless(l::Array{Int}, r::Array{Int})
     false
 end
 
-function names(parent::Union{JldFile, JldGroup})
+function Base.keys(parent::Union{JldFile, JldGroup})
     n = keys(parent.plain)
     keep = trues(length(n))
     reserved = [pathrefs[2:end], pathtypes[2:end], pathrequire[2:end]]
@@ -1066,7 +1065,7 @@ macro load(filename, vars...)
         readexprs = Vector{Expr}(undef, 0)
         vars = Vector{Expr}(undef, 0)
         f = jldopen(filename)
-        nms = names(f)
+        nms = keys(f)
         for n in nms
             obj = f[n]
             if isa(obj, JldDataset)
@@ -1118,7 +1117,7 @@ end
 # load with just a filename returns a dictionary containing all the variables
 function load(filename::AbstractString)
     jldopen(filename, "r") do file
-        Dict{String,Any}([(var, read(file, var)) for var in names(file)])
+        Dict{String,Any}([(var, read(file, var)) for var in keys(file)])
     end
 end
 # When called with explicitly requested variable names, return each one
@@ -1141,11 +1140,6 @@ function addrequire(file::JldFile, filename::AbstractString)
     write(file, pathrequire, files)
 end
 
-# deprecated for HDF5 v0.14+, but use deprecated binding to have common function with
-# e.g. MAT.jl
-import HDF5: exists
-exists(p::Union{JldFile, JldGroup, JldDataset}, path::String) = haskey(p, path)
-
 export
     addrequire,
     ismmappable,
@@ -1157,4 +1151,14 @@ export
     @save,
     load,
     save
+
+###
+### v0.12.0 deprecations
+###
+
+@noinline function Base.names(parent::Union{JldFile, JldGroup})
+    Base.depwarn("`names(parent)` is deprecated, use `keys(parent)` instead.", :names)
+    return keys(parent)
+end
+
 end

src/datafile.jl

@@ -6,7 +6,7 @@
 # JLD, or MAT files. This is the super class of HDF5File, HDF5Group,
 # JldFile, JldGroup, Matlabv5File, and MatlabHDF5File.
 #
-# Types inheriting from DataFile should have names, read, and write
+# Types inheriting from DataFile should have keys, read, and write
 # methods
 
 abstract type DataFile end
@@ -39,7 +39,7 @@ read(f::Base.Callable, parent::DataFile, name::ASCIIString...) =
 
 # Read every variable in the file
 function read(f::DataFile)
-    vars = names(f)
+    vars = keys(f)
     vals = Vector{Any}(undef, length(vars))
     for i = 1:length(vars)
         vals[i] = read(f, vars[i])

test/jldtests.jl

@@ -682,9 +682,9 @@ for compatible in (false, true), compress in (false, true)
         end
     end
     fid = jldopen(fn, "r")
-    @test names(fid) == String["mygroup"]
+    @test keys(fid) == String["mygroup"]
     g = fid["mygroup"]
-    @test names(g) == String["x"]
+    @test keys(g) == String["x"]
     @test read(g, "x") == 3.2
     close(g)
     close(fid)
@@ -781,8 +781,8 @@ for compatible in (false, true), compress in (false, true)
     end
     jldopen(fn, "r") do file
         @test(read(file["ms"]) == β)
-        @test(!exists(file, "g/ms"))
-        @test(!exists(file, "g"))
+        @test(!haskey(file, "g/ms"))
+        @test(!haskey(file, "g"))
     end
 
 end # compress in (false,true)