Probe: Add read_bound()

To get a `BoundTaggedFile` from a `Probe`. Plan to use this to simplify some tests.

Signed-off-by: Serial <69764315+Serial-ATA@users.noreply.github.com>

Author: Serial-ATA

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - For example, a track has `ItemKey::TrackArtist` = "Foo & Bar", then `ItemKey::AlbumArtists` = ["Foo", "Bar"].
 - **Serde**: [Serde] support for `*Type` enums (`FileType`, `TagType`, `PictureType`)
   - Support can be enabled with the new `serde` feature (not enabled by default)
+- **Probe**: `Probe::read_bound()` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/557))
+  - Same as `Probe::read()`, but returns a [`BoundTaggedFile`](https://docs.rs/lofty/latest/lofty/file/struct.BoundTaggedFile.html)
 
 ### Changed
 - **ID3v2**: Check `TXXX:ALBUMARTIST` and `TXXX:ALBUM ARTIST` for `ItemKey::AlbumArtist` conversions

lofty/src/file/tagged_file.rs

@@ -4,9 +4,8 @@ use crate::config::{ParseOptions, WriteOptions};
 use crate::error::{LoftyError, Result};
 use crate::properties::FileProperties;
 use crate::tag::{Tag, TagExt, TagType};
-
 use crate::util::io::{FileLike, Length, Truncate};
-use std::fs::File;
+
 use std::io::{Read, Seek};
 
 /// Provides a common interface between [`TaggedFile`] and [`BoundTaggedFile`]
@@ -453,13 +452,13 @@ impl AudioFile for TaggedFile {
 	}
 }
 
-impl From<BoundTaggedFile> for TaggedFile {
-	fn from(input: BoundTaggedFile) -> Self {
+impl<F> From<BoundTaggedFile<F>> for TaggedFile {
+	fn from(input: BoundTaggedFile<F>) -> Self {
 		input.inner
 	}
 }
 
-/// A variant of [`TaggedFile`] that holds a [`File`] handle, and reflects changes
+/// A variant of [`TaggedFile`] that holds a handle to its original [`FileLike`] buffer, and reflects changes
 /// such as tag removals.
 ///
 /// For example:
@@ -515,12 +514,27 @@ impl From<BoundTaggedFile> for TaggedFile {
 /// assert!(!bound_tagged_file.contains_tag_type(TagType::Id3v2));
 /// # Ok(()) }
 /// ```
-pub struct BoundTaggedFile {
-	inner: TaggedFile,
-	file_handle: File,
+pub struct BoundTaggedFile<F> {
+	pub(crate) inner: TaggedFile,
+	pub(crate) file_handle: F,
 }
 
-impl BoundTaggedFile {
+impl<F> BoundTaggedFile<F> {
+	/// Consume this tagged file and return the internal file "buffer".
+	/// This allows you to reuse the internal file.
+	///
+	/// Any changes that haven't been commited will be discarded once you
+	/// call this function.
+	pub fn into_inner(self) -> F {
+		self.file_handle
+	}
+}
+
+impl<F: FileLike> BoundTaggedFile<F>
+where
+	LoftyError: From<<F as Truncate>::Error>,
+	LoftyError: From<<F as Length>::Error>,
+{
 	/// Create a new [`BoundTaggedFile`]
 	///
 	/// # Errors
@@ -544,7 +558,7 @@ impl BoundTaggedFile {
 	/// let bound_tagged_file = BoundTaggedFile::read_from(file, parse_options)?;
 	/// # Ok(()) }
 	/// ```
-	pub fn read_from(mut file: File, parse_options: ParseOptions) -> Result<Self> {
+	pub fn read_from(mut file: F, parse_options: ParseOptions) -> Result<Self> {
 		let inner = TaggedFile::read_from(&mut file, parse_options)?;
 		file.rewind()?;
 
@@ -588,18 +602,9 @@ impl BoundTaggedFile {
 
 		Ok(())
 	}
-
-	/// Consume this tagged file and return the internal file "buffer".
-	/// This allows you to reuse the internal file.
-	///
-	/// Any changes that haven't been commited will be discarded once you
-	/// call this function.
-	pub fn into_inner(self) -> File {
-		self.file_handle
-	}
 }
 
-impl TaggedFileExt for BoundTaggedFile {
+impl<F> TaggedFileExt for BoundTaggedFile<F> {
 	fn file_type(&self) -> FileType {
 		self.inner.file_type()
 	}
@@ -633,7 +638,7 @@ impl TaggedFileExt for BoundTaggedFile {
 	}
 }
 
-impl AudioFile for BoundTaggedFile {
+impl<T> AudioFile for BoundTaggedFile<T> {
 	type Properties = FileProperties;
 
 	fn read_from<R>(_: &mut R, _: ParseOptions) -> Result<Self>

lofty/src/probe.rs

@@ -4,7 +4,7 @@ use crate::aac::AacFile;
 use crate::ape::ApeFile;
 use crate::config::{ParseOptions, global_options};
 use crate::error::Result;
-use crate::file::{AudioFile, FileType, FileTypeGuessResult, TaggedFile};
+use crate::file::{AudioFile, BoundTaggedFile, FileType, FileTypeGuessResult, TaggedFile};
 use crate::flac::FlacFile;
 use crate::iff::aiff::AiffFile;
 use crate::iff::wav::WavFile;
@@ -19,6 +19,7 @@ use crate::ogg::vorbis::VorbisFile;
 use crate::resolve::custom_resolvers;
 use crate::wavpack::WavPackFile;
 
+use crate::io::FileLike;
 use std::fs::File;
 use std::io::{BufReader, Cursor, Read, Seek, SeekFrom};
 use std::path::Path;
@@ -455,16 +456,20 @@ impl<R: Read + Seek> Probe<R> {
 	/// let parsed_file = probe.read()?;
 	/// # Ok(()) }
 	/// ```
-	pub fn read(mut self) -> Result<TaggedFile> {
+	pub fn read(self) -> Result<TaggedFile> {
+		self.read_inner().map(|(tagged_file, _)| tagged_file)
+	}
+
+	fn read_inner(mut self) -> Result<(TaggedFile, R)> {
 		let reader = &mut self.inner;
 		let options = self.options.unwrap_or_default();
 
 		if !options.read_tags && !options.read_properties {
 			log::warn!("Skipping both tag and property reading, file will be empty");
 		}
 
-		match self.f_ty {
-			Some(f_type) => Ok(match f_type {
+		let tagged_file = match self.f_ty {
+			Some(f_type) => match f_type {
 				FileType::Aac => AacFile::read_from(reader, options)?.into(),
 				FileType::Aiff => AiffFile::read_from(reader, options)?.into(),
 				FileType::Ape => ApeFile::read_from(reader, options)?.into(),
@@ -485,9 +490,42 @@ impl<R: Read + Seek> Probe<R> {
 					let resolver = crate::resolve::lookup_resolver(c);
 					resolver.read_from(reader, options)?
 				},
-			}),
+			},
 			None => err!(UnknownFormat),
-		}
+		};
+
+		Ok((tagged_file, self.inner))
+	}
+}
+
+impl<F: FileLike> Probe<F> {
+	/// Attempts to extract a [`BoundTaggedFile`] from the reader
+	///
+	/// # Errors
+	///
+	/// See [`Self::read()`].
+	///
+	/// # Examples
+	///
+	/// ```rust
+	/// use lofty::file::FileType;
+	/// use lofty::probe::Probe;
+	///
+	/// # fn main() -> lofty::error::Result<()> {
+	/// # let path = "tests/files/assets/minimal/full_test.mp3";
+	/// # let file = std::fs::File::open(path)?;
+	/// let probe = Probe::new(file).guess_file_type()?;
+	///
+	/// let bound_tagged_file = probe.read_bound()?;
+	/// # Ok(()) }
+	/// ```
+	pub fn read_bound(self) -> Result<BoundTaggedFile<F>> {
+		let (tagged_file, file_handle) = self.read_inner()?;
+
+		Ok(BoundTaggedFile {
+			inner: tagged_file,
+			file_handle,
+		})
 	}
 }