//! A crate for quick and easy format structure definitions for use in binary file parsing.
//!
//! # Usage
//!
//! This crate should be used by invoking the provided [`format_struct`] macro like this:
//!
//! ```rust
//! use format_struct::{format_struct, FromByteSlice};
//!
//! // Here we define a small structure.
//! format_struct! {
//!     struct little Test {
//!         foo: u8,
//!         bar: u32,
//!         baz: [u8; 2],
//!     }
//! }
//!
//! # pub fn main() {
//! // This is the data we want to parse:
//! let data = &[
//!     0x42u8, // this goes into foo
//!     0x39, 0x05, 0x00, 0x00, // this goes into bar
//!     0xaa, 0x55, // this goes into baz
//! ][..];
//!
//! // This is completely zero-cost since the implementation is just a transmute.
//! let s = Test::from_byte_slice(data).unwrap();
//!
//! // Each integer field access compiles to a single unaligned memory access instruction.
//! assert_eq!(s.foo(), 0x42);
//! assert_eq!(s.bar(), 1337);
//! assert_eq!(s.baz(), &[0xaa, 0x55]);
//! # }
//! ```
//!
//! # Reexports
//!
//! Due to the way macros currently work in Rust this crate reexports the [`paste`] crate since it's needed to construct
//! identifiers for setters and mutable getters.

#![no_std]
#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#![deny(rust_2018_idioms)]
#![deny(unreachable_pub)]

#[cfg(feature = "std")]
extern crate std;

pub use paste;

/// The error type returned when a slice provided to any of the [`FromByteSlice`] methods didn't meet their size
/// constraints.
#[derive(Copy, Clone, Debug)]
pub struct InvalidSizeError;

impl core::fmt::Display for InvalidSizeError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.write_str("byte slice is not aligned to the structure's size")
    }
}

#[cfg(feature = "std")]
impl std::error::Error for InvalidSizeError {}

/// An **unsafe** trait for types that byte slices may be transmuted into.
///
/// This trait is usually automatically implemented by the [`format_struct`] macro so there is no need to implement it
/// manually.
///
/// All of the trait's methods could be implemented automatically but are not due to limitations of the Rust's generics:
/// using `Self` in a const context (array size on our case) isn't possible in traits. Since the trait isn't meant to
/// be implemented manually that is considered a non-issue.
///
/// # Safety
///
/// Types implementing the trait must be safe to transmute from an arbitrary byte slice that has proper size. That means
/// their alignment must be 1.
pub unsafe trait FromByteSlice: Sized {
    /// Transmutes an immutable byte slice reference into an immutable `Self` reference.
    ///
    /// # Errors
    ///
    /// Returns an error in case the size doesn't match the type's size.
    fn from_byte_slice(s: &[u8]) -> Result<&Self, InvalidSizeError>;

    /// Transmutes a mutable byte slice reference into a mutable `Self` reference.
    ///
    /// # Errors
    ///
    /// Returns an error in case the size doesn't match the type's size.
    fn from_byte_slice_mut(s: &mut [u8]) -> Result<&mut Self, InvalidSizeError>;

    /// Transmutes an immutable byte slice reference into an immutable to a slice of `Self`.
    ///
    /// # Errors
    ///
    /// Returns an error in case the size isn't a multiple of the type's size.
    fn slice_from_byte_slice(s: &[u8]) -> Result<&[Self], InvalidSizeError>;

    /// Transmutes a mutable byte slice reference into a mutable to a slice of `Self`.
    ///
    /// # Errors
    ///
    /// Returns an error in case the size isn't a multiple of the type's size.
    fn slice_from_byte_slice_mut(s: &mut [u8]) -> Result<&mut [Self], InvalidSizeError>;
}

/// Defines a structure that can be transmuted from/into a byte slice for parsing/constructing binary formats in a
/// zero-copy way. That works due to the generated structure having alignment of 1 byte and no internal padding.
/// Generated structures will have the [`FromByteSlice`] trait implemented on them.
///
/// The macro accepts syntax similar to a standard structure definition in Rust with some differences:
///
/// * The `struct` keyword is followed by either `little` or `big` keywords that specify which endianness to use for
/// the structure's integer fields.
/// * Fields of the generated structure may not have any *meta* attached to them which includes the docs. This may be
/// changed in the future.
///
/// # Examples
///
/// ```rust
/// # use format_struct::format_struct;
/// format_struct! {
///     /// A little-endian test structure.
///     #[derive(Default, Clone)]
///     pub struct little Test {
///         byte: u8,
///         short: u16,
///         word: i32,
///         dword: i64,
///         qword: u128,
///         byte_arr: [u8; 16],
///     }
/// }
/// ```
///
/// It is also possible to define multiple structures in one macro invocation:
///
/// ```rust
/// # use format_struct::format_struct;
/// format_struct! {
///     struct little Foo {
///         byte: u8,
///     }
///
///     struct big Bar {
///         a: u64,
///     }
///
///     pub struct little Baz {
///         z: [u8; 33],
///     }
/// }
/// ```
///
/// # Allowed field types
///
/// Currently only integer types (`u8`, `u16`, `u32`, `u64`, `u128` and their signed counterparts) are allowed and
/// statically sized byte arrays (`[u8; N]`).
///
/// # Layout
///
/// The fields in the structure are laid out in declaration order without any padding. That means that the following
/// structure will take 7 bytes instead of 16 you might expect:
///
/// ```rust
/// # use format_struct::format_struct;
/// format_struct! {
///     struct little SmallStruct {
///         byte: u8,
///         dword: u64,
///     }
/// }
/// ```
///
/// # Inner workings
///
/// Structures generated by this macro will have their integer fields replaced with appropriately sized byte arrays.
/// Integer fields will be exposed by generated getters and setters which use `from_(le|be)_bytes` and
/// `to_(le|be)_bytes` to convert between the integer types and byte arrays. Byte array fields will be stored as is and
/// exposed using references.
#[macro_export]
macro_rules! format_struct {
    ($($(#[$m:meta])* $vis:vis struct $endian:tt $name:ident {$($field_name:ident: $ty:tt),*,})+) => {
        $(
            #[repr(C)]
            $(#[$m])*
            $vis struct $name {
                $($field_name: format_struct!(@store_type $ty)),*
            }

            impl $name {
                $(format_struct!{@getter $endian $field_name $ty})*

                $(format_struct!{@setter_or_mut $endian $field_name $ty})*
            }

            impl AsRef<[u8]> for $name {
                fn as_ref(&self) -> &[u8] {
                    let ptr = self as *const Self as *const u8;
                    unsafe { ::core::slice::from_raw_parts(ptr, ::core::mem::size_of::<Self>()) }
                }
            }

            impl AsMut<[u8]> for $name {
                fn as_mut(&mut self) -> &mut [u8] {
                    let ptr = self as *mut Self as *mut u8;
                    unsafe { ::core::slice::from_raw_parts_mut(ptr, ::core::mem::size_of::<Self>()) }
                }
            }

            unsafe impl $crate::FromByteSlice for $name {
                fn from_byte_slice(s: &[u8]) -> ::core::result::Result<&Self, $crate::InvalidSizeError> {
                    let bytes: &[u8; ::core::mem::size_of::<Self>()] = ::core::convert::TryInto::try_into(s).map_err(|_| $crate::InvalidSizeError)?;

                    Ok(unsafe { ::core::mem::transmute(bytes) })
                }

                fn from_byte_slice_mut(s: &mut [u8]) -> ::core::result::Result<&mut Self, $crate::InvalidSizeError> {
                    let bytes: &mut [u8; ::core::mem::size_of::<Self>()] = ::core::convert::TryInto::try_into(s).map_err(|_| $crate::InvalidSizeError)?;

                    Ok(unsafe { ::core::mem::transmute(bytes) })
                }

                fn slice_from_byte_slice(s: &[u8]) -> ::core::result::Result<&[Self], $crate::InvalidSizeError> {
                    if s.is_empty() {
                        return Ok(&[]);
                    } else if s.len() % ::core::mem::size_of::<Self>() != 0 {
                        return ::core::result::Result::Err($crate::InvalidSizeError);
                    }

                    let size = s.len() / ::core::mem::size_of::<Self>();
                    let ptr = s.as_ptr() as *const Self;

                    ::core::result::Result::Ok(unsafe { ::core::slice::from_raw_parts(ptr, size) })
                }

                fn slice_from_byte_slice_mut(s: &mut [u8]) -> ::core::result::Result<&mut [Self], $crate::InvalidSizeError> {
                    if s.is_empty() {
                        return Ok(&mut []);
                    } else if s.len() % ::core::mem::size_of::<Self>() != 0 {
                        return ::core::result::Result::Err($crate::InvalidSizeError);
                    }

                    let size = s.len() / ::core::mem::size_of::<Self>();
                    let ptr = s.as_mut_ptr() as *mut Self;

                    ::core::result::Result::Ok(unsafe { ::core::slice::from_raw_parts_mut(ptr, size) })
                }
            }

            impl ::core::fmt::Debug for $name {
                fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
                    f.debug_struct(stringify!($name))
                        $(.field(stringify!($field_name), $crate::format_struct!(@debug_target self.$field_name $ty)))*
                        .finish()
                }
            }
        )+
    };
    (@store_type [u8; $sz:literal]) => {[u8; $sz]};
    (@store_type $ty:ty) => {[u8; ::core::mem::size_of::<$ty>()]};
    (@getter $endian:tt $field_name:ident [u8; $sz:literal]) => {
        pub const fn $field_name(&self) -> &[u8; $sz] { &self.$field_name }
    };
    (@getter little $field_name:ident $ty:ty) => {
        pub const fn $field_name(&self) -> $ty { <$ty>::from_le_bytes(self.$field_name) }
    };
    (@getter big $field_name:ident $ty:ty) => {
        pub const fn $field_name(&self) -> $ty { <$ty>::from_be_bytes(self.$field_name) }
    };
    (@setter_or_mut $endian:tt $field_name:ident [u8; $sz:literal]) => {
        $crate::paste::paste!{
            pub fn [<$field_name _ mut>](&mut self) -> &mut [u8; $sz] { &mut self.$field_name }
        }
    };
    (@setter_or_mut little $field_name:ident $ty:ty) => {
        $crate::paste::paste!{
            pub fn [<set _ $field_name>](&mut self, value: $ty) { self.$field_name = value.to_le_bytes() }
        }
    };
    (@setter_or_mut big $field_name:ident $ty:ty) => {
        $crate::paste::paste!{
            pub fn [<set _ $field_name>](&mut self, value: $ty) { self.$field_name = value.to_be_bytes() }
        }
    };
    (@debug_target $self:ident.$field_name:ident [u8; $sz:literal]) => {&$self.$field_name};
    (@debug_target $self:ident.$field_name:ident $ty:ty) => {&$self.$field_name()};
}

#[cfg(test)]
#[allow(unused, unreachable_pub)]
mod tests {
    format_struct! {
        #[derive(Default, Clone)]
        struct little TestLe {
            byte: u8,
            short: u16,
            word: u32,
            dword: u64,
            qword: u128,
            byte_arr: [u8; 16],
        }

        #[derive(Default, Clone)]
        struct big TestBe {
            byte: u8,
            short: u16,
            word: u32,
            dword: u64,
            qword: u128,
            byte_arr: [u8; 16],
        }
    }

    #[test]
    fn test_access_byte_arr() {
        let mut test = TestLe::default();

        for b in 0..16 {
            test.byte_arr_mut()[b as usize] = b;
        }

        assert_eq!(test.byte_arr()[5], 5);
    }

    #[test]
    fn test_access_u8() {
        let mut test = TestLe::default();

        test.set_byte(42);
        assert_eq!(test.byte(), 42);
    }

    #[test]
    fn test_access_u16() {
        let mut test_le = TestLe::default();
        test_le.set_short(1337);
        assert_eq!(test_le.short(), 1337);
        assert_eq!(test_le.short, 1337u16.to_le_bytes());

        let mut test_be = TestBe::default();
        test_be.set_short(1337);
        assert_eq!(test_be.short(), 1337);
        assert_eq!(test_be.short, 1337u16.to_be_bytes());
    }

    #[test]
    fn test_access_u32() {
        let mut test_le = TestLe::default();
        test_le.set_word(13371337);
        assert_eq!(test_le.word(), 13371337);
        assert_eq!(test_le.word, 13371337u32.to_le_bytes());

        let mut test_be = TestBe::default();
        test_be.set_word(13371337);
        assert_eq!(test_be.word(), 13371337);
        assert_eq!(test_be.word, 13371337u32.to_be_bytes());
    }

    #[test]
    fn test_access_u64() {
        let mut test_le = TestLe::default();
        test_le.set_dword(1337133713371337);
        assert_eq!(test_le.dword(), 1337133713371337);
        assert_eq!(test_le.dword, 1337133713371337u64.to_le_bytes());

        let mut test_be = TestBe::default();
        test_be.set_dword(1337133713371337);
        assert_eq!(test_be.dword(), 1337133713371337);
        assert_eq!(test_be.dword, 1337133713371337u64.to_be_bytes());
    }

    #[test]
    fn test_access_u128() {
        let mut test_le = TestLe::default();
        test_le.set_qword(13371337133713371337133713371337);
        assert_eq!(test_le.qword(), 13371337133713371337133713371337);
        assert_eq!(
            test_le.qword,
            13371337133713371337133713371337u128.to_le_bytes()
        );

        let mut test_be = TestBe::default();
        test_be.set_qword(13371337133713371337133713371337);
        assert_eq!(test_be.qword(), 13371337133713371337133713371337);
        assert_eq!(
            test_be.qword,
            13371337133713371337133713371337u128.to_be_bytes()
        );
    }
}