support tag diff before saving

Author: sentriz

README.md

@@ -43,11 +43,29 @@ func main() {
 
         // Non-standard allowed too
         "ALBUMARTIST_CREDIT": {"Brian Eno & David Bynre"},
-    })
+    }, 0)
     // check(err)
 }
 ```
 
+#### Options for writing
+
+The behaviour of writing can be configured with some bitset flags
+
+The options are
+
+- `Clear` which clears existing metadata before writing the new
+- `DiffBeforeWrite` which won't modify the file on disk if the new metadata is the same as the old
+
+The options can be combined the with the bitwise `OR` operator (`|`)
+
+```go
+    taglib.WriteTags(path, tags, taglib.Clear|taglib.DiffBeforeWrite) // clear and diff
+    taglib.WriteTags(path, tags, taglib.DiffBeforeWrite)              // only diff diff
+    taglib.WriteTags(path, tags, taglib.Clear)                        // only clear
+    taglib.WriteTags(path, tags, 0)                                   // don't clear or diff
+```
+
 ### Reading properties
 
 ```go

taglib.cpp

@@ -46,41 +46,40 @@ taglib_file_tags(const char *filename) {
   return tags;
 }
 
+static const uint8_t CLEAR = 1 << 0;
+static const uint8_t DIFF_SAVE = 1 << 1;
+
 __attribute__((export_name("taglib_file_write_tags"))) bool
-taglib_file_write_tags(const char *filename, const char **tags, bool replace) {
+taglib_file_write_tags(const char *filename, const char **tags, uint8_t opts) {
   if (!filename || !tags)
     return false;
 
   TagLib::FileRef file(filename);
   if (file.isNull())
     return false;
 
-  TagLib::PropertyMap properties;
-  for (size_t i = 0; tags[i] != nullptr; i++) {
+  auto properties = file.properties();
+  if (opts & CLEAR)
+    properties.clear();
+
+  for (size_t i = 0; tags[i]; i++) {
     TagLib::String row(tags[i], TagLib::String::UTF8);
     if (auto ti = row.find("\t"); ti != -1) {
-      TagLib::String key(row.substr(0, ti));
-      if (auto v = row.substr(ti + 1); !v.isEmpty()) {
-        properties.insert(key, TagLib::StringList(v));
-      } else {
-        properties.insert(key, TagLib::StringList());
-      }
+      auto key = row.substr(0, ti);
+      auto value = row.substr(ti + 1);
+      if (value.isEmpty())
+        properties.erase(key);
+      else
+        properties.replace(key, value.split("\v"));
     }
   }
 
-  if (replace) {
-    if (auto rejected = file.setProperties(properties); !rejected.isEmpty())
-      return 0;
-    return file.save();
+  if (opts & DIFF_SAVE) {
+    if (file.properties() == properties)
+      return true;
   }
 
-  auto existing = file.properties();
-  existing.erase(properties); // wipe the keys we're sending
-  existing.merge(properties); // merge them in
-  existing.removeEmpty();
-
-  if (auto rejected = file.setProperties(existing); !rejected.isEmpty())
-    return 0;
+  file.setProperties(properties);
   return file.save();
 }
 

taglib.go

@@ -221,17 +221,20 @@ func ReadProperties(path string) (Properties, error) {
 	}, nil
 }
 
-// WriteTags writes the metadata key-values pairs to path, leaving other found keys untouched.
-func WriteTags(path string, tags map[string][]string) error {
-	return writeTagsOpt(path, tags, false)
-}
+// WriteOption configures the behavior of write operations. The can be passed to [WriteTags] and combined with the bitwise OR operator.
+type WriteOption uint8
 
-// ReplaceTags replaces all tag metadata at path with the the metadata in thhe map.
-func ReplaceTags(path string, tags map[string][]string) error {
-	return writeTagsOpt(path, tags, true)
-}
+const (
+	// Clear indicates that all existing tags not present in the map should be removed.
+	Clear WriteOption = 1 << iota
+
+	// DiffBeforeWrite enables comparison before writing to disk.
+	// When set, no write occurs if the map contains no changes compared to the existing tags.
+	DiffBeforeWrite
+)
 
-func writeTagsOpt(path string, tags map[string][]string, replace bool) error {
+// WriteTags writes the metadata key-values pairs to path. The behavior can be controlled with [WriteOption].
+func WriteTags(path string, tags map[string][]string, opts WriteOption) error {
 	var err error
 	path, err = filepath.Abs(path)
 	if err != nil {
@@ -247,17 +250,11 @@ func writeTagsOpt(path string, tags map[string][]string, replace bool) error {
 
 	var raw []string
 	for k, vs := range tags {
-		if len(vs) == 0 {
-			raw = append(raw, k+"\t") // allow clearing
-			continue
-		}
-		for _, v := range vs {
-			raw = append(raw, k+"\t"+v)
-		}
+		raw = append(raw, fmt.Sprintf("%s\t%s", k, strings.Join(vs, "\v")))
 	}
 
 	var out bool
-	if err := mod.call("taglib_file_write_tags", &out, wasmPath(path), raw, replace); err != nil {
+	if err := mod.call("taglib_file_write_tags", &out, wasmPath(path), raw, opts); err != nil {
 		return fmt.Errorf("call: %w", err)
 	}
 	if !out {
@@ -374,6 +371,10 @@ func (m *module) call(name string, dest any, args ...any) error {
 			}
 		case int:
 			params = append(params, uint64(a))
+		case uint8:
+			params = append(params, uint64(a))
+		case WriteOption:
+			params = append(params, uint64(a))
 		case uint32:
 			params = append(params, uint64(a))
 		case uint64:

taglib.wasm

@@ -32,14 +32,15 @@ func TestClear(t *testing.T) {
 	for _, path := range paths {
 		t.Run(filepath.Base(path), func(t *testing.T) {
 			// set some tags first
-			err := taglib.ReplaceTags(path, map[string][]string{
+			err := taglib.WriteTags(path, map[string][]string{
 				"ARTIST":     {"Example A"},
 				"ALUMARTIST": {"Example"},
-			})
+			}, taglib.Clear)
+
 			nilErr(t, err)
 
 			// then clear
-			err = taglib.ReplaceTags(path, nil)
+			err = taglib.WriteTags(path, nil, taglib.Clear)
 			nilErr(t, err)
 
 			got, err := taglib.ReadTags(path)
@@ -94,7 +95,7 @@ func TestReadWrite(t *testing.T) {
 	for _, path := range paths {
 		for i, tags := range testTags {
 			t.Run(fmt.Sprintf("%s_tags_%d", filepath.Base(path), i), func(t *testing.T) {
-				err := taglib.ReplaceTags(path, tags)
+				err := taglib.WriteTags(path, tags, taglib.Clear)
 				nilErr(t, err)
 
 				got, err := taglib.ReadTags(path)
@@ -120,12 +121,13 @@ func TestMergeWrite(t *testing.T) {
 
 	for _, path := range paths {
 		t.Run(filepath.Base(path), func(t *testing.T) {
-			err := taglib.ReplaceTags(path, nil) // clear
+			err := taglib.WriteTags(path, nil, taglib.Clear)
 			nilErr(t, err)
 
 			err = taglib.WriteTags(path, map[string][]string{
 				"ONE": {"one"},
-			})
+			}, 0)
+
 			nilErr(t, err)
 			cmp(t, path, map[string][]string{
 				"ONE": {"one"},
@@ -134,7 +136,8 @@ func TestMergeWrite(t *testing.T) {
 			nilErr(t, err)
 			err = taglib.WriteTags(path, map[string][]string{
 				"TWO": {"two", "two!"},
-			})
+			}, 0)
+
 			nilErr(t, err)
 			cmp(t, path, map[string][]string{
 				"ONE": {"one"},
@@ -143,7 +146,8 @@ func TestMergeWrite(t *testing.T) {
 
 			err = taglib.WriteTags(path, map[string][]string{
 				"THREE": {"three"},
-			})
+			}, 0)
+
 			nilErr(t, err)
 			cmp(t, path, map[string][]string{
 				"ONE":   {"one"},
@@ -154,7 +158,8 @@ func TestMergeWrite(t *testing.T) {
 			// change prev
 			err = taglib.WriteTags(path, map[string][]string{
 				"ONE": {"one new"},
-			})
+			}, 0)
+
 			nilErr(t, err)
 			cmp(t, path, map[string][]string{
 				"ONE":   {"one new"},
@@ -166,7 +171,8 @@ func TestMergeWrite(t *testing.T) {
 			err = taglib.WriteTags(path, map[string][]string{
 				"ONE":   {},
 				"THREE": {"three new!"},
-			})
+			}, 0)
+
 			nilErr(t, err)
 			cmp(t, path, map[string][]string{
 				"TWO":   {"two", "two!"},
@@ -276,14 +282,14 @@ func BenchmarkWrite(b *testing.B) {
 	b.ResetTimer()
 
 	for range b.N {
-		err := taglib.ReplaceTags(path, bigTags)
+		err := taglib.WriteTags(path, bigTags, taglib.Clear)
 		nilErr(b, err)
 	}
 }
 
 func BenchmarkRead(b *testing.B) {
 	path := tmpf(b, egFLAC, "eg.flac")
-	err := taglib.ReplaceTags(path, bigTags)
+	err := taglib.WriteTags(path, bigTags, taglib.Clear)
 	nilErr(b, err)
 	b.ResetTimer()