objc_rs/lib.rs
1/*!
2Objective-C Runtime bindings and wrapper for Rust.
3
4# Messaging objects
5
6Objective-C objects can be messaged using the [`msg_send!`](macro.msg_send!.html) macro:
7
8``` no_run
9# #[macro_use] extern crate objc;
10# use objc::runtime::{BOOL, Class, Object};
11# fn main() {
12# unsafe {
13let cls = class!(NSObject);
14let obj: *mut Object = msg_send![cls, new];
15let hash: usize = msg_send![obj, hash];
16let is_kind: BOOL = msg_send![obj, isKindOfClass:cls];
17// Even void methods must have their return type annotated
18let _: () = msg_send![obj, release];
19# }
20# }
21```
22
23# Reference counting
24
25Utilities for reference counting Objective-C objects are provided in the
26[`rc`](rc/index.html) module.
27
28# Declaring classes
29
30Objective-C classes can even be declared from Rust using the functionality of
31the [`declare`](declare/index.html) module.
32
33# Exceptions
34
35By default, if the `msg_send!` macro causes an exception to be thrown, this
36will unwind into Rust resulting in unsafe, undefined behavior.
37However, this crate has an `"exception"` feature which, when enabled, wraps
38each `msg_send!` in a `@try`/`@catch` and panics if an exception is caught,
39preventing Objective-C from unwinding into Rust.
40
41# Message type verification
42
43The Objective-C runtime includes encodings for each method that describe the
44argument and return types. This crate can take advantage of these encodings to
45verify that the types used in Rust match the types encoded for the method.
46
47To use this functionality, enable the `"verify_message"` feature.
48With this feature enabled, type checking is performed for every message send,
49which also requires that all arguments and return values for all messages
50implement `Encode`.
51
52If this requirement is burdensome or you'd rather
53just verify specific messages, you can call the
54[`Message::verify_message`](trait.Message.html#method.verify_message) method
55for specific selectors.
56
57# Support for other Operating Systems
58
59The bindings can be used on Linux or *BSD utilizing the
60[GNUstep Objective-C runtime](https://www.github.com/gnustep/libobjc2).
61*/
62
63#![crate_name = "objc_rs"]
64#![crate_type = "lib"]
65#![warn(missing_docs)]
66
67extern crate malloc_buf;
68#[cfg(feature = "exception")]
69extern crate objc_exception;
70
71pub use encode::{Encode, EncodeArguments, Encoding};
72pub use message::{Message, MessageArguments, MessageError};
73
74pub use message::send_message as __send_message;
75pub use message::send_super_message as __send_super_message;
76
77#[macro_use]
78mod macros;
79
80pub mod declare;
81mod encode;
82#[cfg(feature = "exception")]
83mod exception;
84mod message;
85pub mod rc;
86pub mod runtime;
87
88#[cfg(test)]
89mod test_utils;