Probe: Add minimal ParseOptions

CHANGELOG.md

@@ -7,10 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `ParseOptions`:
+  - ⚠️ Important ⚠️: This update introduces `ParseOptions` to allow for finer grained control over error
+      eagerness and other settings. Previously, when reading a file the only option available was
+      `read_properties`, specified with a `bool` in `read_from{_path}`. This will now default to `true`,
+      and can be overridden when using `Probe`.
 - **FileProperties**: `FileProperties::new`
 
 ### Changed
 - **ID3v2**: Frame/tag flags with optional additional data are now `Option<T>` instead of `(bool, T)`
+- `read_from{_path}` will no longer take a `bool` for reading properties, and will do it by default. To
+  change this behavior, you must now use `Probe`.
 
 ## [0.8.1] - 2022-09-09
 

Cargo.toml

@@ -19,7 +19,7 @@ byteorder = "1.4.3"
 cfg-if = "1.0.0"
 # ID3 compressed frames
 flate2 = { version = "1.0.24", optional = true }
-lofty_attr = "0.3.0"
+lofty_attr = { path = "lofty_attr" }
 # OGG Vorbis/Opus
 ogg_pager = "0.3.2"
 # Key maps
@@ -62,4 +62,4 @@ path = "examples/custom_resolver/src/main.rs"
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "docsrs"]
+rustdoc-args = ["--cfg", "docsrs"]

benches/read_file.rs

@@ -1,4 +1,4 @@
-use lofty::Probe;
+use lofty::{ParseOptions, Probe};
 
 use criterion::{criterion_group, criterion_main, Criterion};
 
@@ -15,9 +15,10 @@ macro_rules! test_read_file {
 				stringify!($NAME),
 				|b| b.iter(|| {
 					Probe::new(Cursor::new($NAME))
+					.options(ParseOptions::new())
 					.guess_file_type()
 					.unwrap()
-					.read(true)
+					.read()
 					.unwrap()
 				})
 			);

examples/custom_resolver/src/main.rs

@@ -2,7 +2,7 @@ use lofty::ape::ApeTag;
 use lofty::error::Result as LoftyResult;
 use lofty::id3::v2::ID3v2Tag;
 use lofty::resolve::FileResolver;
-use lofty::{FileProperties, FileType, TagType};
+use lofty::{FileProperties, FileType, ParseOptions, TagType};
 use lofty_attr::LoftyFile;
 use std::fs::File;
 
@@ -17,30 +17,30 @@ use std::fs::File;
 #[lofty(file_type = "Custom(\"MyFile\")")]
 struct MyFile {
 	// A file has two requirements, at least one tag field, and a properties field.
-	
+
 	// Tag field requirements:
 	// * Fields *must* end with "_tag" to set them apart from the others.
 	// * The type of the field *must* implement `TagExt`
-	
-	
+
+
 	// Specify a tag type
 	#[lofty(tag_type = "ID3v2")]
 	// Let's say our file *always* has an ID3v2Tag present,
 	// we can indicate that with this.
 	#[lofty(always_present)]
 	pub id3v2_tag: ID3v2Tag,
-	
+
 	// Our APE tag is optional in this format, so we wrap it in an `Option`
 	#[lofty(tag_type = "APE")]
 	pub ape_tag: Option<ApeTag>,
-	
+
 	// The properties field *must* be present and named as such.
 	// The only requirement for this field is that the type *must* implement `Into<FileProperties>`.
 	pub properties: FileProperties,
 }
 
 impl MyFile {
-	pub fn parse_my_file<R>(_reader: &mut R, _read_properties: bool) -> LoftyResult<Self>
+	pub fn parse_my_file<R>(_reader: &mut R, _parse_options: ParseOptions) -> LoftyResult<Self>
 	where
 		R: std::io::Read + std::io::Seek,
 	{
@@ -97,10 +97,10 @@ fn main() {
 	let path = "examples/custom_resolver/test_asset.myfile";
 
 	// Detected from the "myfile" extension
-	let _ = lofty::read_from_path(path, true).unwrap();
+	let _ = lofty::read_from_path(path).unwrap();
 
 	let mut file = File::open(path).unwrap();
 
 	// The file's content starts with "myfiledata"
-	let _ = lofty::read_from(&mut file, true).unwrap();
+	let _ = lofty::read_from(&mut file).unwrap();
 }

examples/tag_reader.rs

@@ -11,7 +11,7 @@ fn main() {
 
 	let tagged_file = Probe::open(path)
 		.expect("ERROR: Bad path provided!")
-		.read(true)
+		.read()
 		.expect("ERROR: Failed to read file!");
 
 	let tag = match tagged_file.primary_tag() {

examples/tag_stripper.rs

@@ -6,7 +6,7 @@ fn main() {
 
 	let tagged_file = Probe::open(path.as_str())
 		.expect("ERROR: Bad path provided!")
-		.read(false)
+		.read()
 		.expect("ERROR: Failed to read file!");
 
 	let tags = tagged_file.tags();

examples/tag_writer.rs

@@ -28,7 +28,7 @@ fn main() {
 
 	let mut tagged_file = Probe::open(&opt.path)
 		.expect("ERROR: Bad path provided!")
-		.read(false)
+		.read()
 		.expect("ERROR: Failed to read file!");
 
 	let tag = match tagged_file.primary_tag_mut() {

fuzz/fuzz_targets/aifffile_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::iff::AiffFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::iff::AiffFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/apefile_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::ape::ApeFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::ape::ApeFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/flacfile_read_from.rs

@@ -3,8 +3,11 @@
 use std::io::Cursor;
 
 use libfuzzer_sys::fuzz_target;
-use lofty::AudioFile;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-	let _ = lofty::flac::FlacFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::flac::FlacFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/mp4file_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::mp4::Mp4File::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::mp4::Mp4File::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/mpegfile_read_from.rs

@@ -3,8 +3,11 @@
 use std::io::Cursor;
 
 use libfuzzer_sys::fuzz_target;
-use lofty::AudioFile;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-	let _ = lofty::mpeg::MPEGFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::mpeg::MPEGFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/opusfile_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::ogg::OpusFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::ogg::OpusFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/speexfile_read_from.rs

@@ -3,8 +3,11 @@
 use std::io::Cursor;
 
 use libfuzzer_sys::fuzz_target;
-use lofty::AudioFile;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-	let _ = lofty::ogg::SpeexFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::ogg::SpeexFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/vorbisfile_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::ogg::VorbisFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::ogg::VorbisFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/wavfile_read_from.rs

@@ -2,9 +2,12 @@
 
 use std::io::Cursor;
 
-use lofty::AudioFile;
 use libfuzzer_sys::fuzz_target;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-    let _ = lofty::iff::WavFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::iff::WavFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

fuzz/fuzz_targets/wavpackfile_read_from.rs

@@ -3,8 +3,11 @@
 use std::io::Cursor;
 
 use libfuzzer_sys::fuzz_target;
-use lofty::AudioFile;
+use lofty::{AudioFile, ParseOptions};
 
 fuzz_target!(|data: Vec<u8>| {
-	let _ = lofty::wavpack::WavPackFile::read_from(&mut Cursor::new(data), false);
+	let _ = lofty::wavpack::WavPackFile::read_from(
+		&mut Cursor::new(data),
+		ParseOptions::new().read_properties(false),
+	);
 });

lofty_attr/src/lib.rs

@@ -130,11 +130,11 @@ fn parse(input: DeriveInput, errors: &mut Vec<syn::Error>) -> proc_macro2::Token
 			impl lofty::AudioFile for #struct_name {
 				type Properties = #properties_field_ty;
 
-				fn read_from<R>(reader: &mut R, read_properties: bool) -> lofty::error::Result<Self>
+				fn read_from<R>(reader: &mut R, parse_options: lofty::ParseOptions) -> lofty::error::Result<Self>
 				where
 					R: std::io::Read + std::io::Seek,
 				{
-					#read_fn(reader, read_properties)
+					#read_fn(reader, parse_options)
 				}
 
 				fn properties(&self) -> &Self::Properties {

src/ape/read.rs

@@ -10,10 +10,11 @@ use crate::id3::v1::tag::ID3v1Tag;
 use crate::id3::v2::{read::parse_id3v2, tag::ID3v2Tag};
 use crate::id3::{find_id3v1, find_id3v2, find_lyrics3v2, ID3FindResults};
 use crate::macros::decode_err;
+use crate::probe::ParseOptions;
 
 use std::io::{Read, Seek, SeekFrom};
 
-pub(crate) fn read_from<R>(data: &mut R, read_properties: bool) -> Result<ApeFile>
+pub(crate) fn read_from<R>(data: &mut R, parse_options: ParseOptions) -> Result<ApeFile>
 where
 	R: Read + Seek,
 {
@@ -155,7 +156,7 @@ where
 		id3v2_tag,
 		#[cfg(feature = "ape")]
 		ape_tag,
-		properties: if read_properties {
+		properties: if parse_options.read_properties {
 			super::properties::read_properties(data, stream_len, file_length)?
 		} else {
 			ApeProperties::default()