Implement cache item indexing using numeric sequence keys.

Author: jeetsukumaran

README.md

@@ -128,10 +128,14 @@ dc = DataCache(joinpath(homedir(), ".datacaches", "project1"))
 dc["canidae_occs"]  = pbdb_occurrences(base_name = "Canidae", show = "full")
 dc["dinosaur_taxa"] = pbdb_taxa(name = "Dinosauria", vocab = "pbdb")
 
-# Retrieve
+# Retrieve by label
 occs = dc["canidae_occs"]
 taxa = dc["dinosaur_taxa"]
 
+# Retrieve by sequence index (as shown in showcache output)
+occs = dc[1]
+taxa = dc[2]
+
 # Conditionally fetch
 if !haskey(dc, "trilobites")
     dc["trilobites"] = pbdb_occurrences(base_name = "Trilobita")
@@ -156,6 +160,9 @@ showcache(dc)
 relabel!(dc, "canidae_occs", "canidae")   # by label
 relabel!(dc, 2, "canidae")                # by sequence index
 
+# Retrieve by sequence index
+df = dc[1]
+
 # Remove entries
 delete!(dc, "trilobites")   # by label
 delete!(dc, 2)              # by sequence index

src/DataCaches.jl

@@ -268,8 +268,11 @@ end
 """
     read(cache::DataCache, key::CacheKey) → data
     read(cache::DataCache, label::AbstractString) → data
+    read(cache::DataCache, n::Integer) → data
 
-Retrieve a cached dataset by [`CacheKey`](@ref) or label string.
+Retrieve a cached dataset by [`CacheKey`](@ref), label string, or stable sequence
+index. The `Integer` form uses the sequence index shown in brackets by `showcache`
+(e.g. `[1]`, `[2]`). Use `reindexcache!` to compact gaps after many deletions.
 """
 function Base.read(cache::DataCache, key::CacheKey)
     isfile(key.path) || error("Cache file missing: $(key.path)")
@@ -282,8 +285,15 @@ function Base.read(cache::DataCache, lbl::AbstractString)
     return Base.read(cache, cache._index[id])
 end
 
+function Base.read(cache::DataCache, n::Integer)
+    key = _resolve_by_seq(cache, Int(n))
+    isnothing(key) && error("No cache entry with sequence index $n")
+    return Base.read(cache, key)
+end
+
 Base.getindex(cache::DataCache, lbl::AbstractString) = Base.read(cache, lbl)
 Base.getindex(cache::DataCache, key::CacheKey)        = Base.read(cache, key)
+Base.getindex(cache::DataCache, n::Integer)           = Base.read(cache, n)
 Base.setindex!(cache::DataCache, data, lbl::AbstractString) = write!(cache, data; label = lbl)
 
 # --- Introspection -----------------------------------------------------------

test/runtests.jl

@@ -240,4 +240,43 @@ using TOML
         end
     end
 
+    @testset "read and getindex by sequence index" begin
+        mktempdir() do dir
+            c = DataCache(dir)
+            write!(c, [1, 2, 3]; label = "first")
+            write!(c, [4, 5, 6]; label = "second")
+
+            @test Base.read(c, 1) == [1, 2, 3]
+            @test Base.read(c, 2) == [4, 5, 6]
+
+            @test c[1] == [1, 2, 3]
+            @test c[2] == [4, 5, 6]
+
+            @test_throws ErrorException c[99]
+        end
+    end
+
+    @testset "seq index stable after deletion" begin
+        mktempdir() do dir
+            c = DataCache(dir)
+            write!(c, "a"; label = "first")
+            write!(c, "b"; label = "second")
+            write!(c, "c"; label = "third")
+            delete!(c, "second")
+            @test c[1] == "a"
+            @test c[3] == "c"
+            @test_throws ErrorException c[2]
+        end
+    end
+
+    @testset "seq index survives reload" begin
+        mktempdir() do dir
+            c1 = DataCache(dir)
+            write!(c1, [9, 8, 7]; label = "persist_seq")
+            seq = only(values(c1._index)).seq
+            c2 = DataCache(dir)
+            @test c2[seq] == [9, 8, 7]
+        end
+    end
+
 end