newtypedecl 0.0.1

#![doc = include_str!("../README.md")]

/// Error returned when the inner failed the invariant check or can't be constructed.  Note
/// that we can not return a failed inner value since there are to many cases where the inner
/// is destructively updated or contains references with lifetimes which would put a lot
/// burden and limitations on error handling only for cases that should rarely happen.
#[derive(Debug)]
pub struct InvariantFailure;

/// The trait defined for all newtypes.
///
/// `Newtype` only contains associated functions and types. Users are advised generally
/// **not** to use its functions, at best use it as Marker when needed.  Only use these trait
/// functions when implementing safe abstractions and methods for accessing the newtype.
/// Careless usage of its API will break contracts and invariants the newtype
/// establishes.  The `newtype!{}` macro implements and uses the functions defined here in a
/// safe way.
// We decided against marking `as_inner` and `as_inner_mut` unsafe, because that would taint
// all uses even in user code by the macro with unsafe calls which would make it impossible to
// use this crate in code that forbids unsafe_code.
pub trait Newtype: Sized {
    /// Actual wrapped inner type
    type Inner;

    /// Construct a newtype.  Will return `Err(InvariantFailure)` when the inner can not be
    /// converted to the newtypes inner type or the invariant of the type does not hold.
    #[allow(clippy::missing_errors_doc)]
    fn try_from_inner(inner: impl TryInto<Self::Inner>) -> Result<Self, InvariantFailure>;

    /// Construct a newtype, panics when the inner fails the invariant check
    #[inline]
    fn from_inner(t: impl Into<Self::Inner>) -> Self {
        Self::try_from_inner(t.into()).unwrap()
    }

    /// Replaces the inner with a new value, returns the old inner
    #[inline]
    fn replace_inner(this: &mut Self, new: Self::Inner) -> Self::Inner {
        Newtype::into_inner(std::mem::replace(this, Newtype::from_inner(new)))
    }

    /// Replaces the inner with the default value, returns the old inner
    #[inline]
    fn take_inner(this: &mut Self) -> Self::Inner
    where
        Self: Default,
    {
        Newtype::into_inner(std::mem::take(this))
    }

    /// Destruct a newtype, returning the inner
    fn into_inner(this: Self) -> Self::Inner;

    /// returns a clone of the inner
    #[inline]
    fn clone_inner(this: &Self) -> Self::Inner
    where
        Self::Inner: Clone,
    {
        Newtype::as_inner(this).clone()
    }

    /// returns a reference to the inner
    #[allow(unsafe_code)]
    fn as_inner(this: &Self) -> &Self::Inner;

    /// returns a mutable reference to the inner
    #[allow(unsafe_code)]
    fn as_inner_mut(this: &mut Self) -> &mut Self::Inner;

    /// Invariant check which must be true at all times
    #[inline]
    fn invariant(_inner: &Self::Inner) -> bool {
        true
    }
}

// PLANNED: trait Apply/ApplyInPlace

/// The newtype macro creates a struct with the given name and generates the boilerplate code
/// that comes with the newtype idiom.
///

/// # The newtype macro syntax
///
/// The macro extends rust syntax with some ergonomics. 
///
///
///
#[doc = include_str!(concat!(env!("OUT_DIR"), "/newtype_macro_syntax.md"))]

///
/// # The newtype macro generates
///
/// ## The struct for the user define newtype
///
/// The struct is generated as given. The newtype idiom is represented by a tuple-struct with
/// the first data member of the wrapped type. This tuple can have additional zero length
/// marker entries such as `PhantomData`, each of these must implement `Default`. Lifetimes
/// and generics can be used as usual. One can define any number of attributes before the
/// actual struct definition. This includes rustdoc comments as these are just syntactic sugar
/// for attributes. Both, the struct and the wrapped type can be declared `pub`.
///
/// Then the `Newtype` trait for the defined newtype. Currently the only user definable part
/// is the invariant function.
///
/// ## The generated API
///
/// ### Default without Control Block
///
/// When no control block is given (terminated with a semicolon) then a predefined set of
/// traits and member functions are implemented for the newtype. These are not the safest
/// choice but make sure that the newtype is usable. Currently these are:
#[doc = include_str!(concat!(env!("OUT_DIR"), "/newtype_predef.md"))]
///
/// Expect this set to change in future releases.
///
/// ### With user defined Control Block
///
/// When the user provides a control block then they control what traits and member functions
/// are available. There is a shortcut notation for supported traits and functions where only
/// the respective names are listed with plus signs delimiting each element.
///
/// #### Supported Functions
///
#[doc = include_str!(concat!(env!("OUT_DIR"), "/newtype_macro_fns.md"))]
///
/// #### Supported Traits
///
#[doc = include_str!(concat!(env!("OUT_DIR"), "/newtype_macro_traits.md"))]


// variant when generating docs
#[cfg(all(doc, not(doctest)))]
#[macro_export]
macro_rules! newtype {
    (
        // newtype with default API
        struct $name:ident(
            // Wrapped inner type
            $inner:ty
            // followed by any number of markers
            $(,$phantom:ty)*
        );
        $($cont:tt)*
    ) => {};

    (
        // newtype with control block defining the API
        struct $name:ident(
            // Wrapped inner type
            $inner:ty
            // followed by any number of markers
            $(,$phantom:ty)*
        )
        // Control block
        {
            // Newtype associated functions
            invariant ($value:ident) { $validating_code:tt }
            // Supported traits
            impl $Traitname:ident $(+$Traitnames:ident)*;
            // trait impls with custom or special block
            impl $Trait:ident $custom:block
            // Supported member functions
            fn $funcname:ident $(+$funcnames:ident)*;
            // Custom member functions
            fn $func:ident($($arg:ident: $type:ty),*) $(-> $result:ty)? $code:block
        }
        $($cont:tt)*
    ) => {};
}

// hide docs in normal compilation
#[doc(hidden)]
#[cfg(any(not(doc), doctest))]
#[macro_export]
macro_rules! newtype {
    ////syntax_struct
    //// ## The struct
    ////
    //// Newtypes are defined like tuple structs with a few specialties and limitations.
    ////
    //// * Attributes and rustdoc comments are supported as usual. Especially `#[derive(..)]`.
    ////   can be used as usual
    //// * Visibility specifiers such as `pub`, `pub(crate)` etc.
    //// * Lifetimes and generics including trait bounds
    //// * The first member must be the wrapped inner type, it can be generic.
    //// * Any additional member must be default constructible. This can be used to add
    ////   `PhantomData` and other markers or metadata/debug instrumentation.
    //// * The newtype is then terminated with a semicolon or a control block in braces.
    ////   * When terminated with a semicolon then some predefined traits and functions are
    ////     implemented for it
    ////   * When terminated with a control block then the user has full control of what
    ////     becomes implemented.
    ////
    //// Planned:
    ////
    //// * Special Support for boxed inner types, making the boxing transparent.
    //// * `where` clauses are not supported yet
    ////
    //// ## The control bock
    ////
    (
        $(#[$($attrs:meta)*])*
        $pub:vis struct $name:ident
        $(<
           $($lifetimes:lifetime),* $(,)?
           $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)? $(= $default:ty)?),*
        >)?
        (
            $(#[$($mattrs:meta)*])*
            $mpub:vis $inner:ty $(,$phantom:ty)*
        )
        $($cont:tt)*
    ) => {
        $(#[$($attrs)*])*
        $pub struct $name
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)? $(= $default)?),*
        >)?
        (
            $(#[$($mattrs)*])*
            $mpub $inner
            $(,$phantom)*
        );

        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)? ),*
        >)?
        $crate::Newtype for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        {
            type Inner = $inner;
            #[inline]
            fn try_from_inner(t: impl TryInto<Self::Inner>) -> Result<Self, $crate::InvariantFailure> {
                let t = t.try_into().map_err(|_| $crate::InvariantFailure)?;
                if !Self::invariant(&t) {
                    Err($crate::InvariantFailure)
                } else {
                    Ok(Self(t $(, <$phantom>::default())*))
                }
            }
            #[inline]
            fn into_inner(this: Self) -> Self::Inner { this.0 }
            #[inline]
            fn as_inner(this: &Self) -> &Self::Inner { &this.0 }
            #[inline]
            fn as_inner_mut(this: &mut Self) -> &mut Self::Inner { &mut this.0 }

            $crate::newtype!{
                @newtype(
                    $name
                    $(<
                        $($lifetimes,)*
                        $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                    >)?
                )
                $($cont)*
            }
        }

        $crate::newtype!{
            @impls(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    //
    // Newtype methods dispatcher
    //

    ////syntax_assocfn
    //// ### `trait Newtype` associated functions
    ////
    //// The `Newtype` trait becomes automatically implemented for each newtype.
    (
        @newtype(
            $name:ident
            $(<
               $($lifetimes:lifetime),* $(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        { $($impls:tt)* }
        $($_:tt)*
    ) => {
        $crate::newtype!{
            @newtype_fn(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($impls)*
        }
    };

    (@newtype$($_:tt)*) => {};

    // newtype associated functions

    ////syntax_assocfn
    //// The only user definable part here is the `invariant` function which uses the keyword
    //// `invariant` followed by a parameter name in parenthesis followed by a code block that
    //// validates the parameter. The parameter is a `&Inner` and the code block operating on
    //// this parameter must return a bool.
    ////
    //// `invariant (inner) {inner > 100}`
    ////
    (
        @newtype_fn(
            $name:ident
            $(<
               $($lifetimes:lifetime),* $(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $(#[$($attrs:meta)*])*
        invariant ($ref:ident) $code:block
        $($cont:tt)*
    ) => {
        $(#[$($attrs)*])*
        fn invariant ($ref: &Self::Inner) -> bool $code

        $crate::newtype!{
            @newtype_fn(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }

    };

    (@newtype_fn$($_:tt)*) => {};


    //
    // Impls block dispatcher
    //

    // ;
    (
        @impls(
            $name:ident
            $(<
               $($lifetimes:lifetime),* $(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        ;
        $($cont:tt)*
    ) => {
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            impl Deref + AsRef + Borrow + From;  ////predef * The traits {{/impl (.*);/$1/}}
            pub fn new;                          ////predef * The public function {{/fn (.*);$/$1/}}
            fn inner + into_inner + inner_mut;   ////predef * Private methods {{/fn (.*);/$1/}}
        }
        $crate::newtype!{$($cont)*}
    };

    // { impls } block
    (
        @impls(
            $name:ident
            $(<
               $($lifetimes:lifetime),* $(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        {$($impls:tt)*}
        $($cont:tt)*
    ) => {

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($impls)*
        }

        $crate::newtype!{$($cont)*}
    };

    //
    // trait impls
    //

    ////syntax_impltrait
    //// ## impl Trait
    ////
    //// The newtype macro can implement a number of common traits for the current newtype.
    //// In the simplest form this just needs `impl Trait;` the actual rules how to implement
    //// the trait are programmed into the macro. When one wants to implement more than one
    //// trait these can be conveniently chained with the plus sign `impl TraitA + TraitB +
    //// TraitC;`
    ////
    //// Some supported traits need a code block instead a semicolon. Usually this is the
    //// direct code block for one single trait function but the actual specification may
    //// differ.
    ////
    //// Traits for which the newtype macro has no special support can be written as `impl
    //// Trait { ..methods.. }` These support extra generics and lifetimes.  Note that you
    //// have to omit the `..for MyType..` part. The newtype macro knows for which type the
    //// trait will be implemented.
    ////
    //// Since the newtype struct is just a normal struct one can also implement traits
    //// outside of the macro block. This is necessary when implementing traits that take the
    //// newtype as type parameter and are implemented for something else:
    //// `impl From<MyNewtype> for OtherType ...`

    // impl Trait + Trait;
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl $trait:ident $(+$traits:ident)+;
        $($cont:tt)*
    ) => {
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            impl $trait;
            $(impl $traits;)+
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `Deref`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when the inner
    ////   value implements some interior mutability and mutating these can break the
    ////   contracts and invariants the newtype establishes. When in doubt do **not**
    ////   implement `Deref`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl Deref;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::ops::Deref for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            type Target = <Self as $crate::Newtype>::Inner;
            #[inline]
            fn deref(&self) -> &Self::Target {
                <Self as $crate::Newtype>::as_inner(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `DerefMut`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when mutating
    ////   the inner value mutating these can break the contracts and invariants the newtype
    ////   establishes. When in doubt do **not** implement `DerefMut`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl DerefMut;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::ops::DerefMut for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn deref_mut(&mut self) -> &mut Self::Target {
                <Self as $crate::Newtype>::as_inner_mut(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `AsRef`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when the inner
    ////   value implements some interior mutability and mutating these can break the
    ////   contracts and invariants the newtype establishes. When in doubt do **not**
    ////   implement `AsRef`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl AsRef;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::convert::AsRef<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn as_ref(&self) -> &<Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::as_inner(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `AsMut`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when mutating
    ////   the inner value mutating these can break the contracts and invariants the newtype
    ////   establishes. When in doubt do **not** implement `AsMut`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl AsMut;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::convert::AsMut<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn as_mut(&mut self) -> &mut <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::as_inner_mut(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `Borrow`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when the inner
    ////   value implements some interior mutability and mutating these can break the
    ////   contracts and invariants the newtype establishes. When in doubt do **not**
    ////   implement `Borrow`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl Borrow;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::borrow::Borrow<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn borrow(&self) -> &<Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::as_inner(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `BorrowMut`<br>
    ////   Dereferences to the inner value. Note that this is dangerous to use when mutating
    ////   the inner value mutating these can break the contracts and invariants the newtype
    ////   establishes. When in doubt do **not** implement `BorrowMut`.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl BorrowMut;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::borrow::BorrowMut<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn borrow_mut(&mut self) -> &mut <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::as_inner_mut(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `TryFrom`<br>
    ////   Will return `Err(InvariantFailure)` when the source can not be converted or the invariant check failed.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl TryFrom;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::convert::TryFrom<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype,
        {
            type Error=$crate::InvariantFailure;

            #[inline]
            fn try_from(value: <Self as $crate::Newtype>::Inner) -> Result<Self, Self::Error> {
                <Self as $crate::Newtype>::try_from_inner(value)
            }
        }
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `From`<br>
    ////   Will panic invariant check failed. Prefer to implement `TryFrom` when invariants are in use.
   (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl From;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::convert::From<<Self as $crate::Newtype>::Inner> for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn from(value: <Self as $crate::Newtype>::Inner) -> Self {
                <Self as $crate::Newtype>::from_inner(value)
            }
        }
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////trait
    //// * `Default{impl Into<Inner>}`<br>
    ////   The `Default` trait needs a body of a function that returns a type that implements
    ////   `Into<Inner>`. The rationale here is that we only need to implement `Default` when it
    ////   is distinct from the normal `Inner::default()` eg. when the normal default would
    ////   violate the invariant of the newtype. When normal default construction with
    ////   `Inner::default()` is sufficient then one can just `#[derive(Default)]` the
    ////   newtype. It will panic when the default inner generated here fails the invariant
    ////   check.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl Default $code:block
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        std::default::Default for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            fn default() -> Self {
                <Self as Newtype>::from_inner($code)
            }
        }
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    // impl $Trait $impl:block
    // TODO: generic doc
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        impl
        $(<
           $($newlifetimes:lifetime),*$(,)?
           $($newgeneric:ident$(: $newfirst:tt $(:: $newprest:ident)* $(+ $newmore:tt $(:: $newpmrest:ident)*)*)?),*
        >)?
        $trait:ty {$($methods:tt)*}
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($newlifetimes,)*
            $($lifetimes,)*
            $($newgeneric$(: $newfirst $(:: $newprest)* $(+ $newmore $(:: $newpmrest)*)*)?,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $trait for $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            $($methods)*
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    // recurse on newtype assoc functions
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $_fn:ident($_ref:ident) $_code:block
        $($cont:tt)*
    ) => {
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }

    };

    // terminate
    (@impl($($_:tt)*)) => {};

    //
    // fn impls
    //

    ////syntax_fn
    //// ## functions and methods
    ////
    //// As with implementing traits, the newtype macro can implement some known/common
    //// functions and methods for your newtype. The syntax is similar to the trait syntax,
    //// instead `impl Trait;` you use `fn name;` or `fn name_a + fn name_b + fn name_c;` to
    //// implement one of the predefined functions.
    ////
    //// Since defining an API using functions in the primary objective for newtypes you can
    //// also define full functions as you would do in a normal `fn MyType {}` block.
    ////

    // fn func + func;
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn $func:ident $(+ $funcs:ident)+;
        $($cont:tt)*
    ) => {
        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $pub fn $func;
            $($pub fn $funcs;)+
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn new(inner: impl Into<Inner>) -> Self`
    ////   `new` will panic when the `invariant` over inner fails. Use `try_new` when invariant is defined.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn new;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn new(inner: impl Into<<Self as $crate::Newtype>::Inner>) -> Self {
                <Self as $crate::Newtype>::from_inner(inner)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn try_new(inner: impl TryInto<Inner>) -> Result<Self, InvariantFailure>`<br>
    ////   Returns `InvariantFailure` when the newtype can't be constructed
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn try_new;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn try_new(inner: <Self as $crate::Newtype>::Inner) -> Result<Self, InvariantFailure> {
                <Self as $crate::Newtype>::try_from_inner(inner)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn into_inner(self) -> Inner`<br>
    ////   Destructures the newtype returning its inner value.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn into_inner;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn into_inner(self) -> <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::into_inner(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn take(&mut self) -> Inner where Self::Default`<br>
    ////   Replaces the inner value with the default for this type, returns the old inner value.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn take;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype + Default
        {
            #[inline]
            $pub fn take(&mut self) -> <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::take_inner(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn replace(&mut self, inner: Inner) -> Inner`<br>
    ////   Replaces the inner value with a new value, returns the old inner value.
    ////   May panic when the new inner value fails the invariant check.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn replace;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn replace(&mut self, new: <Self as $crate::Newtype>::Inner) -> <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::replace_inner(self, new)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn inner(&self) -> &Inner`<br>
    ////   Returns a reference to the inner value. Note that this is dangerous when the type
    ////   must uphold some invariants and the inner value supports some interior mutability.
    ////   Do **not** implement this method in such cases.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn inner;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn clone_inner(&self) -> <Self as $crate::Newtype>::Inner where <Self as $crate::Newtype>::Inner: Clone {
                <Self as $crate::Newtype>::as_inner(self).clone()
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn clone_inner(&self) -> Inner`<br>
    ////   Returns a clone of he inner value.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn inner;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn clone_inner(&self) -> <Self as $crate::Newtype>::Inner where <Self as $crate::Newtype>::Inner: Clone {
                <Self as $crate::Newtype>::as_inner(self).clone()
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    ////fn
    //// * `fn inner_mut(&mut self) -> &mut Inner`<br>
    ////   Returns a mutable reference to the inner value. Note that this is dangerous when the type
    ////   must uphold some invariants. Do **not** implement this method in such cases.
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $pub:vis fn inner_mut;
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            #[inline]
            $pub fn inner_mut(&mut self) -> &mut <Self as $crate::Newtype>::Inner {
                <Self as $crate::Newtype>::as_inner_mut(self)
            }
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    // generic function definitions
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $(#[$($attrs:meta)*])*
        $pub:vis fn $fnname:ident($($args:tt)*) $(-> $result:ty)? /*TODO: generics and where*/ $code:block
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            $(#[$($attrs)*])*
            $pub fn $fnname($($args)*) $(-> $result)? $code
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    // const fn
    (
        @impl(
            $name:ident
            $(<
               $($lifetimes:lifetime),*$(,)?
               $($generic:ident$(: $first:tt $(:: $prest:ident)* $(+ $more:tt $(:: $pmrest:ident)*)*)?$(= $default:ty)?),*
            >)?
        )
        $(#[$($attrs:meta)*])*
        $pub:vis const fn $fnname:ident($($args:tt)*) $(-> $result:ty)? /*TODO: generics and where*/ $code:block
        $($cont:tt)*
    ) => {
        impl
        $(<
            $($lifetimes,)*
            $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?),*
        >)?
        $name
        $(<
            $($lifetimes,)*
            $($generic),*
        >)?
        where Self: $crate::Newtype
        {
            $(#[$($attrs)*])*
            $pub const fn $fnname($($args)*) $(-> $result)? $code
        }

        $crate::newtype!{
            @impl(
                $name
                $(<
                    $($lifetimes,)*
                    $($generic$(: $first $(:: $prest)* $(+ $more $(:: $pmrest)*)*)?$(= $default)?),*
                >)?
            )
            $($cont)*
        }
    };

    // termination
    () => {};
}