ot_tools_io/

lib.rs

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

//! Serialization and Deserialization library for Elektron Octatrack data files.
//!
//! ## Important types
//!
//! | rust type    | octatrack filename pattern | description |
//! | ------------ | -------------------------- | ------------|
//! | [crate::arrangements::ArrangementFile] | `arr??.*` | data for arrangements |
//! | [crate::banks::BankFile] | `bank??.*` | data for parts and patterns |
//! | [crate::markers::MarkersFile] | `markers.*` | start trim/end trim/slices/loop points for sample slots |
//! | [crate::projects::ProjectFile] | `project.*` | project level settings; state; sample slots |
//! | [crate::samples::SampleAttributes] | `*.ot` | saved sample settings data, loops slices etc. |
//!
//!
//! Only the above types implement the [crate::Encode] and [crate::Decode] traits,
//! which means only these types can be read from / written to the filesystem using functions
//! in this library.
//!
//! Read the relevant modules in this library for more detailed information on the data contained in each file.
//!
//! ## How do different Octatrack data files relate to each other?
//!
//! - A Bank stores zero-indexed sample slot IDs to indicate which sample should be played when on a given track
//!   (part machine data and/or track p-lock trigs).
//! - Changing the sample loaded into a sample slot updates both the `project.*` file (change the trig quantization
//!   settings, file path etc) and the `markers.*` file (change the trim settings based on either initial load,
//!   or any data in a relevant `*.ot` sample settings file).
//! - Data from `project.*`and `markers.*` is written to an `*.ot` file when saving sample attributes data from the
//!   octatrack's audio editing menu.
//! - Loading a sample into a project sample slot (`project.*` and `markers.*` files) reads any data in an `*.ot` files
//!   and configures the sample slot accordingly.
//!
//! ## When do `*.work` and `*.strd` files get modified by the Octatrack?
//!
//! - `*.work` files are created when creating a new project `PROJECT MENU -> CHANGE PROJECT -> CREATE NEW`.
//! - `*.work` files are updated by using the `PROJECT MENU -> SYNC TO CARD` operation.
//! - `*.work` files are updated when the user performs a `PROJECT MENU -> SAVE PROJECT` operation.
//! - `*.strd` files are created/updated when the user performs a `PROJECT MENU -> SAVE PROJECT` operation.
//! - `*.strd` files are not changed by the `PROJECT -> SYNC TO CARD` operation.
//! - `arr??.strd` files can also be saved via the `ARRANGER MENU -> SAVE ARRANGEMENT` operation.
//!
//! ## Notable 'gotcha's
//! - Project sample slots (`project.*` files) are one-indexed, but their references everywhere else are zero-indexed
//!   (`bank??.*` and `markers.*` files).
//! - A 'Disabled' loop point in either `markers.*` or `*.ot` files is a `0xFFFFFFFF` value, but the default
//!   loop point when creating new `markers.*` file is always `0_u32`. The 'Disabled' value setting is only set
//!   when a sample is loaded into a sample slot.
//!
//! ## Example code
//! ```rust
//! /*
//! reading, mutating and writing a bank file
//! */
//!
//! use std::path::PathBuf;
//! use ot_tools_io::{read_type_from_bin_file, write_type_to_bin_file, banks::BankFile};
//!
//! let binfpath = PathBuf::from("test-data")
//!     .join("blank-project")
//!     .join("bank01.work");
//!
//! // read an editable version of the bank file
//! let mut bank: BankFile = read_type_from_bin_file(&binfpath).unwrap();
//!
//! // change active scenes on the working copy of Part 4
//! bank.parts.unsaved[3].active_scenes.scene_a = 2;
//! bank.parts.unsaved[3].active_scenes.scene_b = 6;
//!
//! // write to a new bank file
//! let outfpath = std::env::temp_dir()
//!     .join("ot-tools-io")
//!     .join("doctest")
//!     .join("main_example_1");
//! write_type_to_bin_file::<BankFile>(&bank, &outfpath).unwrap();
//! ```

pub mod arrangements;
pub mod banks;
pub mod markers;
pub mod projects;
pub mod samples;
#[cfg(test)]
mod test_utils;

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

// todo: sized errors so not necessary to keep Boxing error enum varients
/// Shorthand type alias for a Result with a Boxed Error
type RBoxErr<T> = Result<T, Box<dyn Error>>;

/// Global error variants
#[derive(Debug, PartialEq, Eq)]
pub enum OtToolsIoErrors {
    /// An 'Options' Enum (e.g. `SampleAttributesLoopMode`) does not have a matching variant for this value
    NoMatchingOptionEnumValue,
    /// Could not parse a sample slot string data when loading a project
    ProjectSampleSlotParsingError,
    /// A file does not exist at the provided location
    FileNotFound,
    /// I know an error exists here, but I'm busy yak shaving something else at the moment.
    TodoError,
}
impl std::fmt::Display for OtToolsIoErrors {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            Self::NoMatchingOptionEnumValue => {
                write!(f, "no matching enum option for the provided value")
            }
            Self::ProjectSampleSlotParsingError => {
                write!(f, "count not load sample slot from project string data")
            }
            Self::FileNotFound => {
                write!(f, "file not found")
            }
            Self::TodoError => {
                write!(
                    f,
                    "this error is handled, but an error variant is not created yet"
                )
            }
        }
    }
}
impl Error for OtToolsIoErrors {}

// DO-NOT-DERIVE: Implementation details for each enum are always required.
/// Trait to convert between Enum option instances and their corresponding value.
trait OptionEnumValueConvert {
    /// One of the enum types within the `octatrack::options` module.
    type T;

    /// Input type for `from_value` and return type for `value` method.
    type V;

    /// Get an Enum instance from a numeric value.
    fn from_value(v: &Self::V) -> RBoxErr<Self::T>;

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

fn u8_bytes_to_u16(bytes: &[u8; 2]) -> u16 {
    ((bytes[0] as u16) << 8) | bytes[1] as u16
}

/// Adds deserialisation via `bincode` and `serde` to a type.
/// Must be present on all major file types.
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.
pub trait Encode {
    fn encode(&self) -> RBoxErr<Vec<u8>>
    where
        Self: Serialize,
    {
        Ok(bincode::serialize(&self)?)
    }
}

/// 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
/// ```
/// // usage example
///
/// 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, banks::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;
/// use ot_tools_io::{CalculateChecksum, read_type_from_bin_file, banks::BankFile};
/// # let fpath = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// let bank: BankFile = read_type_from_bin_file(&fpath).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 to understand why this is useful:
/// <https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27>
/// ```rust
/// # use std::path::PathBuf;
/// use ot_tools_io::{CheckHeader, read_type_from_bin_file, banks::BankFile};
/// # let fpath = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// let bank: BankFile = read_type_from_bin_file(&fpath).unwrap();
/// assert!(bank.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 to understand why this is useful:
/// <https://www.elektronauts.com/t/bank-unavailable-octatrack/190647/27>
/// ```rust
/// # use std::path::PathBuf;
/// use ot_tools_io::{CheckChecksum, read_type_from_bin_file, banks::BankFile};
/// # let fpath = PathBuf::from("test-data")
/// #     .join("blank-project")
/// #     .join("bank01.work");
/// let bank: BankFile = read_type_from_bin_file(&fpath).unwrap();
/// assert!(bank.check_checksum().unwrap()) // true for valid checksum values
/// ```
pub trait CheckChecksum {
    fn check_checksum(&self) -> RBoxErr<bool>;
}

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

/* SER/DE GENERICS ============================================================================== */

/// Deserialize a bytes to a data structure of type `T`
/// ```rust
/// # use std::array::from_fn;
/// # use ot_tools_io::{deserialize_bin_to_type, samples::SampleAttributes};
/// let bytes: [u8; 832] = from_fn(|_| 0);
/// let samples_type: SampleAttributes = deserialize_bin_to_type(&bytes).unwrap();
/// assert_eq!(samples_type.gain, 0)
/// ```
pub fn deserialize_bin_to_type<T>(bytes: &[u8]) -> RBoxErr<T>
where
    T: Decode,
    T: for<'a> Deserialize<'a>,
{
    let x: T = T::decode(bytes)?;
    Ok(x)
}

/// Serialize to bytes from a data structure of type `T`
/// ```rust
/// # use std::array::from_fn;
/// # use ot_tools_io::{serialize_bin_from_type, banks::BankFile};
/// let bank = BankFile::default();
/// let bytes = serialize_bin_from_type::<BankFile>(&bank).unwrap();
/// assert_eq!(bytes.len(), 636113);
/// ```
pub fn serialize_bin_from_type<T>(data: &T) -> RBoxErr<Vec<u8>>
where
    T: Encode,
    T: Serialize,
{
    data.encode()
}

/// Deserialize a JSON string to a data structure of type `T`
pub fn deserialize_json_to_type<T>(data: &str) -> RBoxErr<T>
where
    T: for<'a> Deserialize<'a>,
{
    let x: T = serde_json::from_str(data)?;
    Ok(x)
}

/// Serialize a JSON string from a data structure of type `T`
/// ```rust
/// # use ot_tools_io::{serialize_json_from_type, banks::BankFile};
/// let bank = BankFile::default();
/// let json_string = serialize_json_from_type::<BankFile>(&bank).unwrap();
/// assert_eq!(json_string.len(), 7807730);
/// assert_eq!(json_string[0..15], "{\"header\":[70,7".to_string());
/// ```
pub fn serialize_json_from_type<T>(data: &T) -> RBoxErr<String>
where
    T: Serialize,
{
    Ok(serde_json::to_string(&data)?)
}

/// Deserialize a YAML string to a data structure of type `T`
pub fn deserialize_yaml_to_type<T>(data: &str) -> RBoxErr<T>
where
    T: for<'a> Deserialize<'a>,
{
    let x: T = serde_yml::from_str(data)?;
    Ok(x)
}
/// Serialize a YAML string from a data structure of type `T`
/// ```rust
/// # use ot_tools_io::{serialize_yaml_from_type, banks::BankFile};
/// let bank = BankFile::default();
/// let yaml_string = serialize_yaml_from_type::<BankFile>(&bank).unwrap();
/// assert_eq!(yaml_string.len(), 12578394);
/// assert_eq!(yaml_string[0..15], "header:\n- 70\n- ".to_string());
/// ```
pub fn serialize_yaml_from_type<T>(data: &T) -> RBoxErr<String>
where
    T: Serialize,
{
    Ok(serde_yml::to_string(&data)?)
}

/* UTILS ======================================================================================== */

/* NO TESTS BLOCK START */

/// Read a YAML file into a data structure of type `<T>`
/// ```rust
/// # use std::path::PathBuf;
/// use ot_tools_io::{yaml_file_to_type, banks::BankFile};
/// let fpath = PathBuf::from("test-data").join("bank").join("blank.yaml");
/// let bank: BankFile = yaml_file_to_type(&fpath).unwrap();
/// assert_eq!(bank.datatype_version, 23);
/// ```
pub fn yaml_file_to_type<T>(path: &Path) -> RBoxErr<T>
where
    T: for<'a> Deserialize<'a>,
{
    let string = read_str_file(path)?;
    let data = deserialize_yaml_to_type::<T>(&string)?;
    Ok(data)
}

/// Write a data structure of type `<T>` into a YAML file
/// ```rust
/// use std::env::temp_dir;
/// # use std::fs::create_dir_all;
/// use ot_tools_io::{type_to_yaml_file, banks::BankFile};
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("type_to_yaml_file.yaml");
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
///
/// let r = type_to_yaml_file(&BankFile::default(), &fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn type_to_yaml_file<T>(data: &T, path: &Path) -> RBoxErr<()>
where
    T: Serialize,
{
    let yaml = serialize_yaml_from_type::<T>(data)?;
    write_str_file(&yaml, path)?;
    Ok(())
}

/// Read a JSON file into a data structure of type `<T>`
pub fn json_file_to_type<T>(path: &Path) -> RBoxErr<T>
where
    T: for<'a> Deserialize<'a>,
{
    let string = read_str_file(path)?;
    let data = deserialize_json_to_type::<T>(&string)?;
    Ok(data)
}

/// Write a data structure of type `<T>` into a JSON file
/// ```rust
/// use std::env::temp_dir;
/// # use std::fs::create_dir_all;
/// use ot_tools_io::{type_to_json_file, banks::BankFile};
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("type_to_json_file.json");
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
///
/// let r = type_to_json_file(&BankFile::default(), &fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn type_to_json_file<T>(data: &T, path: &Path) -> RBoxErr<()>
where
    T: Serialize,
{
    let yaml = serialize_json_from_type::<T>(data)?;
    write_str_file(&yaml, path)?;
    Ok(())
}

/// Create a new type with default settings, and write the data to a file.
/// ```rust
/// use std::env::temp_dir;
/// # use std::fs::create_dir_all;
/// use ot_tools_io::{default_type_to_bin_file, banks::BankFile};
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("default_type_to_bin_file.bank");
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
///
/// let r = default_type_to_bin_file::<BankFile>(&fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn default_type_to_bin_file<T>(outpath: &Path) -> RBoxErr<()>
where
    T: Encode,
    T: Default,
    T: Serialize,
{
    write_type_to_bin_file(&T::default(), outpath)?;
    Ok(())
}

/* NO TESTS BLOCK ENDS */

/// Show deserialized representation of a binary data file of type `T` at `path`
pub fn show_type<T>(path: &Path, newlines: Option<bool>) -> RBoxErr<()>
where
    T: Debug,
    T: Decode,
    T: for<'a> Deserialize<'a>,
{
    let data = read_type_from_bin_file::<T>(path)?;
    if newlines.unwrap_or(true) {
        println!("{data:#?}")
    } else {
        println!("{data:?}")
    };

    Ok(())
}

/// Read a YAML file then write the data to a new `<T>` type file
/// ```rust
/// # use std::{path::PathBuf, fs::create_dir_all};
/// use std::env::temp_dir;
/// use ot_tools_io::{yaml_file_to_bin_file, banks::BankFile};
///
/// let yaml_fpath = PathBuf::from("test-data")
///     .join("bank")
///     .join("blank.yaml");
///
/// let bin_fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("yaml_to_bin.bank_example");
/// # create_dir_all(&bin_fpath.parent().unwrap()).unwrap();
///
/// let r = yaml_file_to_bin_file::<BankFile>(&yaml_fpath, &bin_fpath);
/// assert!(r.is_ok());
/// assert!(bin_fpath.exists());
/// ```
pub fn yaml_file_to_bin_file<T>(yaml_filepath: &Path, bin_filepath: &Path) -> RBoxErr<()>
where
    T: Encode,
    T: Serialize,
    T: for<'a> Deserialize<'a>,
{
    let yaml = read_str_file(yaml_filepath)?;
    let data = deserialize_yaml_to_type::<T>(&yaml)?;
    write_type_to_bin_file::<T>(&data, bin_filepath)?;
    Ok(())
}

/// Read data of type `<T>` from  a binary data file and write it to a YAML file
/// ```rust
/// # use std::{path::PathBuf, fs::create_dir_all};
/// use std::env::temp_dir;
/// use ot_tools_io::{bin_file_to_yaml_file, banks::BankFile};
///
/// let bin_fpath = PathBuf::from("test-data")
///     .join("blank-project")
///     .join("bank01.work");
///
/// let yaml_fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("bin_to_yaml.bank_example");
/// # create_dir_all(&yaml_fpath.parent().unwrap()).unwrap();
///
/// let r = bin_file_to_yaml_file::<BankFile>(&bin_fpath, &yaml_fpath);
/// assert!(r.is_ok());
/// assert!(bin_fpath.exists());
/// ```
pub fn bin_file_to_yaml_file<T>(bin_filepath: &Path, yaml_filepath: &Path) -> RBoxErr<()>
where
    T: Decode,
    T: Serialize,
    T: for<'a> Deserialize<'a>,
{
    let data = read_type_from_bin_file::<T>(bin_filepath)?;
    let yaml = serialize_yaml_from_type::<T>(&data)?;
    write_str_file(&yaml, yaml_filepath)?;
    Ok(())
}

/// Read a JSON file then write the data to a new `<T>` type file
pub fn json_file_to_bin_file<T>(json_filepath: &Path, bin_filepath: &Path) -> RBoxErr<()>
where
    T: Encode,
    T: Serialize,
    T: for<'a> Deserialize<'a>,
{
    let json = read_str_file(json_filepath)?;
    let data = deserialize_json_to_type::<T>(&json)?;
    write_type_to_bin_file::<T>(&data, bin_filepath)?;
    Ok(())
}

/// Read data of type `<T>` from  a binary data file and write it to a JSON file
/// ```rust
/// # use std::{path::PathBuf, fs::create_dir_all};
/// use std::env::temp_dir;
/// use ot_tools_io::{bin_file_to_json_file, banks::BankFile};
///
/// let bin_fpath = PathBuf::from("test-data")
///     .join("blank-project")
///     .join("bank01.work");
///
/// let json_fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("bin_to_json.bank_example");
/// # create_dir_all(&json_fpath.parent().unwrap()).unwrap();
///
/// let r = bin_file_to_json_file::<BankFile>(&bin_fpath, &json_fpath);
/// assert!(r.is_ok());
/// assert!(bin_fpath.exists());
/// ```
pub fn bin_file_to_json_file<T>(bin_filepath: &Path, json_filepath: &Path) -> RBoxErr<()>
where
    T: Decode,
    T: Serialize,
    T: for<'a> Deserialize<'a>,
{
    let data = read_type_from_bin_file::<T>(bin_filepath)?;
    let yaml = serialize_json_from_type::<T>(&data)?;
    write_str_file(&yaml, json_filepath)?;
    Ok(())
}

/// Read a data structure of type `<T>` from a binary data file.
/// ```rust
/// use std::path::PathBuf;
/// use ot_tools_io::{read_type_from_bin_file, banks::BankFile};
///
/// let fpath = PathBuf::from("test-data")
///     .join("blank-project")
///     .join("bank01.work");
///
/// let bank: BankFile = read_type_from_bin_file(&fpath).unwrap();
/// assert_eq!(bank.datatype_version, 23);
/// ```
pub fn read_type_from_bin_file<T>(path: &Path) -> RBoxErr<T>
where
    T: Decode,
    T: for<'a> Deserialize<'a>,
{
    let bytes = read_bin_file(path)?;
    let data = deserialize_bin_to_type::<T>(&bytes)?;
    Ok(data)
}

/// Write a data structue of type `<T>` to a binary data file.
/// ```rust
/// # use std::{path::PathBuf, fs::create_dir_all};
/// use std::env::temp_dir;
/// use ot_tools_io::{write_type_to_bin_file, banks::BankFile};
///
/// let fpath = temp_dir()
///    .join("ot-tools-io")
///    .join("doctest")
///    .join("write_type_to_bin_file.bank_example");
/// # create_dir_all(&fpath.parent().unwrap()).unwrap();
///
/// let r = write_type_to_bin_file::<BankFile>(&BankFile::default(), &fpath);
/// assert!(r.is_ok());
/// assert!(fpath.exists());
/// ```
pub fn write_type_to_bin_file<T>(data: &T, path: &Path) -> RBoxErr<()>
where
    T: Encode,
    T: Serialize,
{
    let bytes = serialize_bin_from_type::<T>(data)?;
    write_bin_file(&bytes, path)?;
    Ok(())
}

/// 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)
}

/// 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");
///
/// 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(())
}

/// Read a file at `path` as a string.
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)
}

/// Write a string to a file at `path`.
pub fn write_str_file(string: &str, path: &Path) -> RBoxErr<()> {
    let mut file: File = File::create(path)?;
    write!(file, "{}", string)?;
    Ok(())
}

#[cfg(test)]
#[allow(unused_imports)]
mod test {
    use super::*;
    use crate::arrangements::ArrangementFile;
    use crate::banks::BankFile;
    use crate::projects::ProjectFile;
    use crate::samples::SampleAttributes;
    use crate::test_utils::*;
    mod show_ok {
        use super::*;
        #[test]
        fn test_arrangement() {
            let fp = get_blank_proj_dirpath().join("arr01.work");
            let r = show_type::<ArrangementFile>(&fp, None);
            assert!(r.is_ok())
        }

        #[test]
        fn test_bank() {
            let fp = get_blank_proj_dirpath().join("bank01.work");
            let r = show_type::<BankFile>(&fp, None);
            assert!(r.is_ok())
        }

        #[test]
        fn test_project() {
            let fp = get_blank_proj_dirpath().join("project.work");
            let r = show_type::<ProjectFile>(&fp, None);
            assert!(r.is_ok())
        }

        #[test]
        fn test_sample() {
            let fp = get_samples_dirpath().join("sample.ot");
            let r = show_type::<SampleAttributes>(&fp, None);
            assert!(r.is_ok())
        }
    }

    // TODO: Add more cases
    mod yaml_file_to_bin_file_ok {
        use super::*;
        use crate::arrangements::ArrangeRow;

        mod arrangement {
            use crate::arrangements::ArrangementFile;
            use crate::test_utils::get_arrange_dirpath;
            use crate::{read_type_from_bin_file, yaml_file_to_bin_file};

            fn helper_arrangement(fname: String) {
                let testfile = get_arrange_dirpath().join(format!["{fname}.work"]);
                let outfile = std::env::temp_dir()
                    .join(format!["ot-tools-io-arrangement-load-test-{fname}.work"]);
                let yaml = get_arrange_dirpath().join(format!["{fname}.yaml"]);
                let r = yaml_file_to_bin_file::<ArrangementFile>(&yaml, &outfile);
                let written = read_type_from_bin_file::<ArrangementFile>(&outfile).unwrap();
                let valid = read_type_from_bin_file::<ArrangementFile>(&testfile).unwrap();
                let _ = std::fs::remove_file(&outfile);
                println!("{r:?}");
                assert!(r.is_ok());
                assert_eq!(written, valid);
            }
            #[test]
            fn blank() {
                helper_arrangement("blank".to_string());
            }

            #[test]
            fn full_options() {
                helper_arrangement("full-options".to_string());
            }

            #[test]
            fn full_options_no_rems() {
                helper_arrangement("full-options-no-rems".to_string());
            }

            #[test]
            fn no_saved_flag() {
                helper_arrangement("no-saved-flag".to_string());
            }

            #[test]
            fn with_saved_flag() {
                helper_arrangement("with-saved-flag".to_string());
            }

            #[test]
            fn blank_diffname_1() {
                helper_arrangement("blank-diffname1".to_string());
            }

            #[test]
            fn blank_diffname_2() {
                helper_arrangement("blank-diffname2".to_string());
            }

            #[test]
            fn four_patterns() {
                helper_arrangement("4-patterns".to_string());
            }

            #[test]
            fn one_pattern() {
                helper_arrangement("1-pattern".to_string());
            }
            #[test]
            fn one_halt() {
                helper_arrangement("1-halt".to_string());
            }
            #[test]
            fn one_pattern_1_loop() {
                helper_arrangement("1-patt-1-loop".to_string());
            }
            #[test]
            fn one_pattern_1_loop_1_jump() {
                helper_arrangement("1-patt-1-jump-1-loop".to_string());
            }
            #[test]
            fn one_pattern_1_loop_1_jump_1_halt() {
                helper_arrangement("1-patt-1-jump-1-loop-1-halt".to_string());
            }
            #[test]
            fn one_rems_no_txt() {
                helper_arrangement("1-rem-blank-txt".to_string());
            }
            #[test]
            fn one_rems_chain_txt() {
                helper_arrangement("1-rem-CHAIN-txt".to_string());
            }
            #[test]
            fn two_rems_chain_txt() {
                helper_arrangement("2-rem-CHAIN-txt".to_string());
            }
            #[test]
            fn blank_same_name_saved() {
                helper_arrangement("blank-samename-saved-chktest".to_string());
            }
            #[test]
            fn blank_same_name_unsaved() {
                helper_arrangement("blank-samename-unsaved-chktest".to_string());
            }
        }

        #[test]
        fn test_project() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-project-load-test-ok.work");
            let yaml = get_project_dirpath().join("project.yaml");
            let r = yaml_file_to_bin_file::<ProjectFile>(&yaml, &outfile);
            let _ = std::fs::remove_file(&outfile);
            println!("{r:?}");
            assert!(r.is_ok())
        }

        #[test]
        fn test_project_matches_blank() {
            let testfile = get_project_dirpath().join("blank.work");
            let outfile = std::env::temp_dir().join("ot-tools-actions-project-load-test-full.work");
            let yaml = get_project_dirpath().join("project.yaml");

            let r = yaml_file_to_bin_file::<ProjectFile>(&yaml, &outfile);

            let written = read_type_from_bin_file::<ProjectFile>(&outfile).unwrap();
            let valid = read_type_from_bin_file::<ProjectFile>(&testfile).unwrap();

            let _ = std::fs::remove_file(&outfile);
            println!("{r:?}");
            assert!(r.is_ok());
            assert_eq!(written, valid)
        }

        #[test]
        fn test_bank() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bank-load-test-ok.work");
            let yaml = get_bank_dirpath().join("blank.yaml");
            let r = yaml_file_to_bin_file::<BankFile>(&yaml, &outfile);
            let _ = std::fs::remove_file(&outfile);
            println!("{r:?}");
            assert!(r.is_ok())
        }

        #[test]
        fn test_sample() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-sample-load-test-ok.work");
            let yaml = get_samples_dirpath().join("chain.yaml");
            let r = yaml_file_to_bin_file::<SampleAttributes>(&yaml, &outfile);
            let _ = std::fs::remove_file(&outfile);
            println!("{r:?}");
            assert!(r.is_ok());
        }
    }

    mod bin_file_to_yaml_file_ok {
        use super::*;
        #[test]
        // Windows will add on carriage returns...
        #[cfg(not(target_os = "windows"))]
        fn arrangement_blank() {
            let valid_yaml_path = get_arrange_dirpath().join("blank.yaml");
            let binpath = get_arrange_dirpath().join("blank.work");
            let outyaml = std::env::temp_dir().join("serde-ot-bin2yaml-arrange-blank.yaml");

            let r = crate::bin_file_to_yaml_file::<super::ArrangementFile>(&binpath, &outyaml);
            let written = crate::read_str_file(&outyaml).unwrap();
            let valid = crate::read_str_file(&valid_yaml_path).unwrap();

            let _ = std::fs::remove_file(&outyaml);
            println!("{r:?}");
            assert!(r.is_ok());
            assert_eq!(valid, written);
        }

        #[test]
        // Windows will add on carriage returns...
        #[cfg(not(target_os = "windows"))]
        fn arrangement_full_options() {
            let valid_yaml_path = get_arrange_dirpath().join("full-options.yaml");
            let binpath = get_arrange_dirpath().join("full-options.work");
            let outyaml = std::env::temp_dir().join("serde-ot-bin2yaml-arrange-fulloptions.yaml");

            let r = crate::bin_file_to_yaml_file::<super::ArrangementFile>(&binpath, &outyaml);
            let written = crate::read_str_file(&outyaml).unwrap();
            let valid = crate::read_str_file(&valid_yaml_path).unwrap();

            let _ = std::fs::remove_file(&outyaml);
            println!("{r:?}");
            assert!(r.is_ok());
            assert_eq!(valid, written);
        }

        #[test]
        // Windows will add on carriage returns...
        #[cfg(not(target_os = "windows"))]
        fn arrangement_one_blank_reminder_row() {
            let valid_yaml_path = get_arrange_dirpath().join("1-rem-blank-txt.yaml");
            let binpath = get_arrange_dirpath().join("1-rem-blank-txt.work");
            let outyaml =
                std::env::temp_dir().join("serde-ot-bin2yaml-arrange-onereminderrow.yaml");

            let r = crate::bin_file_to_yaml_file::<super::ArrangementFile>(&binpath, &outyaml);
            let written = crate::read_str_file(&outyaml).unwrap();
            let valid = crate::read_str_file(&valid_yaml_path).unwrap();

            let _ = std::fs::remove_file(&outyaml);
            println!("{r:?}");
            assert!(r.is_ok());
            assert_eq!(valid, written);
        }

        #[test]
        fn test_bank() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-bank-ok.yaml");
            let binfile = get_blank_proj_dirpath().join("bank01.work");
            let r = bin_file_to_yaml_file::<BankFile>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_project() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-project-ok.yaml");
            let binfile = get_blank_proj_dirpath().join("project.work");
            let r = bin_file_to_yaml_file::<ProjectFile>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_sample() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-sample-ok.yaml");
            let binfile = get_samples_dirpath().join("sample.ot");
            let r = bin_file_to_yaml_file::<SampleAttributes>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }
    }

    mod bin_file_to_json_file_ok {
        use super::*;

        #[test]
        fn arrangement_blank() {
            // let valid_json_path = std::path::Path::new("TODO");

            let binpath = get_arrange_dirpath().join("blank.work");
            let outjson = std::env::temp_dir().join("serde-ot-bin2yaml-arrange-blank.json");

            let r = crate::bin_file_to_json_file::<super::ArrangementFile>(&binpath, &outjson);
            let written = crate::read_str_file(&outjson);
            // let valid = crate::read_str_file(&valid_json_path).unwrap();

            let _ = std::fs::remove_file(&outjson);
            println!("{r:?}");
            assert!(r.is_ok());
            assert!(written.is_ok());
            // assert_eq!(valid, written);
        }

        #[test]
        fn arrangement_full_options() {
            // let valid_json_path = std::path::Path::new("TODO");
            let binpath = get_arrange_dirpath().join("full-options.work");
            let outjson = std::env::temp_dir().join("serde-ot-bin2yaml-arrange-full.json");

            let r = crate::bin_file_to_json_file::<super::ArrangementFile>(&binpath, &outjson);
            let written = crate::read_str_file(&outjson);
            // let valid = crate::read_str_file(&valid_json_path).unwrap();

            let _ = std::fs::remove_file(&outjson);
            println!("{r:?}");
            assert!(r.is_ok());
            assert!(written.is_ok());
            // assert_eq!(valid, written);
        }

        #[test]
        fn arrangement_one_reminder_row() {
            // let valid_json_path = std::path::Path::new("TODO");
            let binpath = get_arrange_dirpath().join("1-rem-blank-txt.work");
            let outjson =
                std::env::temp_dir().join("serde-ot-bin2yaml-arrange-one_rem_row_blank.json");

            let r = crate::bin_file_to_json_file::<super::ArrangementFile>(&binpath, &outjson);
            let written = crate::read_str_file(&outjson);
            // let valid = crate::read_str_file(&valid_json_path).unwrap();

            let _ = std::fs::remove_file(&outjson);
            println!("{r:?}");
            assert!(r.is_ok());
            assert!(written.is_ok());
            // assert_eq!(valid, written);
        }

        #[test]
        fn test_bank() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-bank-ok.json");
            let binfile = get_blank_proj_dirpath().join("bank01.work");
            let r = bin_file_to_json_file::<BankFile>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_project() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-project-ok.json");
            let binfile = get_blank_proj_dirpath().join("project.work");
            let r = bin_file_to_json_file::<ProjectFile>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_sample() {
            let outfile = std::env::temp_dir().join("ot-tools-actions-bin2yaml-sample-ok.json");
            let binfile = get_samples_dirpath().join("sample.ot");
            let r = bin_file_to_json_file::<SampleAttributes>(&binfile, &outfile);
            let _ = std::fs::remove_file(&outfile);
            assert!(r.is_ok())
        }
    }

    // TODO: Add more cases!
    mod json_file_to_bin_file_ok {
        // #[test]
        // fn test_arrangement() {
        //     let outfile = std::env::temp_dir().join("ot-tools-actions-arrangement-load-test-ok.work");
        //     let yaml = PathBuf::from("TODO");
        //     // TODO!
        //     let r = yaml_file_to_bin_file::<ArrangementFile>(&yaml, &outfile);
        //     let _ = std::fs::remove_file(&outfile);
        //     assert!(r.is_ok())
        // }

        // #[test]
        // fn test_bank() {
        //     let outfile = std::env::temp_dir().join("ot-tools-actions-bank-load-test-ok.work");
        //     let yaml = PathBuf::from("TODO");
        //     let r = yaml_file_to_bin_file::<Bank>(&yaml, &outfile);
        //     let _ = std::fs::remove_file(&outfile);
        //     assert!(r.is_ok())
        // }

        // #[test]
        // fn test_project() {
        //     let outfile = std::env::temp_dir().join("ot-tools-actions-project-load-test-ok.work");
        //     let yaml = PathBuf::from("../data/tests/projects/project.yaml");
        //     let r = yaml_file_to_bin_file::<Project>(&yaml, &outfile);
        //     let _ = std::fs::remove_file(&outfile);
        //     assert!(r.is_ok())
        // }

        // #[test]
        // fn test_sample() {
        //     let outfile = std::env::temp_dir().join("ot-tools-actions-sample-load-test-ok.work");
        //     let yaml = PathBuf::from("TODO");
        //     let r = yaml_file_to_bin_file::<SampleAttributes>(&yaml, &outfile);
        //     let _ = std::fs::remove_file(&outfile);
        //     assert!(r.is_ok())
        // }
    }

    mod read_type_from_bin_file_ok {
        use super::*;

        #[test]
        fn arrangement_blank() {
            let binfile = get_arrange_dirpath().join("blank.work");
            let r = read_type_from_bin_file::<ArrangementFile>(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn arrangement_full_options() {
            let binfile = get_arrange_dirpath().join("full-options.work");
            let r = read_type_from_bin_file::<ArrangementFile>(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn arrangement_one_reminder() {
            let binfile = get_arrange_dirpath().join("1-rem-blank-txt.work");
            let r = read_type_from_bin_file::<ArrangementFile>(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_type_from_bin_file_bank() {
            let binfile = get_blank_proj_dirpath().join("bank01.work");
            let r = read_type_from_bin_file::<BankFile>(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_type_from_bin_file_project() {
            let binfile = get_blank_proj_dirpath().join("project.work");
            let r = read_type_from_bin_file::<ProjectFile>(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_type_from_bin_file_sample() {
            let binfile = get_samples_dirpath().join("sample.ot");
            let r = read_type_from_bin_file::<SampleAttributes>(&binfile);
            assert!(r.is_ok())
        }
    }

    mod write_type_from_bin_file_ok {
        // TODO
    }

    mod read_bin_file_ok {
        use super::*;

        #[test]
        fn arrangement_blank() {
            let binfile = get_arrange_dirpath().join("blank.work");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn arrangement_full_options() {
            let binfile = get_arrange_dirpath().join("full-options.work");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn arrangement_one_reminder() {
            let binfile = get_arrange_dirpath().join("1-rem-blank-txt.work");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_bin_file_bank() {
            let binfile = get_blank_proj_dirpath().join("bank01.work");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_bin_file_project() {
            let binfile = get_blank_proj_dirpath().join("project.work");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }

        #[test]
        fn test_read_bin_file_sample() {
            let binfile = get_samples_dirpath().join("sample.ot");
            let r = read_bin_file(&binfile);
            assert!(r.is_ok())
        }
    }

    mod write_bin_file_ok {
        // TODO
    }

    mod read_str_file_ok {
        // TODO
    }

    mod write_str_file_ok {
        // TODO
    }

    // TODO: This probably shouldn't be here...
    mod project_read {
        use super::*;
        use crate::projects::metadata::ProjectMetadata;
        use crate::projects::settings::ProjectSettings;
        use crate::projects::slots::ProjectSampleSlot;
        use crate::projects::states::ProjectStates;
        use crate::projects::ProjectFile;
        // can read a project file without errors
        #[test]
        fn test_read_default_project_work_file() {
            let infile = get_blank_proj_dirpath().join("project.work");
            assert!(read_type_from_bin_file::<ProjectFile>(&infile).is_ok());
        }

        // test that the metadata section is correct
        #[test]
        fn test_read_default_project_work_file_metadata() {
            let infile = get_blank_proj_dirpath().join("project.work");
            let p = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();

            let correct = ProjectMetadata::default();

            assert_eq!(p.metadata, correct);
        }

        // test that the states section is correct
        #[test]
        fn test_read_default_project_work_file_states() {
            let infile = get_blank_proj_dirpath().join("project.work");
            let p = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();

            let correct = ProjectStates::default();

            assert_eq!(p.states, correct);
        }

        // test that the states section is correct
        #[test]
        fn test_read_default_project_work_file_settings() {
            let infile = get_blank_proj_dirpath().join("project.work");
            let p = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();

            let correct = ProjectSettings::default();

            assert_eq!(p.settings, correct);
        }

        // test that the states section is correct
        #[test]
        fn test_read_default_project_work_file_sslots() {
            let infile = get_blank_proj_dirpath().join("project.work");
            let p = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();
            let default_sslots = ProjectSampleSlot::defaults();

            assert_eq!(p.slots, default_sslots);
        }

        // test that reading and writing a single project gives the same outputs
        #[test]
        fn test_read_write_default_project_work_file() {
            let infile = get_blank_proj_dirpath().join("project.work");
            let outfile = std::env::temp_dir().join("default_1.work");
            let p = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();
            let _ = write_type_to_bin_file::<ProjectFile>(&p, &outfile);

            let p_reread = read_type_from_bin_file::<ProjectFile>(&infile).unwrap();

            assert_eq!(p, p_reread)
        }
    }
}