EBML: Start parsing \Ebml\Segment\Tags\Tag\Targets

Author: Serial-ATA

Cargo.toml

@@ -55,6 +55,7 @@ needless_return 				   = "allow" # Explicit returns are needed from time to time
 redundant_guards 				   = "allow" # Currently broken for some cases, might enable later
 into_iter_without_iter 		       = "allow" # This is only going to fire on some internal types, doesn't matter much
 struct_excessive_bools 		       = "allow" # I have yet to find one case of this being useful
+struct_field_names                 = "allow"
 
 [workspace.lints.rustdoc]
 broken_intra_doc_links = "deny"

lofty/src/ebml/read/segment_tags.rs

@@ -1,8 +1,9 @@
 use crate::config::ParseOptions;
 use crate::ebml::element_reader::{ElementChildIterator, ElementIdent, ElementReaderYield};
-use crate::ebml::EbmlTag;
+use crate::ebml::{EbmlTag, TargetType};
 use crate::error::Result;
 
+use crate::macros::decode_err;
 use std::io::{Read, Seek};
 
 pub(super) fn read_from<R>(
@@ -32,9 +33,9 @@ where
 	while let Some(child) = children_reader.next()? {
 		match child {
 			ElementReaderYield::Master((ElementIdent::Targets, _size)) => {
-				read_targets(&mut children_reader.children())?
+				let _ = read_targets(&mut children_reader.children())?;
 			},
-			ElementReaderYield::Master((ElementIdent::Tag, _size)) => {
+			ElementReaderYield::Master((ElementIdent::SimpleTag, _size)) => {
 				read_simple_tag(&mut children_reader.children())?
 			},
 			_ => unimplemented!("Unhandled child element in \\Ebml\\Segment\\Tags: {child:?}"),
@@ -44,11 +45,75 @@ where
 	Ok(())
 }
 
-fn read_targets<R>(_children_reader: &mut ElementChildIterator<'_, R>) -> Result<()>
+struct Target {
+	target_type_value: TargetType,
+	target_type: Option<String>,
+	track_uid: Vec<u64>,
+	edition_uid: Vec<u64>,
+	chapter_uid: Vec<u64>,
+	attachment_uid: Vec<u64>,
+}
+
+fn read_targets<R>(children_reader: &mut ElementChildIterator<'_, R>) -> Result<Target>
 where
 	R: Read + Seek,
 {
-	unimplemented!("\\Ebml\\Segment\\Tags\\Targets")
+	let mut target_type_value = None;
+	let mut target_type = None;
+	let mut track_uid = Vec::new();
+	let mut edition_uid = Vec::new();
+	let mut chapter_uid = Vec::new();
+	let mut attachment_uid = Vec::new();
+
+	while let Some(child) = children_reader.next()? {
+		match child {
+			ElementReaderYield::Child((child, size)) => match child.ident {
+				ElementIdent::TargetTypeValue => {
+					target_type_value = Some(children_reader.read_unsigned_int(size.value())?);
+				},
+				ElementIdent::TargetType => {
+					target_type = Some(children_reader.read_string(size.value())?);
+				},
+				ElementIdent::TagTrackUID => {
+					track_uid.push(children_reader.read_unsigned_int(size.value())?);
+				},
+				ElementIdent::TagEditionUID => {
+					edition_uid.push(children_reader.read_unsigned_int(size.value())?);
+				},
+				ElementIdent::TagChapterUID => {
+					chapter_uid.push(children_reader.read_unsigned_int(size.value())?);
+				},
+				ElementIdent::TagAttachmentUID => {
+					attachment_uid.push(children_reader.read_unsigned_int(size.value())?);
+				},
+				_ => unreachable!(
+					"Unhandled child element in \\Ebml\\Segment\\Tags\\Targets: {child:?}"
+				),
+			},
+			ElementReaderYield::Eof => break,
+			_ => {
+				unreachable!("Unhandled child element in \\Ebml\\Segment\\Tags\\Targets: {child:?}")
+			},
+		}
+	}
+
+	let target_type_value = match target_type_value {
+		// Casting the `u64` to `u8` is safe because the value is checked to be within
+		// the range of `TargetType` anyway.
+		Some(value) => TargetType::try_from(value as u8)?,
+		// The spec defines TargetType 50 (Album) as the default value, as it is the most
+		// common grouping level.
+		None => TargetType::Album,
+	};
+
+	Ok(Target {
+		target_type_value,
+		target_type,
+		track_uid,
+		edition_uid,
+		chapter_uid,
+		attachment_uid,
+	})
 }
 
 fn read_simple_tag<R>(_children_reader: &mut ElementChildIterator<'_, R>) -> Result<()>

lofty/src/ebml/tag/mod.rs

@@ -1,5 +1,10 @@
 pub(crate) mod attached_file;
+pub(crate) mod simple_tag;
+pub(crate) mod target_type;
+
 pub use attached_file::*;
+pub use simple_tag::*;
+pub use target_type::*;
 
 use crate::config::WriteOptions;
 use crate::error::LoftyError;

lofty/src/ebml/tag/simple_tag.rs

@@ -0,0 +1,94 @@
+use crate::tag::ItemValue;
+
+/// The language of a [`SimpleTag`] or chapter
+///
+/// Notes:
+///
+/// - ISO-639-2 was the original language code used in Matroska.
+/// - BCP-47 is the newer, **recommended** language option.
+/// - The ISO-639-2 language code allows for an optional country code, so the [Lang] type cannot be used.
+///
+/// [Lang]: crate::tag::items::Lang
+pub enum Language {
+	/// An ISO-639-2 language code
+	Iso639_2(String),
+	/// A BCP-47 language code (recommended)
+	Bcp47(String),
+}
+
+/// The type of content stored in a [`SimpleTag`]
+///
+/// Matroska allows two different types of content to be stored in tags: UTF-8 strings and binary data.
+///
+/// ## Conversions with [`ItemValue`]
+///
+/// A `TagValue` can be converted to and from an [`ItemValue`] with the following conversions:
+///
+/// ### To [`ItemValue`]
+///
+/// - [`TagValue::String`] -> [`ItemValue::Text`]
+/// - [`TagValue::Binary`] -> [`ItemValue::Binary`]
+///
+/// ### From [`ItemValue`]
+///
+/// - [`ItemValue::Text`] | [`ItemValue::Locator`] -> [`TagValue::String`]
+/// - [`ItemValue::Binary`] -> [`TagValue::Binary`]
+pub enum TagValue {
+	/// A UTF-8 string tag value
+	String(String),
+	/// A binary tag value
+	Binary(Vec<u8>),
+}
+
+impl From<TagValue> for ItemValue {
+	fn from(value: TagValue) -> Self {
+		match value {
+			TagValue::String(s) => ItemValue::Text(s),
+			TagValue::Binary(b) => ItemValue::Binary(b),
+		}
+	}
+}
+
+impl From<ItemValue> for TagValue {
+	fn from(value: ItemValue) -> Self {
+		match value {
+			ItemValue::Text(s) | ItemValue::Locator(s) => TagValue::String(s),
+			ItemValue::Binary(b) => TagValue::Binary(b),
+		}
+	}
+}
+
+/// General information about the target
+///
+/// Notes on how `SimpleTag`s work:
+///
+/// - Multiple [`SimpleTag`]s can exist in a file.
+/// - They each describe a single [`Target`].
+///   - This also means that multiple tags can describe the same target.
+/// - They **do not** need to have a value.
+pub struct SimpleTag {
+	/// The name of the tag as it is stored
+	///
+	/// This field can essentially contain anything, but the following conditions are recommended:
+	///
+	/// - It **SHOULD** consist of capital letters, numbers and the underscore character ‘_’.
+	/// - It **SHOULD NOT** contain any space.
+	///
+	/// When in doubt, the [`TagName`] enum can be used, which covers all specified tags.
+	pub name: String,
+	/// The language of the tag
+	///
+	/// See [`Language`] for more information.
+	pub language: Option<Language>,
+	/// Whether [`language`] is the default/original langauge to use
+	///
+	/// This is used when multiple languages are present in a file. This field will be ignored
+	/// if [`language`] is `None`.
+	///
+	/// [`language`]: #structfield.language
+	pub default: bool,
+	/// The actual tag value
+	///
+	/// For more information, see [`TagValue`]
+	pub value: Option<TagValue>,
+}

lofty/src/ebml/tag/target_type.rs

@@ -0,0 +1,54 @@
+use crate::error::{LoftyError, Result};
+use crate::macros::decode_err;
+
+/// The type of the target.
+///
+/// This is used to determine the type of the target that the tag is applied to.
+#[repr(u8)]
+#[non_exhaustive]
+#[derive(Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord)]
+pub enum TargetType {
+	/// For video, this represents: SHOT
+	Shot = 10,
+	/// This is used to represent the following:
+	///
+	/// - Audio: SUBTRACK / PART / MOVEMENT
+	/// - Video: SCENE
+	Scene = 20,
+	/// This is used to represent the following:
+	///
+	/// - Audio: TRACK / SONG
+	/// - Video: CHAPTER
+	Track = 30,
+	/// For both audio and video, this represents: PART / SESSION
+	Part = 40,
+	/// This is used to represent the following:
+	///
+	/// - Audio: ALBUM / OPERA / CONCERT
+	/// - Video: MOVIE / EPISODE / CONCERT
+	Album = 50,
+	/// This is used to represent the following:
+	///
+	/// - Audio: EDITION / ISSUE / VOLUME / OPUS
+	/// - Video: SEASON / SEQUEL / VOLUME
+	Edition = 60,
+	/// For both audio and video, this represents: COLLECTION
+	Collection = 70,
+}
+
+impl TryFrom<u8> for TargetType {
+	type Error = LoftyError;
+
+	fn try_from(value: u8) -> Result<Self> {
+		match value {
+			10 => Ok(Self::Shot),
+			20 => Ok(Self::Scene),
+			30 => Ok(Self::Track),
+			40 => Ok(Self::Part),
+			50 => Ok(Self::Album),
+			60 => Ok(Self::Edition),
+			70 => Ok(Self::Collection),
+			_ => decode_err!(@BAIL Ebml, "TargetType value out of range"),
+		}
+	}
+}