The great Lofty module refactor

CHANGELOG.md

@@ -18,10 +18,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `ChannelMask::from_{mp4, opus}_channels`
 - **Opus**: `OpusProperties` now contains the channel mask
 - **AAC**: `AacProperties` now contains the channel mask
+- **Prelude**: `lofty::prelude` module to make trait imports easier ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374))
 
 ### Changed
 - **Properties**: `FileProperties` and `ChannelMask` have been moved from the root to the new `lofty::properties`
                    module ([PR](https://github.com/Serial-ATA/lofty-rs/pull/372))
+- **ParseOptions**/**WriteOptions**/**GlobalOptions**:
+  - ⚠️ Important ⚠️: Moved to `lofty::options` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374))
+- **AudioFile**/**TaggedFileExt**/**TaggedFile**/**BoundTaggedFile**:
+  - ⚠️ Important ⚠️: Moved to `lofty::file` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374))
+- **Tag**:
+    - ⚠️ Important ⚠️- The following items have been moved to `lofty::tag` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374)):
+      - `Tag`
+      - `Accessor`
+      - `TagType`
+      - `TagItem`
+      - `ItemKey`
+      - `ItemValue`
+- **Probe**:
+    - ⚠️ Important ⚠️- Moved to `lofty::probe` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374)):
+- **Picture**:
+    - ⚠️ Important ⚠️- The following items have been moved to `lofty::picture` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/374)):
+      - `Picture`
+      - `PictureType`
+      - `PictureInformation`
+      - `MimeType`
 
 ### Fixed
 - **Vorbis**: Fix panic when reading properties of zero-length files ([issue](https://github.com/Serial-ATA/lofty-rs/issues/342)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/365))

benches/create_tag.rs

@@ -1,11 +1,13 @@
 use lofty::ape::ApeTag;
+use lofty::config::WriteOptions;
 use lofty::id3::v1::Id3v1Tag;
 use lofty::id3::v2::Id3v2Tag;
 use lofty::iff::aiff::AIFFTextChunks;
 use lofty::iff::wav::RIFFInfoList;
 use lofty::mp4::Ilst;
 use lofty::ogg::VorbisComments;
-use lofty::{Accessor, MimeType, Picture, PictureType, TagExt, WriteOptions};
+use lofty::picture::{MimeType, Picture, PictureType};
+use lofty::tag::{Accessor, TagExt};
 
 use iai_callgrind::{library_benchmark, library_benchmark_group, main};
 
@@ -36,7 +38,7 @@ bench_tag_write!([
 	(aiff_text_chunks, AIFFTextChunks, |tag| {}),
 	(apev2, ApeTag, |tag| {
 		use lofty::ape::ApeItem;
-		use lofty::ItemValue;
+		use lofty::tag::ItemValue;
 
 		let picture = Picture::new_unchecked(
 			PictureType::CoverFront,

benches/read_file.rs

@@ -1,4 +1,5 @@
-use lofty::{ParseOptions, Probe};
+use lofty::config::ParseOptions;
+use lofty::probe::Probe;
 
 use iai_callgrind::{library_benchmark, library_benchmark_group, main};
 

examples/custom_resolver/src/main.rs

@@ -1,9 +1,11 @@
 use lofty::ape::ApeTag;
+use lofty::config::{GlobalOptions, ParseOptions};
 use lofty::error::Result as LoftyResult;
+use lofty::file::FileType;
 use lofty::id3::v2::Id3v2Tag;
 use lofty::properties::FileProperties;
 use lofty::resolve::FileResolver;
-use lofty::{FileType, GlobalOptions, ParseOptions, TagType};
+use lofty::tag::TagType;
 use lofty_attr::LoftyFile;
 
 use std::fs::File;
@@ -95,7 +97,7 @@ fn main() {
 	// By default, lofty will not check for custom files.
 	// We can enable this by updating our `GlobalOptions`.
 	let global_options = GlobalOptions::new().use_custom_resolvers(true);
-	lofty::apply_global_options(global_options);
+	lofty::config::apply_global_options(global_options);
 
 	// Now when using the following functions, your custom file will be checked
 

examples/tag_reader.rs

@@ -1,4 +1,6 @@
-use lofty::{Accessor, AudioFile, Probe, TaggedFileExt};
+use lofty::prelude::*;
+use lofty::probe::Probe;
+
 use std::path::Path;
 
 fn main() {
@@ -31,8 +33,7 @@ fn main() {
 	// import keys from https://docs.rs/lofty/latest/lofty/enum.ItemKey.html
 	println!(
 		"Album Artist: {}",
-		tag.get_string(&lofty::ItemKey::AlbumArtist)
-			.unwrap_or("None")
+		tag.get_string(&ItemKey::AlbumArtist).unwrap_or("None")
 	);
 
 	let properties = tagged_file.properties();

examples/tag_stripper.rs

@@ -1,4 +1,6 @@
-use lofty::{Probe, TaggedFileExt};
+use lofty::file::TaggedFileExt;
+use lofty::probe::Probe;
+
 use std::io::Write;
 
 fn main() {

examples/tag_writer.rs

@@ -1,4 +1,7 @@
-use lofty::{Accessor, Probe, Tag, TagExt, TaggedFileExt, WriteOptions};
+use lofty::config::WriteOptions;
+use lofty::prelude::*;
+use lofty::probe::Probe;
+use lofty::tag::Tag;
 
 use structopt::StructOpt;
 

lofty_attr/src/internal.rs

@@ -78,10 +78,10 @@ pub(crate) fn init_write_lookup(
 
 	insert!(map, AiffText, {
 		lofty::iff::aiff::tag::AiffTextChunksRef {
-			name: tag.get_string(&lofty::tag::item::ItemKey::TrackTitle),
-			author: tag.get_string(&lofty::tag::item::ItemKey::TrackArtist),
-			copyright: tag.get_string(&lofty::tag::item::ItemKey::CopyrightMessage),
-			annotations: Some(tag.get_strings(&lofty::tag::item::ItemKey::Comment)),
+			name: tag.get_string(&lofty::prelude::ItemKey::TrackTitle),
+			author: tag.get_string(&lofty::prelude::ItemKey::TrackArtist),
+			copyright: tag.get_string(&lofty::prelude::ItemKey::CopyrightMessage),
+			annotations: Some(tag.get_strings(&lofty::prelude::ItemKey::Comment)),
 			comments: None,
 		}
 		.write_to(data, write_options)
@@ -96,11 +96,12 @@ pub(crate) fn write_module(
 ) -> proc_macro2::TokenStream {
 	let applicable_formats = fields.iter().map(|f| {
 		let tag_ty =
-			syn::parse_str::<syn::Path>(&format!("::lofty::TagType::{}", &f.tag_type)).unwrap();
+			syn::parse_str::<syn::Path>(&format!("::lofty::tag::TagType::{}", &f.tag_type))
+				.unwrap();
 
 		let cfg_features = f.get_cfg_features();
 
-		let block = lookup.get(&*tag_ty.segments[2].ident.to_string()).unwrap();
+		let block = lookup.get(&*tag_ty.segments[3].ident.to_string()).unwrap();
 
 		quote! {
 			#( #cfg_features )*
@@ -111,7 +112,7 @@ pub(crate) fn write_module(
 	quote! {
 		pub(crate) mod write {
 			#[allow(unused_variables)]
-			pub(crate) fn write_to(data: &mut ::std::fs::File, tag: &::lofty::Tag, write_options: ::lofty::WriteOptions) -> ::lofty::error::Result<()> {
+			pub(crate) fn write_to(data: &mut ::std::fs::File, tag: &::lofty::tag::Tag, write_options: ::lofty::config::WriteOptions) -> ::lofty::error::Result<()> {
 				match tag.tag_type() {
 					#( #applicable_formats )*
 					_ => crate::macros::err!(UnsupportedTag),

lofty_attr/src/lofty_file.rs

@@ -178,7 +178,7 @@ impl LoftyFile {
 				let name = format_ident!("_AssertTagExt{}", i);
 				let field_ty = &f.ty;
 				quote_spanned! {field_ty.span()=>
-					struct #name where #field_ty: lofty::TagExt;
+					struct #name where #field_ty: ::lofty::prelude::TagExt;
 				}
 			});
 
@@ -435,18 +435,18 @@ fn generate_audiofile_impl(file: &LoftyFile) -> syn::Result<proc_macro2::TokenSt
 	let struct_name = &file.struct_info.name;
 	let ret = quote! {
 		#assert_properties_impl
-		impl ::lofty::AudioFile for #struct_name {
+		impl ::lofty::prelude::AudioFile for #struct_name {
 			type Properties = #properties_field_ty;
 
-			fn read_from<R>(reader: &mut R, parse_options: ::lofty::ParseOptions) -> ::lofty::error::Result<Self>
+			fn read_from<R>(reader: &mut R, parse_options: ::lofty::config::ParseOptions) -> ::lofty::error::Result<Self>
 			where
 				R: std::io::Read + std::io::Seek,
 			{
 				#read_fn(reader, parse_options)
 			}
 
-			fn save_to(&self, file: &mut ::std::fs::File, write_options: ::lofty::WriteOptions) -> ::lofty::error::Result<()> {
-				use ::lofty::TagExt as _;
+			fn save_to(&self, file: &mut ::std::fs::File, write_options: ::lofty::config::WriteOptions) -> ::lofty::error::Result<()> {
+				use ::lofty::tag::TagExt as _;
 				use ::std::io::Seek as _;
 				#save_to_body
 			}
@@ -461,9 +461,9 @@ fn generate_audiofile_impl(file: &LoftyFile) -> syn::Result<proc_macro2::TokenSt
 			}
 
 			#[allow(unreachable_code, unused_variables)]
-			fn contains_tag_type(&self, tag_type: ::lofty::TagType) -> bool {
+			fn contains_tag_type(&self, tag_type: ::lofty::tag::TagType) -> bool {
 				match tag_type {
-					#( ::lofty::TagType::#tag_type => { #tag_exists_2 } ),*
+					#( ::lofty::tag::TagType::#tag_type => { #tag_exists_2 } ),*
 					_ => false
 				}
 			}
@@ -523,23 +523,23 @@ fn generate_from_taggedfile_impl(file: &LoftyFile) -> proc_macro2::TokenStream {
 
 	let file_type = &file.file_type;
 	let file_type_variant = if file.internal_details.has_internal_file_type {
-		quote! { ::lofty::FileType::#file_type }
+		quote! { ::lofty::file::FileType::#file_type }
 	} else {
 		let file_ty_str = file_type.to_string();
-		quote! { ::lofty::FileType::Custom(#file_ty_str) }
+		quote! { ::lofty::file::FileType::Custom(#file_ty_str) }
 	};
 
 	let struct_name = &file.struct_info.name;
 	quote! {
-		impl ::std::convert::From<#struct_name> for ::lofty::TaggedFile {
+		impl ::std::convert::From<#struct_name> for ::lofty::file::TaggedFile {
 			fn from(input: #struct_name) -> Self {
-				use ::lofty::TaggedFileExt as _;
+				use ::lofty::prelude::TaggedFileExt as _;
 
-				::lofty::TaggedFile::new(
+				::lofty::file::TaggedFile::new(
 					#file_type_variant,
 					::lofty::properties::FileProperties::from(input.properties),
 					{
-						let mut tags: Vec<::lofty::Tag> = Vec::new();
+						let mut tags: Vec<::lofty::tag::Tag> = Vec::new();
 						#( #conditions )*
 
 						tags

lofty_attr/src/lofty_tag.rs

@@ -83,12 +83,12 @@ impl LoftyTag {
 			#input
 
 			impl #ident {
-				pub(crate) const SUPPORTED_FORMATS: &'static [::lofty::FileType] = &[
-					#( ::lofty::FileType:: #flattened_file_types ),*
+				pub(crate) const SUPPORTED_FORMATS: &'static [::lofty::file::FileType] = &[
+					#( ::lofty::file::FileType:: #flattened_file_types ),*
 				];
 
-				pub(crate) const READ_ONLY_FORMATS: &'static [::lofty::FileType] = &[
-					#( ::lofty::FileType:: #read_only_file_types ),*
+				pub(crate) const READ_ONLY_FORMATS: &'static [::lofty::file::FileType] = &[
+					#( ::lofty::file::FileType:: #read_only_file_types ),*
 				];
 			}
 		})

src/aac/header.rs

@@ -1,8 +1,8 @@
+use crate::config::ParsingMode;
 use crate::error::Result;
 use crate::macros::decode_err;
 use crate::mp4::{AudioObjectType, SAMPLE_RATES};
 use crate::mpeg::MpegVersion;
-use crate::probe::ParsingMode;
 
 use std::io::{Read, Seek, SeekFrom};
 

src/aac/read.rs

@@ -1,12 +1,12 @@
 use super::header::{ADTSHeader, HEADER_MASK};
 use super::AacFile;
+use crate::config::{ParseOptions, ParsingMode};
 use crate::error::Result;
 use crate::id3::v2::header::Id3v2Header;
 use crate::id3::v2::read::parse_id3v2;
 use crate::id3::{find_id3v1, ID3FindResults};
 use crate::macros::{decode_err, parse_mode_choice};
 use crate::mpeg::header::{cmp_header, search_for_frame_sync, HeaderCmpResult};
-use crate::probe::{ParseOptions, ParsingMode};
 
 use std::io::{Read, Seek, SeekFrom};
 

src/ape/header.rs

@@ -1,6 +1,6 @@
 use crate::error::Result;
 use crate::macros::decode_err;
-use crate::traits::SeekStreamLen;
+use crate::util::io::SeekStreamLen;
 
 use std::io::{Read, Seek, SeekFrom};
 use std::ops::Neg;
@@ -44,8 +44,7 @@ where
 		size = size.saturating_add(32);
 	}
 
-	#[allow(unstable_name_collisions)]
-	if u64::from(size) > data.stream_len()? {
+	if u64::from(size) > data.stream_len_hack()? {
 		decode_err!(@BAIL Ape, "APE tag has an invalid size (> file size)");
 	}
 

src/ape/properties.rs

@@ -1,6 +1,6 @@
+use crate::config::ParsingMode;
 use crate::error::Result;
 use crate::macros::decode_err;
-use crate::probe::ParsingMode;
 use crate::properties::FileProperties;
 
 use std::io::{Read, Seek, SeekFrom};

src/ape/read.rs

@@ -2,13 +2,13 @@ use super::header::read_ape_header;
 use super::tag::ApeTag;
 use super::{ApeFile, ApeProperties};
 use crate::ape::tag::read::{read_ape_tag, read_ape_tag_with_header};
+use crate::config::ParseOptions;
 use crate::error::Result;
 use crate::id3::v1::tag::Id3v1Tag;
 use crate::id3::v2::read::parse_id3v2;
 use crate::id3::v2::tag::Id3v2Tag;
 use crate::id3::{find_id3v1, find_id3v2, find_lyrics3v2, FindId3v2Config, ID3FindResults};
 use crate::macros::decode_err;
-use crate::probe::ParseOptions;
 
 use std::io::{Read, Seek, SeekFrom};
 

src/ape/tag/item.rs

@@ -1,8 +1,8 @@
 use crate::ape::constants::INVALID_KEYS;
 use crate::error::{LoftyError, Result};
 use crate::macros::decode_err;
-use crate::tag::item::{ItemValue, ItemValueRef, TagItem};
-use crate::tag::TagType;
+use crate::tag::item::ItemValueRef;
+use crate::tag::{ItemValue, TagItem, TagType};
 
 /// Represents an `APE` tag item
 ///