From 179d5e6e1758c5a8e74d7bebb879886b5fa53c64 Mon Sep 17 00:00:00 2001
From: Philippe PITTOLI <karchnu@karchnu.fr>
Date: Sun, 2 Jun 2024 01:37:30 +0200
Subject: [PATCH] Documentation fixes. Add `Trigger#delete?`.

---
 spec/test-cars.cr             | 27 ++++++++++++++++++++++++++-
 src/dodb/storage/common.cr    |  4 ++--
 src/dodb/trigger/index.cr     | 13 +++++++++++++
 src/dodb/trigger/partition.cr | 12 ++++++++++++
 src/dodb/trigger/tags.cr      | 19 ++++++++++++++++---
 5 files changed, 69 insertions(+), 6 deletions(-)

diff --git a/spec/test-cars.cr b/spec/test-cars.cr
index a7dd740..f93981e 100644
--- a/spec/test-cars.cr
+++ b/spec/test-cars.cr
@@ -45,7 +45,7 @@ describe "tracking inconsistencies between implementations" do
 		cars_ram0 = SPECDB::RAMOnly(Car).new "-0"
 		cars_ram1 = SPECDB::RAMOnly(Car).new "-1"
 		cars_ram2 = SPECDB::RAMOnly(Car).new "-2"
-		cars_fifo = SPECDB::Common(Car).new "-2", 5
+		cars_fifo = SPECDB::Common(Car).new "-3", 5
 
 		uncached_searchby_name,    uncached_searchby_color,    uncached_searchby_keywords    = uncached_indexes cars_ram0
 		cached_searchby_name,      cached_searchby_color,      cached_searchby_keywords      = cached_indexes   cars_ram1
@@ -101,3 +101,28 @@ describe "tracking inconsistencies between implementations" do
 		cars_fifo.rm_storage_dir
 	end
 end
+
+describe "Errors" do
+	it "Removing an entry which doesn't exist" do
+		db = SPECDB::RAMOnly(Car).new
+		searchby_name, searchby_color, searchby_keywords = uncached_indexes db
+
+		searchby_name.delete?(    "doesn't exist").should be_nil # Should not throw an exception.
+		searchby_color.delete?(   "doesn't exist").should be_nil # Should not throw an exception.
+		searchby_keywords.delete?("doesn't exist").should be_nil # Should not throw an exception.
+
+		expect_raises DODB::MissingEntry do
+			searchby_name.delete      "doesn't exist"
+		end
+
+		expect_raises DODB::MissingEntry do
+			searchby_color.delete     "doesn't exist"
+		end
+
+		expect_raises DODB::MissingEntry do
+			searchby_keywords.delete  "doesn't exist"
+		end
+
+		db.rm_storage_dir
+	end
+end
diff --git a/src/dodb/storage/common.cr b/src/dodb/storage/common.cr
index fe67ac1..36bb761 100644
--- a/src/dodb/storage/common.cr
+++ b/src/dodb/storage/common.cr
@@ -12,8 +12,8 @@
 # constantly ask for the same data over and over.
 #
 # ```
-# # Creates a DODB database for common usage (a limited number of cached entries).
-# car_database = DODB::Storage::Common.new "/path/to/db"
+# # Creates a DODB database for common usage (a limited number of cached entries: 100k).
+# car_database = DODB::Storage::Common.new "/path/to/db", 100_000
 #
 # # Creates a (cached) index.
 # cars_by_name = car_database.new_index "name", &.name
diff --git a/src/dodb/trigger/index.cr b/src/dodb/trigger/index.cr
index 654022c..0b983d8 100644
--- a/src/dodb/trigger/index.cr
+++ b/src/dodb/trigger/index.cr
@@ -256,12 +256,25 @@ class DODB::Trigger::Index(V) < DODB::Trigger(V)
 	# # Deletes the car named "Corvet".
 	# car_by_name.delete "Corvet"
 	# ```
+	# WARNING: may throw a MissingEntry exception.
 	def delete(index : String)
 		key = get_key index
 
 		@storage.delete key
 	end
 
+	# Deletes a value based on its index, but do ignores a MissingEntry error.
+	#
+	# ```
+	# # Deletes the car named "Corvet" (no MissingEntry exception if the car doesn't exist).
+	# car_by_name.delete? "Corvet"
+	# ```
+	def delete?(v : String)
+		delete v
+	rescue MissingEntry
+		nil
+	end
+
 	# :inherit:
 	def trigger_directory : String
 		"#{@storage_root}/indices/by_#{@name}"
diff --git a/src/dodb/trigger/partition.cr b/src/dodb/trigger/partition.cr
index 79936e5..fd64a9b 100644
--- a/src/dodb/trigger/partition.cr
+++ b/src/dodb/trigger/partition.cr
@@ -153,6 +153,18 @@ class DODB::Trigger::Partition(V) < DODB::Trigger(V)
 		delete partition, do true end
 	end
 
+	# Deletes all entries within the provided partition, but do ignores a MissingEntry error.
+	#
+	# ```
+	# # Deletes all red cars.
+	# cars_by_color.delete? "red" # no MissingEntry exception if there is no red cars
+	# ```
+	def delete?(partition : String)
+		delete partition
+	rescue MissingEntry
+		nil
+	end
+
 	# Deletes entries within the provided partition and matching the provided block of code.
 	#
 	# ```
diff --git a/src/dodb/trigger/tags.cr b/src/dodb/trigger/tags.cr
index b8bda22..a04d004 100644
--- a/src/dodb/trigger/tags.cr
+++ b/src/dodb/trigger/tags.cr
@@ -187,9 +187,22 @@ class DODB::Trigger::Tags(V) < DODB::Trigger(V)
 	# cars_by_keywords.delete "slow"                 # Deletes all slow cars.
 	# cars_by_keywords.delete ["slow", "expensive"]  # Deletes all cars that are both slow and expensive.
 	# ```
-	# WARNING: throws an exception if no value is found.
-	def delete(tag : String | Array(String))
-		delete tag, do true end
+	# WARNING: throws a MissingEntry exception if no value is found.
+	def delete(tag_or_tags : String | Array(String))
+		delete tag_or_tags, do true end
+	end
+
+	# Deletes all entries with the provided tag, but do ignores a MissingEntry error.
+	#
+	# ```
+	# # No MissingEntry exception will be thrown.
+	# cars_by_keywords.delete? "slow"                # Deletes all slow cars.
+	# cars_by_keywords.delete? ["slow", "expensive"] # Deletes all cars that are both slow and expensive.
+	# ```
+	def delete?(tag_or_tags : String | Array(String))
+		delete tag_or_tags
+	rescue MissingEntry
+		nil
 	end
 
 	# Deletes entries within the provided tag index and matching the provided block of code.