Expose and document object! macro

Author: madsmtm

objc2-foundation/CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added `MainThreadMarker` to help with designing APIs where a method is only
   safe to call on the main thread.
 * Added `NSException` object.
+* Added `object!` macro to help with defining other classes.
+* Expose the `objc2` version that this uses in the crate root.
 
 ### Changed
 * Changed a few `Debug` impls.

objc2-foundation/src/array.rs

@@ -14,7 +14,7 @@ use super::{
     NSRange,
 };
 
-object! {
+__inner_object! {
     /// TODO
     ///
     /// You can have a `Id<NSArray<T, Owned>, Owned>`, which allows mutable access
@@ -43,7 +43,7 @@ unsafe impl<T: Sync + Send> Send for NSArray<T, Shared> {}
 unsafe impl<T: Sync> Sync for NSArray<T, Owned> {}
 unsafe impl<T: Send> Send for NSArray<T, Owned> {}
 
-object! {
+__inner_object! {
     // TODO: Ensure that this deref to NSArray is safe!
     // This "inherits" NSArray, and has the same `Send`/`Sync` impls as that.
     #[derive(Debug, PartialEq, Eq, Hash)]

objc2-foundation/src/dictionary.rs

@@ -9,7 +9,7 @@ use objc2::{msg_send, msg_send_id, Message};
 
 use super::{NSArray, NSCopying, NSEnumerator, NSFastEnumeration, NSObject};
 
-object! {
+__inner_object! {
     #[derive(Debug, PartialEq, Eq, Hash)]
     unsafe pub struct NSDictionary<K, V>: NSObject {
         key: PhantomData<Id<K, Shared>>,

objc2-foundation/src/lib.rs

@@ -71,6 +71,12 @@ pub use self::value::NSValue;
 #[doc(no_inline)]
 pub use objc2::ffi::{NSInteger, NSUInteger};
 
+#[doc(hidden)]
+pub use core as __core;
+
+// Expose the version of objc2 that this crate uses
+pub use objc2;
+
 #[cfg(feature = "apple")]
 #[link(name = "Foundation", kind = "framework")]
 extern "C" {}

objc2-foundation/src/macros.rs

@@ -1,15 +1,116 @@
+/// Create a new type to represent an Objective-C class.
+///
+/// The given name should correspond to a valid Objective-C class, whose
+/// instances have the encoding `Encoding::Object` (as an example:
+/// `NSAutoreleasePool` does not have this).
+///
+///
+/// # Specification
+///
+/// This creates an opaque struct, and implements traits for it to allow
+/// easier usage as an Objective-C object.
+///
+/// The traits [`objc2::RefEncode`] and [`objc2::Message`] are implemented to
+/// allow sending messages to the object and using it in [`objc2::rc::Id`].
+///
+/// [`Deref`] and [`DerefMut`] are implemented and delegate to the first
+/// superclass (direct parent). Auto traits are inherited from this superclass
+/// as well (this macro effectively just creates a newtype wrapper around the
+/// superclass).
+///
+/// Finally, [`AsRef`], [`AsMut`], [`Borrow`] and [`BorrowMut`] are
+/// implemented to allow conversion to an arbitary superclasses in the
+/// inheritance chain (since an instance of a class can always be interpreted
+/// as it's superclasses).
+///
+/// [`Deref`]: core::ops::Deref
+/// [`DerefMut`]: core::ops::DerefMut
+/// [`Borrow`]: core::borrow::Borrow
+/// [`BorrowMut`]: core::borrow::BorrowMut
+///
+///
+/// # Safety
+///
+/// The specified inheritance chain must be correct (including in the correct
+/// order), and the types in said chain must be valid as Objective-C objects -
+/// this is easiest to ensure by also creating those using this macro.
+///
+///
+/// # Example
+///
+/// Create a new type to represent the `NSFormatter` class.
+///
+/// ```
+/// use objc2::msg_send_id;
+/// use objc2::rc::{Id, Shared};
+/// use objc2_foundation::{object, NSObject};
+/// #
+/// # #[cfg(feature = "gnustep-1-7")]
+/// # unsafe { objc2::__gnustep_hack::get_class_to_force_linkage() };
+///
+/// object! {
+///     /// An example description.
+///     #[derive(PartialEq, Eq, Hash)] // Uses `NSObject`'s implementation
+///     // Specify class and superclass
+///     // In this case the class `NSFormatter`, which subclasses `NSObject`
+///     unsafe pub struct NSFormatter: NSObject;
+/// }
+///
+/// // Provided by the macro
+/// let cls = NSFormatter::class();
+///
+/// // `NSFormatter` implements `Message`:
+/// let obj: Id<NSFormatter, Shared> = unsafe { msg_send_id![cls, new].unwrap() };
+/// ```
+///
+/// Represent the `NSDateFormatter` class, using the `NSFormatter` type we
+/// declared previously to specify as its superclass.
+///
+/// ```
+/// use objc2_foundation::{object, NSObject};
+/// #
+/// # object! {
+/// #     #[derive(PartialEq, Eq, Hash)]
+/// #     unsafe pub struct NSFormatter: NSObject;
+/// # }
+///
+/// object! {
+///     #[derive(PartialEq, Eq, Hash)]
+///     // Specify the correct inheritance chain
+///     // `NSDateFormatter` subclasses `NSFormatter` which subclasses `NSObject`
+///     unsafe pub struct NSDateFormatter: NSFormatter, NSObject;
+/// }
+/// ```
+///
+/// See the source code of `objc2_foundation` in general for more examples.
+#[macro_export]
+macro_rules! object {
+    (
+        $(#[$m:meta])*
+        unsafe $v:vis struct $name:ident: $($inheritance_chain:ty),+;
+    ) => {
+        $crate::__inner_object! {
+            @__inner
+            $(#[$m])*
+            unsafe $v struct $name<>: $($inheritance_chain,)+ $crate::objc2::runtime::Object {}
+        }
+    };
+}
+
+#[doc(hidden)]
+#[macro_export]
 macro_rules! __impl_as_ref_borrow {
     ($name:ident<$($t:ident $(: $b:ident)?),*>,) => {};
     ($name:ident<$($t:ident $(: $b:ident)?),*>, $item:ty, $($tail:ty,)*) => {
-        impl<$($t $(: $b)?),*> AsRef<$item> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::convert::AsRef<$item> for $name<$($t),*> {
             #[inline]
             fn as_ref(&self) -> &$item {
                 // Triggers Deref coercion depending on return type
                 &*self
             }
         }
 
-        impl<$($t $(: $b)?),*> AsMut<$item> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::convert::AsMut<$item> for $name<$($t),*> {
             #[inline]
             fn as_mut(&mut self) -> &mut $item {
                 // Triggers DerefMut coercion depending on return type
@@ -23,55 +124,40 @@ macro_rules! __impl_as_ref_borrow {
         // In particular, `Eq`, `Ord` and `Hash` all give the same results
         // after borrow.
 
-        impl<$($t $(: $b)?),*> ::core::borrow::Borrow<$item> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::borrow::Borrow<$item> for $name<$($t),*> {
             #[inline]
             fn borrow(&self) -> &$item {
                 // Triggers Deref coercion depending on return type
                 &*self
             }
         }
 
-        impl<$($t $(: $b)?),*> ::core::borrow::BorrowMut<$item> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::borrow::BorrowMut<$item> for $name<$($t),*> {
             #[inline]
             fn borrow_mut(&mut self) -> &mut $item {
                 // Triggers Deref coercion depending on return type
                 &mut *self
             }
         }
 
-        __impl_as_ref_borrow!($name<$($t $(: $b)?),*>, $($tail,)*);
+        $crate::__impl_as_ref_borrow!($name<$($t $(: $b)?),*>, $($tail,)*);
     };
 }
 
-/// TODO
-///
-/// # Safety
-///
-/// The given name must be a valid Objective-C class that inherits NSObject
-/// and it's instances must have the raw encoding `Encoding::Object` (an
-/// example: `NSAutoreleasePool` does not have this). Finally the ownership
-/// must be correct for this class.
-macro_rules! object {
-    (
-        $(#[$m:meta])*
-        unsafe $v:vis struct $name:ident: $($inheritance_chain:ty),+ $(;)?
-    ) => {
-        object! {
-            @__inner
-            $(#[$m])*
-            unsafe $v struct $name<>: $($inheritance_chain,)+ ::objc2::runtime::Object {}
-        }
-    };
+#[doc(hidden)]
+#[macro_export]
+macro_rules! __inner_object {
+    // TODO: Expose this variant in the `object` macro.
     (
         $(#[$m:meta])*
         unsafe $v:vis struct $name:ident<$($t:ident $(: $b:ident)?),*>: $($inheritance_chain:ty),+ {
             $($p:ident: $pty:ty,)*
         }
     ) => {
-        object! {
+        $crate::__inner_object! {
             @__inner
             $(#[$m])*
-            unsafe $v struct $name<$($t $(: $b)?),*>: $($inheritance_chain,)+ ::objc2::runtime::Object {
+            unsafe $v struct $name<$($t $(: $b)?),*>: $($inheritance_chain,)+ $crate::objc2::runtime::Object {
                 $($p: $pty,)*
             }
         }
@@ -87,20 +173,21 @@ macro_rules! object {
         // TODO: repr(transparent) when the inner pointer is no longer a ZST.
         #[repr(C)]
         $v struct $name<$($t $(: $b)?),*> {
-            inner: $inherits,
+            __inner: $inherits,
             // Additional fields (should only be zero-sized PhantomData).
             $($p: $pty),*
         }
 
-        unsafe impl<$($t $(: $b)?),*> ::objc2::Message for $name<$($t),*> { }
+        unsafe impl<$($t $(: $b)?),*> $crate::objc2::Message for $name<$($t),*> { }
 
-        unsafe impl<$($t $(: $b)?),*> ::objc2::RefEncode for $name<$($t),*> {
-            const ENCODING_REF: ::objc2::Encoding<'static> = ::objc2::Encoding::Object;
+        unsafe impl<$($t $(: $b)?),*> $crate::objc2::RefEncode for $name<$($t),*> {
+            const ENCODING_REF: $crate::objc2::Encoding<'static>
+                = <$inherits as $crate::objc2::RefEncode>::ENCODING_REF;
         }
 
         impl<$($t $(: $b)?),*> $name<$($t),*> {
-            $v fn class() -> &'static ::objc2::runtime::Class {
-                ::objc2::class!($name)
+            $v fn class() -> &'static $crate::objc2::runtime::Class {
+                $crate::objc2::class!($name)
             }
         }
 
@@ -122,12 +209,12 @@ macro_rules! object {
         // Note that you can easily have two different variables pointing to
         // the same object, `x: &T` and `y: &T::Target`, and this would be
         // perfectly safe!
-        impl<$($t $(: $b)?),*> ::core::ops::Deref for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::ops::Deref for $name<$($t),*> {
             type Target = $inherits;
 
             #[inline]
             fn deref(&self) -> &Self::Target {
-                &self.inner
+                &self.__inner
             }
         }
 
@@ -142,28 +229,28 @@ macro_rules! object {
         // But `&mut NSMutableString` -> `&mut NSString` safe, since the
         // `NSCopying` implementation of `NSMutableString` is used, and that
         // is guaranteed to return a different object.
-        impl<$($t $(: $b)?),*> ::core::ops::DerefMut for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::ops::DerefMut for $name<$($t),*> {
             #[inline]
             fn deref_mut(&mut self) -> &mut Self::Target {
-                &mut self.inner
+                &mut self.__inner
             }
         }
 
-        impl<$($t $(: $b)?),*> AsRef<Self> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::convert::AsRef<Self> for $name<$($t),*> {
             #[inline]
             fn as_ref(&self) -> &Self {
                 self
             }
         }
 
-        impl<$($t $(: $b)?),*> AsMut<Self> for $name<$($t),*> {
+        impl<$($t $(: $b)?),*> $crate::__core::convert::AsMut<Self> for $name<$($t),*> {
             #[inline]
             fn as_mut(&mut self) -> &mut Self {
                 self
             }
         }
 
-        __impl_as_ref_borrow!($name<$($t $(: $b)?),*>, $inherits, $($inheritance_rest,)*);
+        $crate::__impl_as_ref_borrow!($name<$($t $(: $b)?),*>, $inherits, $($inheritance_rest,)*);
     };
 }
 
@@ -175,7 +262,7 @@ macro_rules! unsafe_def_fn {
         $(#[$m])*
         $v fn new() -> Id<Self, $o> {
             let cls = Self::class();
-            unsafe { ::objc2::msg_send_id![cls, new].unwrap() }
+            unsafe { $crate::objc2::msg_send_id![cls, new].unwrap() }
         }
     };
 }

objc2-foundation/src/object.rs

@@ -7,7 +7,7 @@ use objc2::{msg_send, msg_send_bool, msg_send_id};
 
 use super::NSString;
 
-object! {
+__inner_object! {
     @__inner
     unsafe pub struct NSObject<>: Object {}
 }

objc2-foundation/src/value.rs

@@ -14,7 +14,7 @@ use objc2::{msg_send, msg_send_id};
 
 use super::{NSCopying, NSObject};
 
-object! {
+__inner_object! {
     // `T: Eq` bound correct to prevent `NSValue<f32>` from being `Eq`
     // (even though `[NAN isEqual: NAN]` is true in Objective-C).
     #[derive(Debug, PartialEq, Eq, Hash)]