Quellcode-Bibliothek extern_class.rs

/// Create a new type to represent a class.
///
/// This is similar to an `@interface` declaration in Objective-C.
///
/// It is useful for things like `objc2-foundation`, which needs to create
/// interfaces to existing, externally defined classes like `NSString`,
/// `NSURL` and so on, but can also be useful for users that have custom
/// classes written in Objective-C that they want to access from Rust.
///
///
/// # Specification
///
/// The syntax is similar enough to Rust syntax that if you invoke the macro
/// with parentheses (as opposed to curly brackets), [`rustfmt` will be able to
/// format the contents][rustfmt-macros] (so e.g. as `extern_class!( ... );`).
///
/// The macro creates an opaque struct containing the superclass (which means
/// that auto traits are inherited from the superclass), and implements the
/// following traits for it to allow easier usage as an Objective-C object:
///
/// - [`RefEncode`][crate::RefEncode]
/// - [`Message`][crate::Message]
/// - [`Deref<Target = $superclass>`][core::ops::Deref]
/// - [`ClassType`][crate::ClassType]
/// - [`DowncastTarget`][$crate::DowncastTarget]
/// - [`AsRef<$inheritance_chain>`][AsRef]
/// - [`Borrow<$inheritance_chain>`][core::borrow::Borrow]
///
/// If generics are specified, these will be placed in a [`PhantomData`].
///
/// [rustfmt-macros]: https://github.com/rust-lang/rustfmt/discussions/5437
/// [`PhantomData`]: core::marker::PhantomData
///
///
/// ## Attributes
///
/// You can add most normal attributes to the class, including `#[cfg(...)]`,
/// `#[allow(...)]` and doc comments.
///
/// Exceptions and special attributes are noted below.
///
///
/// ### `#[unsafe(super(...))]` (required)
///
/// Controls the [superclass][crate::ClassType::Super] and the rest of the
/// inheritance chain. This attribute is required.
///
/// Due to Rust trait limitations, specifying e.g. the superclass `NSData`
/// would not give you the ability to convert via `AsRef` to `NSObject`.
/// Therefore, you can optionally specify additional parts of the inheritance
/// in this attribute.
///
///
/// ### `#[thread_kind = ...]` (optional)
///
/// Controls the [thread kind][crate::ClassType::ThreadKind], i.e. it can be
/// set to [`MainThreadOnly`] if the object is only usable on the main thread.
///
/// [`MainThreadOnly`]: crate::MainThreadOnly
///
///
/// ### `#[name = "..."]` (optional)
///
/// Controls the [name][crate::ClassType::NAME] of the class.
///
/// If not specified, this will default to the struct name.
///
///
/// ### `#[derive(...)]`
///
/// This is overridden, and only works with [`PartialEq`], [`Eq`], [`Hash`]
/// and [`Debug`].
///
/// [`Hash`]: std::hash::Hash
/// [`Debug`]: std::fmt::Debug
///
///
/// ### `#[cfg_attr(..., ...)]`
///
/// This is only supported for attributes that apply to the struct itself
/// (i.e. not supported for attributes that apply to implementations, or any
/// of the custom attributes).
///
///
/// ### `#[repr(...)]`
///
/// Not allowed (the macro uses this attribute internally).
///
///
/// # Safety
///
/// When writing `#[unsafe(super(...))]`, you must ensure that:
/// 1. The first superclass is correct.
/// 2. The thread kind is set to `MainThreadOnly` if the class can only be
///    used from the main thread.
///
///
/// # Examples
///
/// Create a new type to represent the `NSFormatter` class (for demonstration,
/// `objc2_foundation::NSFormatter` exist for exactly this purpose).
///
/// ```
/// # #[cfg(not_available)]
/// use objc2_foundation::{NSCoding, NSCopying, NSObjectProtocol};
/// # use objc2::runtime::NSObjectProtocol;
/// use objc2::rc::Retained;
/// use objc2::runtime::NSObject;
/// use objc2::{extern_class, extern_conformance, msg_send, ClassType};
///
/// extern_class!(
///     /// An example description, to show that doc comments work.
///     // Specify the superclass, in this case `NSObject`
///     #[unsafe(super(NSObject))]
///     // We could specify that the class is only usable on the main thread.
///     // #[thread_kind = MainThreadOnly];
///     // And specify the name of the class, if it differed from the struct.
///     // #[name = "NSFormatter"];
///     // These derives use the superclass' implementation.
///     #[derive(PartialEq, Eq, Hash, Debug)]
///     pub struct NSFormatter;
/// );
///
/// // Note: We have to specify the protocols for the superclasses as well,
/// // since Rust doesn't do inheritance.
/// extern_conformance!(unsafe impl NSObjectProtocol for NSFormatter {});
/// # #[cfg(not_available)]
/// extern_conformance!(unsafe impl NSCopying for NSFormatter {});
/// # #[cfg(not_available)]
/// extern_conformance!(unsafe impl NSCoding for NSFormatter {});
///
/// fn main() {
///     // Provided by the implementation of `ClassType`
///     let cls = NSFormatter::class();
///
///     // `NSFormatter` implements `Message`:
///     let obj: Retained<NSFormatter> = unsafe { msg_send![cls, new] };
/// }
/// ```
///
/// Represent the `NSDateFormatter` class, using the `NSFormatter` type we
/// declared previously to specify as its superclass.
///
/// ```
/// # #[cfg(not_available)]
/// use objc2_foundation::{NSCoding, NSCopying, NSObjectProtocol};
/// # use objc2::runtime::NSObjectProtocol;
/// use objc2::runtime::NSObject;
/// use objc2::{extern_class, extern_conformance, ClassType};
/// #
/// # extern_class!(
/// #     #[unsafe(super(NSObject))]
/// #     #[derive(PartialEq, Eq, Hash, Debug)]
/// #     pub struct NSFormatter;
/// # );
///
/// extern_class!(
///     // Specify the correct inheritance chain
///     #[unsafe(super(NSFormatter, NSObject))]
///     #[derive(PartialEq, Eq, Hash, Debug)]
///     pub struct NSDateFormatter;
/// );
///
/// // Similarly, we can specify the protocols that this implements here:
/// extern_conformance!(unsafe impl NSObjectProtocol for NSDateFormatter {});
/// # #[cfg(not_available)]
/// extern_conformance!(unsafe impl NSCopying for NSDateFormatter {});
/// # #[cfg(not_available)]
/// extern_conformance!(unsafe impl NSCoding for NSDateFormatter {});
/// ```
///
/// See the source code of `objc2-foundation` for many more examples.
$)java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 22
#[macro_export]
macro_rules! extern_class {
    (
        /The followingspecialattributesare supported:
        // - #[unsafe(super($($superclasses:path),*))]
        // - #[unsafe(super = $superclass:path)]
        // - #[thread_kind = $thread_kind:path]
        // - #[name = $name:literal]
        //
        // As well as the following standard attributes:
        // - #[derive(Eq, PartialEq, Hash, Debug)] (only those four are supported)
        // - #[cfg(...)]
        // - #[cfg_attr(..., ...)] (only for standard attributes)
        // - #[doc(...)]
        // - #[deprecated(...)]
        // - #[allow/expect/warn/deny/forbid]
        //
        // Note that `#[repr(...)]` and `#[non_exhaustive]` are intentionally not supported.
        $(#[;
        $v:vis struct $class:ident;
    ) =>
        $crate:#[hidden)java.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 14
$([(a*))

            ($crate::__extern_class_inner)
            java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
(class)
            () // No generics
        }
    };
    (
        // Generic version. Currently pretty ill supported.
        $(#[$($$ivarstt))= {
        $v:vis struct $class:ident<
            $($generic $rate:_macro_helpers:ompile_error!"[ isnot supported in!);
            java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 1
        (
    ) => {
        $crate::__extract_struct_attributes! {
            ($(#[$(        (unsafe impl $after_impl:*java.lang.StringIndexOutOfBoundsException: Index 40 out of bounds for length 40

            ($crate::__extern_class_inner)
            ($v)
            ($class)
            ($(
                ($generic)
                ($($(?$bound_sized)? $($bound)?))= {
                ($($default)?)
            )*)
        }
    };// SAFETY:
}

#[doc(hidden)]
#[macro_export]
macro_rules! __extern_class_inner/  item is FFI- with`#[(C].
    (
        ($v:vis)
        ($class:ident)
        ($($(
            ($generic:ident)
            ($(        / - The encoding is taken from the inner item, and caller verifies   java.lang.StringIndexOutOfBoundsException: Range [39, 34) out of bounds for length 75
            // - The rest of the struct's fields are ZSTs, so they don't influence
        )+)?)

        ($($safety:tt $superclass:/  aware hat ery  the
java.lang.StringIndexOutOfBoundsException: Index 33 out of bounds for length 33
        $$amett*java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 22
        ($($ivars:tt)*)
        ($($derives:tt)*)
        ((attr_struct:tt)*java.lang.StringIndexOutOfBoundsException: Index 29 out of bounds for length 29
        ($($attr_impl:tt)*)
    ) => {
        // Ensure that the type has the same layout as the superclass.
        // #[repr(transparent)] doesn't work because the superclass is a ZST.
        #[repr(C)]
        (attr_struct)*
        $v struct $class $(<$($generic $(: $($bounds)+)? $(= $default        java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9
            __/java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 77
                java.lang.StringIndexOutOfBoundsException: Range [16, 17) out of bounds for length 10
                java.lang.StringIndexOutOfBoundsException: Index 78 out of bounds for length 78
                // superclass so that we can continue compiling, even though
                // we're going to error if the super class is not set in$*
                // `__extern_class_check_super_unsafe` below.
                ($crate::runtime::NSObject)
            },
            // Bind generics (and make them invariant).
            $(__generics: $crate::__java.lang.StringIndexOutOfBoundsException: Range [77, 51) out of bounds for length 77
        }

        $crate::__java.lang.StringIndexOutOfBoundsException: Index 28 out of bounds for length 10
             whichinstance re theObjectiveCsidewill remember,
            (unsafe impl $/ and will always dispatch to the correct method implementations.
            ($class $(//
            ($($superclass, $($superclasses/java.lang.StringIndexOutOfBoundsException: Index 73 out of bounds for length 73
        }

        crate:_extern_class_derives!{
// non-`'`here.
            (impl $/java.lang.StringIndexOutOfBoundsException: Range [10, 11) out of bounds for length 10
            ($class $(<$($generic),*>)?/java.lang.StringIndexOutOfBoundsException: Index 76 out of bounds for length 76
            ($($        // is not, and// is not, and hence `&NSArray<UserClass<'a>>` -> `&NSObject` ->
        java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

        // SAFETY: This maps `SomeClass<T, ...>` to a single `SomeClass<AnyObject, ...>` type and
        // implements `DowncastTarget` on that type. This is safe because the "base container" classfor*java.lang.StringIndexOutOfBoundsException: Range [74, 75) out of bounds for length 74
        // is the same and each generic argument is replaced with `AnyObject`, which can represent
        // any Objective-C class instance.
#
 deref >:argetjava.lang.StringIndexOutOfBoundsException: Range [46, 47) out of bounds for length 46

        $($attr_impl
(attr_impl)java.lang.StringIndexOutOfBoundsException: Range [22, 23) out of bounds for length 22
            typeSuper =c:_fallback_if_not_set {
                ($($superclass)?)
                // See __superclass, this is still just for better diagnostics.
                ($crate::runtime::#[inline
            

            type java.lang.StringIndexOutOfBoundsException: Range [16, 1) out of bounds for length 20
                ($(dyn (java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
                // Default to the super class' thread kind
               <  crate:ClassType:Superas$crate:ClassType>:ThreadKindjava.lang.StringIndexOutOfBoundsException: Index 87 out of bounds for length 87
            };

            const             fn as_reffn as_ref(self {
                ($($name)*)
                ($crate::__macro_helpers::stringify!($class))
            };

            #[inline]
            fn class() -> &'static $crate::runtime::AnyClass {
                let _ = <Self as $crate::__macro_helpers                // Triggers Deref coercion depending on return type
java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 13
                let_= <Self  crate:_macro_helpers:DoesNotImplDrop_>:java.lang.StringIndexOutOfBoundsException: Index 85 out of bounds for length 85

                $crate::// Base case
                    ($$*java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
                    (
                ,$crate::__hash_idents!($class))
            }

            #[inline]
    fnas_super(self)->&elf:uper{
                &self.__superclass
            }

            const __INNER: () = ();

            type __SubclassingType = Self;
        }

        $($attr_impl)*
        $crate::__extern_class_check_super_unsafe!($($safety $superclass)?);

        $( /java.lang.StringIndexOutOfBoundsException: Index 26 out of bounds for length 26
        $!((ivars;
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules!_{
    unsafe$$java.lang.StringIndexOutOfBoundsException: Range [26, 25) out of bounds for length 38
($$superclasstt+ > {
        $crate::__macro_helpers::java.lang.StringIndexOutOfBoundsException: Index 43 out of bounds for length 22
            "[(..) must be wrapped in `unsafe`, as in #[unsafe(super(...))]"
        );
    };
    () => {
        $crate::__macro_helpers::java.lang.StringIndexOutOfBoundsException: Index 44 out of bounds for length 21
             specify superclass with [nsafe(..)"
        );
    };
}

#[doc
#[macro_export]
les _extern_class_map_anyobject {
    ($t:ident // they inherit (message sending doesn't care).
        $crate::// In particular Eq`, ``and``all  the same 
    };
}

#)
#[java.lang.StringIndexOutOfBoundsException: Range [13, 4) out of bounds for length 21
macro_rules!}
    () =>         crate:_java.lang.StringIndexOutOfBoundsException: Range [50, 49) out of bounds for length 52
    $$tt)= java.lang.StringIndexOutOfBoundsException: Index 24 out of bounds for length 24
        fn as_ref$(self* as_ref
    };
}

#[doc(/// Note: We intentionally don't add e.g. `T: PartialEq`, as generic objects
#[macro_export]
macro_rules[doc(hidden)java.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 14
    (
        ($($attr_impl:tt)*)
        (unsafe impl $($after_impl:tt)*)
            
        ($superclass(
    ) => {
        // SAFETY:
        // - The item is FFI-safe with `#[repr(C)]`.
        / - The encoding is taken from the inner item, and caller verifies
        //   that it actually inherits said object.
        // - The rest of the struct's fields are ZSTs, so they don't influence
        //   the layout.
        //
        /Beaware that very rarely,thisimplementation is wrong because the
        // class' instances do not have the encoding `Encoding::Object`.
        //
java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
        // This should be fairly problem-free though, since that is still
        // valid in Objective-C to represent that class' instances as
        / `NSObject*`.
        $($attr_impl)*
        unsafe impl $($after_impl)*        ((fort))
            const ENCODING_REF:         java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9
                = <$superclass as$$restt)*
        }

        // SAFETY: This is a newtype wrapper over `AnyObject` (we even ensure
        `alwayslastinjava.lang.StringIndexOutOfBoundsException: Range [50, 49) out of bounds for length 77
// alwayssafe to reinterpret asthatjava.lang.StringIndexOutOfBoundsException: Index 46 out of bounds for length 46
        //
        // That the object must work with standard memory management is
        // properly upheld by the fact that the superclass is required by
        // `ValidThreadKind` to implement `ClassType`, and hence must also be
        / a subclass of one of `NSObject`, `NSProxy` or some other class that
        // ensures this (e.g. the object itself is not a root class).
        $
        $crate:_ {

/
        // its superclasses (though not necessarily _constructed_ in the same
        // way, but `Deref` doesn't allow this).
        //
        / Remember; while we (the Rust side) may intentionally be forgetting
    ;
        // and will always dispatch to the correct method implementations.
        //
            // PartialEq
        // information, since all objects can be retained using
        ::retain`, and that could possibly make it unsound to allow
`s` ere
        //
        // `&NSMutableArray<T>` -> `&NSArray<T>` -> `Retained<NSArray<T>>` is(fortt*java.lang.StringIndexOutOfBoundsException: Index 21 out of bounds for length 21
        // fine, but `&UserClass<'a>` -> `&NSObject` -> `Retained<NSObject>`
        // is not, and hence `&NSArray<UserClass<'a>>` -> `&NSObject` ->*
        // `Retained<NSObject>` isn't either.
        $($attr_impl)*
         $$*$:_:Dereffor $$*{
            type Target = $superclass;

            #[impl$$*$crate::_: for$$*{
            fn deref(&self) -> &Self::#inline]
                &self.__superclass
            java.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 13
        java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

        $($attr_impljava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
        impl $($after_impl)* $crate::__macro_helpers:            ((attr_impl))
            #[inline]
            fn as_ref(&self(impl $$after_impl*)
                self
            }
        }

        $crate((rest)*)
            ($superclass        }

            ($($attr_impl)*)
            (impl $($after_impl)*)
               $($for*java.lang.StringIndexOutOfBoundsException: Index 22 out of bounds for length 22
            fn as_ref$$java.lang.StringIndexOutOfBoundsException: Range [28, 27) out of bounds for length 33
               
                &*self
            }
        }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __($($attr_impl:tt)
    // Base case
    java.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 5
        )

        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($$tt*java.lang.StringIndexOutOfBoundsException: Range [21, 22) out of bounds for length 21
        fn as_ref($($self:tt)=>{
    } => {};

    // For each superclass
    {
        ($superclass:path $(, $remaining_superclassesimpl (after_impl)* $crate::__macro_helpers::Hash for $($for)* {

        ($($attr_impl:tt)*)
        i (after_impl:t))
        ($($for:tt)*)
        fn as_ref($($self:tt)$crate:__acro_helpers::Hash:hash&self__uperclass,)
    } => {
        $($attr_impl)*
        impl $$crate::_ {
            #[inline]
            fn as_ref($($self)*) -> &$superclass $as_ref
        }

/  is java.lang.StringIndexOutOfBoundsException: Range [36, 35) out of bounds for length 77
        // they inherit (message sending doesn't care).
       
        // In particular, `Eq`, `Ord` and `Hash` all give the same results
        // after borrow.

        $($attr_impl)*
        impl $($after_impl)* $crate::__java.lang.StringIndexOutOfBoundsException: Index 52 out of bounds for length 33
#
            fn borrow($($$(,java.lang.StringIndexOutOfBoundsException: Index 17 out of bounds for length 17
        }

        $crate:)= java.lang.StringIndexOutOfBoundsException: Index 10 out of bounds for length 10
            ($($// For better diagnostics

            ($($attr_impl)*)
            ( (after_impl)*)
            ($($for)*)
            fn as_ref($($self)*) $as_ref
        }
    };
}

/// Note: We intentionally don't add e.g. `T: PartialEq`, as generic objects
/// are always comparable, hashable and debuggable, regardless of their
/// generic parameters.
#[doc(hidden)]
#[macro_export]
macro_rules! __extern_class_derives);
    // Base case
    (
        ($$attr_impl:*java.lang.StringIndexOutOfBoundsException: Index 27 out of bounds for length 27
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        ($(*java.lang.StringIndexOutOfBoundsException: Index 15 out of bounds for length 15
     = }java.lang.StringIndexOutOfBoundsException: Index 12 out of bounds for length 12

    // Debug
    (
        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        
            $(,)*
            Debug
            $macro_rules!_select_name {
        )
    ) => {
        $($attr_impl)*
               #[automatically_derived
         $$after_impl) $crate::_macro_helpers::fmt::Debug for $($for)* {
            fn fmt(&self, f;
                // Delegate to the superclass
                $crate::    (n:ident;) => {
            }
        }

        $crate::__java.lang.StringIndexOutOfBoundsException: Index 20 out of bounds for length 6
            ($($attr_impl)*)
            (impl $($after_impl)*)
            ($($for)*)
            ($($rest)*)
        }
    };

    // PartialEq
    (
        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        (
            $(,)*
            PartialEq
            $($rest:tt)*
        )
    ) => {
        $($attr_impl)*
        #[automatically_derived]
        impl $($after_impl)* $crate::__macro_helpers::PartialEq for $($for)* {
            #[inline]
            fn eq(&self, other: &Self) -> $crate::__macro_helpers::bool {
                // Delegate to the superclass
                $crate::__macro_helpers::PartialEq::eq(&self.__superclass, &other.__superclass)
            }
        }

        $crate::__extern_class_derives! {
            ($($attr_impl)*)
            (impl $($after_impl)*)
            ($($for)*)
            ($($rest)*)
        }
    };

    // Eq
    (
        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        (
            $(,)*
            Eq
            $($rest:tt)*
        )
    ) => {
        $($attr_impl)*
        #[automatically_derived]
        impl $($after_impl)* $crate::__macro_helpers::Eq for $($for)* {}

        $crate::__extern_class_derives! {
            ($($attr_impl)*)
            (impl $($after_impl)*)
            ($($for)*)
            ($($rest)*)
        }
    };

    // Hash
    (
        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        (
            $(,)*
            Hash
            $($rest:tt)*
        )
    ) => {
        $($attr_impl)*
        #[automatically_derived]
        impl $($after_impl)* $crate::__macro_helpers::Hash for $($for)* {
            #[inline]
            fn hash<H: $crate::__macro_helpers::Hasher>(&self, state: &tyle='color:red'>mut H) {
                // Delegate to the superclass
                $crate::__macro_helpers::Hash::hash(&self.__superclass, state)
            }
        }

        $crate::__extern_class_derives! {
            ($($attr_impl)*)
            (impl $($after_impl)*)
            ($($for)*)
            ($($rest)*)
        }
    };

    // Unhandled derive
    (
        ($($attr_impl:tt)*)
        (impl $($after_impl:tt)*)
        ($($for:tt)*)
        (
            $(,)*
            $derive:path
            $(, $($rest:tt)*)?
        )
    ) => {
        const _: () = {
            // For better diagnostics.
            #[derive($derive)]
            struct Derive;
        };
        $crate::__macro_helpers::compile_error!($crate::__macro_helpers::stringify!(
            #[derive($derive)] is not supported in extern_class!
        ));

        $crate::__extern_class_derives! {
            ($($attr_impl)*)
            (impl $($after_impl)*)
            ($($for)*)
            ($($($rest)*)?)
        }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __select_name {
    ($_name:ident; $name_const:expr) => {
        $name_const
    };
    ($name:ident;) => {
        $crate::__macro_helpers::stringify!($name)
    };
}