ot_tools_io/

traits.rs

/*
SPDX-License-Identifier: GPL-3.0-or-later
Copyright © 2024 Mike Robeson [dijksterhuis]
*/

use crate::RBoxErr;
use serde::{Deserialize, Serialize};
use serde_big_array::Array;
use std::array::from_fn;
use std::fmt::Debug;
use std::fs::File;
use std::io::{Read, Write};
use std::path::Path;

#[doc(hidden)]
/// Read bytes from a file at `path`.
/// ```rust
/// let fpath = std::path::PathBuf::from("test-data")
///     .join("blank-project")
///     .join("bank01.work");
/// let r = ot_tools_io::read_bin_file(&fpath);
/// assert!(r.is_ok());
/// assert_eq!(r.unwrap().len(), 636113);
/// ```
pub fn read_bin_file(path: &Path) -> RBoxErr<Vec<u8>> {
    let mut infile = File::open(path)?;
    let mut bytes: Vec<u8> = vec![];
    let _: usize = infile.read_to_end(&mut bytes)?;
    Ok(bytes)
}

#[doc(hidden)]
/// Write bytes to a file at `path`.
/// ```rust
/// use std::env::temp_dir;
/// use std::array::from_fn;
///
/// let arr: [u8; 27] = from_fn(|_| 0);
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("write_bin_file.example");
///
/// # use std::fs::create_dir_all;
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
/// let r = ot_tools_io::write_bin_file(&arr, &fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn write_bin_file(bytes: &[u8], path: &Path) -> RBoxErr<()> {
    let mut file: File = File::create(path)?;
    file.write_all(bytes)?;
    Ok(())
}

#[doc(hidden)]
/// Read a file at `path` as a string.
/// ```
/// let fpath = std::path::PathBuf::from("test-data")
///     .join("blank-project")
///     .join("bank01.work");
/// let r = ot_tools_io::read_bin_file(&fpath);
/// assert!(r.is_ok());
/// assert_eq!(r.unwrap().len(), 636113);
/// ```
pub fn read_str_file(path: &Path) -> RBoxErr<String> {
    let mut file = File::open(path)?;
    let mut string = String::new();
    let _ = file.read_to_string(&mut string)?;
    Ok(string)
}

#[doc(hidden)]
/// Write a string to a file at `path`.
/// ```rust
/// use std::env::temp_dir;
///
/// let data = "abcd".to_string();
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("write_str_file.example");
///
/// # use std::fs::create_dir_all;
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
/// let r = ot_tools_io::write_str_file(&data, &fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn write_str_file(string: &str, path: &Path) -> RBoxErr<()> {
    let mut file: File = File::create(path)?;
    write!(file, "{string}")?;
    Ok(())
}

/// Convenience [super trait](https://doc.rust-lang.org/book/ch20-02-advanced-traits.html#using-supertraits)
/// for types which directly correspond to Elektron Octatrack binary data files.
/// Use in trait bounds to require a type have [`Decode`], [`Encode`],
/// [`Serialize`] and [`Deserialize`] implementations.
pub trait OctatrackFileIO: Decode + Encode + Serialize + for<'a> Deserialize<'a> {
    fn repr(&self, newlines: Option<bool>) -> RBoxErr<()>
    where
        Self: Debug,
    {
        if newlines.unwrap_or(true) {
            println!("{self:#?}")
        } else {
            println!("{self:?}")
        };
        Ok(())
    }
    // BYTES
    /// Read type from an Octatrack data file at path
    /// ```rust
    /// # use std::path::PathBuf;
    /// # let path = PathBuf::from("test-data").join("blank-project").join("bank01.work");
    /// use ot_tools_io::{BankFile, OctatrackFileIO};
    /// let bank = BankFile::from_data_file(&path).unwrap();
    /// assert_eq!(bank.datatype_version, 23);
    /// ```
    fn from_data_file(path: &Path) -> RBoxErr<Self> {
        let bytes = read_bin_file(path)?;
        let data = Self::from_bytes(&bytes)?;
        Ok(data)
    }
    /// Read type from bytes
    fn from_bytes(bytes: &[u8]) -> RBoxErr<Self> {
        let x = Self::decode(bytes)?;
        Ok(x)
    }
    /// Write type to an Octatrack data file at path
    /// ```rust
    /// # use std::{path::PathBuf, fs::create_dir_all, env::temp_dir};
    /// # let path = temp_dir()
    /// #    .join("ot-tools-io")
    /// #    .join("doctest")
    /// #    .join("to_bytes_file.bank.work");
    /// # create_dir_all(&path.parent().unwrap()).unwrap();
    /// #
    /// use ot_tools_io::{OctatrackFileIO, BankFile};
    /// let r = BankFile::default().to_data_file(&path);
    /// assert!(r.is_ok());
    /// assert!(path.exists());
    /// ```
    fn to_data_file(&self, path: &Path) -> RBoxErr<()> {
        let bytes = Self::to_bytes(self)?;
        write_bin_file(&bytes, path)?;
        Ok(())
    }
    /// Create bytes from type
    fn to_bytes(&self) -> RBoxErr<Vec<u8>> {
        self.encode()
    }
    // YAML
    /// Read type from a YAML file at path
    /// ```rust
    /// # use std::path::PathBuf;
    /// # let path = PathBuf::from("test-data").join("bank").join("default.yaml");
    /// use ot_tools_io::{BankFile, OctatrackFileIO};
    /// let bank = BankFile::from_yaml_file(&path).unwrap();
    /// assert_eq!(bank.datatype_version, 23);
    /// ```
    fn from_yaml_file(path: &Path) -> RBoxErr<Self> {
        let string = read_str_file(path)?;
        let data = Self::from_yaml_str(&string)?;
        Ok(data)
    }
    /// Read type from YAML string
    fn from_yaml_str(yaml: &str) -> RBoxErr<Self> {
        let x = serde_yml::from_str(yaml)?;
        Ok(x)
    }
    /// Write type to a YAML file at path
    /// ```rust
    /// # use std::{path::PathBuf, fs::create_dir_all, env::temp_dir};
    /// # let path = temp_dir()
    /// #    .join("ot-tools-io")
    /// #    .join("doctest")
    /// #    .join("to_bytes_file.bank.yaml");
    /// # create_dir_all(&path.parent().unwrap()).unwrap();
    /// #
    /// use ot_tools_io::{OctatrackFileIO, BankFile};
    /// let r = BankFile::default().to_yaml_file(&path);
    /// assert!(r.is_ok());
    /// assert!(path.exists());
    /// ```
    fn to_yaml_file(&self, path: &Path) -> RBoxErr<()> {
        let yaml = Self::to_yaml_string(self)?;
        write_str_file(&yaml, path)?;
        Ok(())
    }
    /// Create YAML string from type
    /// ```rust
    /// use ot_tools_io::{BankFile, OctatrackFileIO};
    /// let bank = BankFile::default().to_yaml_string().unwrap();
    /// assert_eq!(bank.len(), 12578424);
    /// assert_eq!(bank[0..15], "header:\n- 70\n- ".to_string());
    /// ```
    fn to_yaml_string(&self) -> RBoxErr<String> {
        Ok(serde_yml::to_string(self)?)
    }
    // JSON
    /// Read type from a JSON file at path
    fn from_json_file(path: &Path) -> RBoxErr<Self> {
        let string = read_str_file(path)?;
        let data = Self::from_yaml_str(&string)?;
        Ok(data)
    }
    /// Create type from JSON string
    fn from_json_str(json: &str) -> RBoxErr<Self> {
        Ok(serde_json::from_str::<Self>(json)?)
    }
    /// Write type to a JSON file at path
    /// ```rust
    /// # use std::{path::PathBuf, fs::create_dir_all, env::temp_dir};
    /// # let path = temp_dir()
    /// #    .join("ot-tools-io")
    /// #    .join("doctest")
    /// #    .join("to_bytes_file.bank.json");
    /// # create_dir_all(&path.parent().unwrap()).unwrap();
    /// #
    /// use ot_tools_io::{OctatrackFileIO, BankFile};
    /// let r = BankFile::default().to_json_file(&path);
    /// assert!(r.is_ok());
    /// assert!(path.exists());
    /// ```
    fn to_json_file(&self, path: &Path) -> RBoxErr<()> {
        let yaml = Self::to_json_string(self)?;
        write_str_file(&yaml, path)?;
        Ok(())
    }
    /// Create JSON string from type
    /// ```rust
    /// use ot_tools_io::{BankFile, OctatrackFileIO};
    /// let json = BankFile::default().to_json_string().unwrap();
    /// assert_eq!(json.len(), 7807763);
    /// assert_eq!(json[0..15], "{\"header\":[70,7".to_string());
    /// ```
    fn to_json_string(&self) -> RBoxErr<String> {
        Ok(serde_json::to_string(&self)?)
    }
}

/// Trait to convert between Enum option instances and their corresponding value.
/// ```
/// use std::error::Error;
/// use ot_tools_io::OptionEnumValueConvert;
///
/// #[derive(std::fmt::Debug, PartialEq, Copy, Clone)]
/// enum SomeThing {
///     X = 0,
///     Y = 19473295,
/// }
///
/// impl OptionEnumValueConvert<u32> for SomeThing {
///
///     fn from_value(v: &u32) -> Result<Self, Box<dyn Error>> {
///         match v {
///             0 => Ok(Self::X),
///             19473295 => Ok(Self::Y),
///             _ => Err(ot_tools_io::OtToolsIoErrors::NoMatchingOptionEnumValue.into())
///         }
///     }
///     fn value(&self) -> Result<u32, Box<dyn Error>> {
///         Ok(*self as u32)
///     }
/// }
///
/// assert_eq!(SomeThing::X.value().unwrap(), 0);
/// assert_eq!(SomeThing::Y.value().unwrap(), 19473295);
/// assert_eq!(SomeThing::from_value(&0).unwrap(), SomeThing::X);
/// assert_eq!(SomeThing::from_value(&19473295).unwrap(), SomeThing::Y);
/// assert!(SomeThing::from_value(&100).is_err());
/// assert!(SomeThing::from_value(&200).is_err());
/// ```
pub trait OptionEnumValueConvert<V> {
    /// Get an Enum instance from some value.
    fn from_value(v: &V) -> RBoxErr<Self>
    where
        Self: Sized;

    /// Get a numeric value for an Enum instance.
    fn value(&self) -> RBoxErr<V>;
}

/// Adds deserialisation via [`bincode`] and [`serde`] to a type.
/// Must be present on all major file types.
/// ```
/// use std::error::Error;
/// use ot_tools_io::Decode;
///
/// #[derive(serde::Deserialize, std::fmt::Debug, PartialEq)]
/// struct SomeType {
///     x: u8,
///     y: u32,
/// }
///
/// // default implementation
/// impl Decode for SomeType {}
///
/// let bytes: Vec<u8> = vec![8, 127, 95, 245, 1];
/// let decoded = SomeType::decode(&bytes).unwrap();
///
/// assert_eq!(
///     SomeType { x : 8, y: 32857983 },
///     decoded,
/// );
/// ```
pub trait Decode {
    fn decode(bytes: &[u8]) -> RBoxErr<Self>
    where
        Self: Sized,
        Self: for<'a> Deserialize<'a>,
    {
        let x: Self = bincode::deserialize(bytes)?;
        Ok(x)
    }
}

/// Adds serialisation via [`bincode`] and [`serde`] to a type.
/// Must be present on all major file types.
///
/// ```
/// use std::error::Error;
/// use ot_tools_io::Encode;
///
/// #[derive(serde::Serialize, std::fmt::Debug)]
/// struct SomeType {
///     x: u8,
///     y: u32,
/// }
///
/// // default implementation
/// impl Encode for SomeType {}
///
/// let x = SomeType { x : 8, y: 32857983 };
/// let encoded = x.encode().unwrap();
/// assert_eq!(
///     vec![8, 127, 95, 245, 1],
///     encoded,
/// );
/// ```
pub trait Encode {
    fn encode(&self) -> RBoxErr<Vec<u8>>
    where
        Self: Serialize,
    {
        Ok(bincode::serialize(&self)?)
    }
}

/// Trait for adding a method which swaps the bytes on all fields of a struct.
///
/// Useful for handling file writes to a different endianness.
/// ```
/// use std::error::Error;
/// use ot_tools_io::SwapBytes;
///
/// #[derive(std::fmt::Debug, PartialEq)]
/// struct SomeType {
///     x: u8,
///     y: u32,
/// }
///
/// impl SwapBytes for SomeType {
///     fn swap_bytes(self) -> Result<Self, Box<dyn Error>> {
///         Ok(Self {
///             x: self.x.swap_bytes(),
///             y: self.y.swap_bytes(),
///         })
///     }
/// }
///
/// let x = SomeType { x : 8, y: 32857983 };
/// let swapped = x.swap_bytes().unwrap();
/// assert_eq!(
///     SomeType { x: 8_u8.swap_bytes(), y: 32857983_u32.swap_bytes()},
///     swapped,
/// );
/// ```
pub trait SwapBytes {
    fn swap_bytes(self) -> RBoxErr<Self>
    where
        Self: Sized;
}

/// Used when we need a collection of default type instances
/// e.g. when creating a default bank we need 16 default patterns.
/// ```
/// // usage example
///
/// use ot_tools_io::DefaultsArray;
///
/// struct SomeType {
///     x: u8,
/// }
///
/// impl Default for SomeType {
///     fn default() -> Self {
///         Self { x: 0 }
///     }
/// }
///
/// impl DefaultsArray for SomeType {}
///
/// let xs: [SomeType; 20] = SomeType::defaults();
/// assert_eq!(xs.len(), 20);
///
/// let xs = SomeType::defaults::<25>();
/// assert_eq!(xs.len(), 25);
/// ```
pub trait DefaultsArray {
    /// Create an Array containing `N` default instances of `Self`.
    fn defaults<const N: usize>() -> [Self; N]
    where
        Self: Default,
    {
        from_fn(|_| Self::default())
    }
}

/// Same as [`DefaultsArray`], but using a boxed [`serde_big_array::Array`]
/// container type
/// ```
/// use serde_big_array::Array;
/// use ot_tools_io::DefaultsArrayBoxed;
///
/// struct SomeType {
///     x: u8,
/// }
///
/// impl Default for SomeType {
///     fn default() -> Self {
///         Self { x: 0 }
///     }
/// }
///
/// impl DefaultsArrayBoxed for SomeType {}
///
/// let xs: Box<Array<SomeType, 20>> = SomeType::defaults();
/// assert_eq!(xs.len(), 20);
///
/// let xs = SomeType::defaults::<25>();
/// assert_eq!(xs.len(), 25);
/// ```
pub trait DefaultsArrayBoxed {
    /// Create a Boxed [serde_big_array::Array] containing `N` default instances
    /// of `Self`.
    fn defaults<const N: usize>() -> Box<Array<Self, N>>
    where
        Self: Default,
    {
        Box::new(Array(from_fn(|_| Self::default())))
    }
}

/// Adds a method to check the current data structure matches the default for the type
/// ```rust
/// use ot_tools_io::{IsDefault, BankFile};
///
/// let mut bank = BankFile::default();
/// assert_eq!(bank.is_default(), true);
///
/// bank.datatype_version = 190;
/// assert_eq!(bank.is_default(), false);
/// ```
pub trait IsDefault {
    fn is_default(&self) -> bool;
}

/// Method for calculating the checksum value for types that have a checksum field
/// ```rust
/// # use std::path::PathBuf;
/// # let path = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// use ot_tools_io::{CalculateChecksum, OctatrackFileIO, BankFile};
/// let bank = BankFile::from_data_file(&path).unwrap();
/// assert_eq!(bank.checksum, bank.calculate_checksum().unwrap())
/// ```
pub trait CalculateChecksum {
    fn calculate_checksum(&self) -> RBoxErr<u16>;
}

/// Adds a method to verify if header(s) are valid in some data.
/// [See this thread](https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27).
/// ```rust
/// # use std::path::PathBuf;
/// # let path = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// use ot_tools_io::{CheckHeader, OctatrackFileIO, BankFile};
/// assert!(BankFile::from_data_file(&path).unwrap().check_header()) // true for valid header values
/// ```
// NOTE: ot-tools-io does not validate headers on file read, which means it is
// possible to perform checks like this when a data file has been read.
// otherwise we'd have to do a complicated check to verify headers on every
// file we read, then throw out an error and probably do some complicated
// error handling to explain to the end user exactly why we couldn't load the
// file (bad header, which patterns, which track within patterns etc.).
pub trait CheckHeader {
    fn check_header(&self) -> bool;
}

/// Adds a method to verify if checksum is valid in some data type.
/// [See this thread](https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27).
/// ```rust
/// # use std::path::PathBuf;
/// # let path = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// use ot_tools_io::{CheckChecksum, OctatrackFileIO, BankFile};
/// // true for valid checksum values
/// assert!(BankFile::from_data_file(&path).unwrap().check_checksum().unwrap())
/// ```
pub trait CheckChecksum {
    fn check_checksum(&self) -> RBoxErr<bool>;
}

/// Adds a method to verify if the data file version field is valid for the given type.
/// ```rust
/// # use std::path::PathBuf;
/// # let path = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// use ot_tools_io::{CheckFileVersion, OctatrackFileIO, BankFile};
/// // true for valid version values
/// assert!(BankFile::from_data_file(&path).unwrap().check_file_version().unwrap())
/// ```
// NOTE: ot-tools-io does not validate headers on file read, which means it is
// possible to perform checks like this when a data file has been read.
// otherwise we'd have to do a complicated check to verify headers on every
// file we read, then throw out an error and probably do some complicated
// error handling to explain to the end user exactly why we couldn't load the
// file (bad header, which patterns, which track within patterns etc.).
pub trait CheckFileVersion {
    fn check_file_version(&self) -> RBoxErr<bool>;
}

/// Adds a single method using the [`CheckHeader::check_header`],
/// [`CheckChecksum::check_checksum`] and [`CheckFileVersion::check_file_version`]
/// methods to run a full integrity check.
/// ```rust
/// # use std::path::PathBuf;
/// # let path = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// use ot_tools_io::{CheckIntegrity, OctatrackFileIO, BankFile};
/// // true for valid checksum+header values
/// assert!(BankFile::from_data_file(&path).unwrap().check_integrity().unwrap())
/// ```
pub trait CheckIntegrity: CheckHeader + CheckChecksum + CheckFileVersion {
    fn check_integrity(&self) -> RBoxErr<bool> {
        Ok(self.check_header() && self.check_checksum()? && self.check_file_version()?)
    }
}