From 8eba1bbceb7f86a15c0bbb0fa79530242b990e55 Mon Sep 17 00:00:00 2001
From: Serial <69764315+Serial-ATA@users.noreply.github.com>
Date: Wed, 1 May 2024 11:46:03 -0400
Subject: [PATCH] GlobalOptions: Add `preserve_format_specific_items()`

---
 CHANGELOG.md                       |  1 +
 lofty/src/config/global_options.rs | 28 ++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 208726ef..b6bffb09 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - New `tag::items` module for generic representations of complex tag items
   - New `Timestamp` item for ISO 8601 timestamps ([PR](https://github.com/Serial-ATA/lofty-rs/pull/389))
 - **ID3v2**: Special handling for frames with timestamps with `Frame::Timestamp` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/389))
+- **GlobalOptions**: `preserve_format_specific_items()`
 
 ### Changed
 - **VorbisComments**/**ApeTag**: Verify contents of `ItemKey::FlagCompilation` during `Tag` merge ([PR](https://github.com/Serial-ATA/lofty-rs/pull/387))
diff --git a/lofty/src/config/global_options.rs b/lofty/src/config/global_options.rs
index b3d7fc35..1308c270 100644
--- a/lofty/src/config/global_options.rs
+++ b/lofty/src/config/global_options.rs
@@ -24,6 +24,7 @@ pub(crate) unsafe fn global_options() -> &'static GlobalOptions {
 pub struct GlobalOptions {
 	pub(crate) use_custom_resolvers: bool,
 	pub(crate) allocation_limit: usize,
+	pub(crate) preserve_format_specific_items: bool,
 }
 
 impl GlobalOptions {
@@ -46,6 +47,7 @@ impl GlobalOptions {
 		Self {
 			use_custom_resolvers: true,
 			allocation_limit: Self::DEFAULT_ALLOCATION_LIMIT,
+			preserve_format_specific_items: true,
 		}
 	}
 
@@ -85,6 +87,31 @@ impl GlobalOptions {
 		self.allocation_limit = allocation_limit;
 		*self
 	}
+
+	/// Whether or not to preserve format-specific items
+	///
+	/// When converting a tag from its concrete format (ex. [`Id3v2`](crate::id3::v2::Id3v2Tag)) to
+	/// a [`Tag`], this options controls whether to preserve any special items that
+	/// are unique to the concrete tag.
+	///
+	/// This will store an extra immutable tag alongside the generic [`Tag`], which will be merged
+	/// back into the concrete tag when converting back.
+	///
+	/// # Examples
+	///
+	/// ```rust
+	/// use lofty::config::{apply_global_options, GlobalOptions};
+	///
+	/// // I'm just reading tags, I don't need to preserve format-specific items
+	/// let global_options = GlobalOptions::new().preserve_format_specific_items(false);
+	/// apply_global_options(global_options);
+	/// ```
+	///
+	/// [Tag]: crate::tag::Tag
+	pub fn preserve_format_specific_items(&mut self, preserve_format_specific_items: bool) -> Self {
+		self.preserve_format_specific_items = preserve_format_specific_items;
+		*self
+	}
 }
 
 impl Default for GlobalOptions {
@@ -96,6 +123,7 @@ impl Default for GlobalOptions {
 	/// GlobalOptions {
 	/// 	use_custom_resolvers: true,
 	/// 	allocation_limit: Self::DEFAULT_ALLOCATION_LIMIT,
+	/// 	preserve_format_specific_items: true,
 	/// }
 	/// ```
 	fn default() -> Self {