hooks_core/

macros.rs

/// This macro should only be used in [`hook_fn`](crate::hook_fn) or `#[hook]`.
#[macro_export]
macro_rules! h {
    [] => {
        ::core::compile_error! {"h! must be used in hook_fn!"}
    };
}

/// Write hook fn without any proc-macro.
///
/// A *hook fn* is a `fn` which returns [`impl UpdateHookUninitialized`](trait@crate::UpdateHookUninitialized).
/// (Thus the output type is also [`UpdateHook`](crate::UpdateHook) + [`IntoHook`](crate::IntoHook)).
///
/// Tips: `cargo fmt` supports formatting code inside `hook_fn!(...);` and `hook_fn![...];`, but not `hook_fn!{...}`.
///
/// ## Usage
///
/// ```
/// # use hooks_core::prelude::*;
/// hook_fn!(
///     fn use_constant() -> i32 {
///         1
///     }
/// );
///
/// # use hooks_core::{UpdateHookUninitialized, Hook, HookValue, HookPollNextUpdate, HookUnmount};
/// /// `use_constant()` actually returns:
/// # fn assert_0() ->
/// UpdateHookUninitialized![i32]
/// # { use_constant() }
/// /// The above macro expands to
/// # fn assert_1() ->
/// impl UpdateHookUninitialized<
///     Uninitialized = impl HookPollNextUpdate + HookUnmount + Default,
///     Hook = impl Hook + for<'hook> HookValue<'hook, Value = i32>
/// >
/// # { use_constant() }
/// ```
///
/// ## Use other hooks with [`h!(...)`](h)
///
/// Usually, you would want to use other hooks in hook_fn.
///
/// ```
/// # extern crate hooks_dev as hooks;
/// use hooks::prelude::*;
///
/// hook_fn!(
///     fn use_auto_increment(max: i32) -> i32 {
///         let state = h!(use_shared_signal(0));
///         let v = state.get();
///
///         h!(use_effect_with::<i32, _>(|old_dependency| {
///             if *old_dependency != Some(v) {
///                 *old_dependency = Some(v);
///                 let state = state.clone();
///                 Some(move |v: &_| state.set(*v + 1))
///             } else {
///                 None
///             }
///         }));
///
///         v
///     }
/// );
/// ```
///
/// ## Capture lifetimes
///
/// Lifetimes in `fn` generics and `type Bounds = impl 'a` are captured.
///
/// For example, in
///
/// ```
/// # use hooks_core::hook_fn;
/// hook_fn!(
///     fn use_hook<'a>(_: &'a str) {}
/// );
/// ```
///
/// the return type of `use_hook` auto captures
/// lifetime `'a` with trait bound [`Captures<&'a ()>`](crate::Captures)
/// (even the argument `&'a str` is not used in the fn body).
///
/// <details>
/// <summary>
///
/// If the lifetime is elided and used,
/// it must be specified with `type Bounds = impl '_;`.
///
/// </summary>
///
/// ```compile_fail
/// # use hooks_core::hook_fn;
/// hook_fn!(
///     fn use_hook(v: &str) {
///         println!("{}", v);
///     }
/// );
/// ```
///
/// ```
/// # use hooks_core::hook_fn;
/// hook_fn!(
///     type Bounds = impl '_;
///     fn use_hook(v: &str) {
///         println!("{}", v);
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// If the lifetime comes from outer `Self` and is used,
/// it must be specified with `type Bounds = impl 'a;`.
///
/// </summary>
///
/// ```compile_fail
/// # use hooks_core::hook_fn;
/// struct Data<'a>(&'a str);
///
/// impl<'a> Data<'a> {
///     hook_fn!(
///         fn use_data(self) {
///             println!("{}", self.0)
///         }
///    );
/// }
/// ```
///
/// ```
/// # use hooks_core::hook_fn;
/// struct Data<'a>(&'a str);
///
/// impl<'a> Data<'a> {
///     hook_fn!(
///         type Bounds = impl 'a;
///         fn use_data(self) {
///             println!("{}", self.0)
///         }
///    );
/// }
/// ```
///
/// </details>
///
/// <details>
/// <summary>
///
/// In Rust 2024 and later editions, all lifetimes should be auto captured
/// so you don't need to specify them explicitly.
///
/// </summary>
///
/// See [lifetime_capture_rules_2024](https://rust-lang.github.io/rfcs/3498-lifetime-capture-rules-2024.html)
///
/// </details>
///
/// ## Use an explicit identifier for hook
///
/// `h!(use_hook())` actually expands to [`use_hook().h(hook_id)`](crate::UpdateHookUninitialized::h),
/// where `hook_id` is of type [`Pin<&mut UpdateHookUninitialized::Uninitialized>`](crate::UpdateHookUninitialized::Uninitialized).
///
/// You can use an explicit `hook_id` for debugging.
///
/// ```
/// # extern crate hooks_dev as hooks;
/// # use hooks::prelude::*;
/// hook_fn!(
///     fn use_my_state() -> i32 {
///         println!("{state_hook:?}"); // inspect this hook before it is used
///
///         let mut the_state_hook = state_hook;
///         let state_hook = std::pin::Pin::as_mut(&mut the_state_hook);
///
///         let (state, updater) = h![state_hook = use_shared_set(1)];
///
///         let state = *state;
///
///         println!("{the_state_hook:?}"); // inspect this hook after it is used
///
///         state
///     }
/// );
/// ```
///
/// ## Limitations
///
/// <details><summary>
///
/// Only *top level token trees* are parsed.
///
/// </summary>
///
/// The following example doesn't work because
/// two macros are in a token tree `()`, which stops them to be parsed.
///
/// ```compile_fail
/// # extern crate hooks_dev as hooks;
/// # use hooks::prelude::*;
/// hook_fn!(
///     fn use_shared_signal_2() -> (i32, i32) {
///         (
///             h![use_shared_signal(0)].get(),
///             h![use_shared_signal(1)].get(),
///         )
///     }
/// );
/// ```
///
/// You have to make sure `h!` to be *top level token trees* when using `hook_fn!`.
///
/// ```
/// # extern crate hooks_dev as hooks;
/// # use hooks::prelude::*;
/// hook_fn!(
///     fn use_shared_signal_2() -> (i32, i32) {
///         let a = h![use_shared_signal(0)].get();
///         let b = h![use_shared_signal(1)].get();
///         (a, b)
///     }
/// );
/// ```
///
/// `#[hook]` parses any *top level expressions* (expressions that are not wrapped in `{}`).
/// Thus, the following example works.
///
/// ```
/// # extern crate hooks_dev as hooks;
/// # use hooks::prelude::*;
/// #[hook]
/// fn use_shared_signal_2() -> (i32, i32) {
///     (
///         use_shared_signal(0).get(),
///         use_shared_signal(1).get(),
///     )
/// }
/// ```
///
/// </details>
///
/// <details><summary>
///
/// Supports at most 10 hooks.
///
/// </summary>
///
/// ```
/// # use hooks_core::hook_fn;
/// # hook_fn!( fn use_hook(_: usize) {} );
/// hook_fn!(
///     fn use_10_hooks() {
///         h!(use_hook(0)); h!(use_hook(1)); h!(use_hook(2)); h!(use_hook(3)); h!(use_hook(4));
///         h!(use_hook(5)); h!(use_hook(6)); h!(use_hook(7)); h!(use_hook(8)); h!(use_hook(9));
///     }
/// );
/// ```
///
/// ```compile_fail
/// # use hooks_core::hook_fn;
/// # hook_fn!( fn use_hook(_: usize) {} );
/// hook_fn!(
///     fn use_11_hooks() {
///         h!(use_hook(0)); h!(use_hook(1)); h!(use_hook(2)); h!(use_hook(3)); h!(use_hook(4));
///         h!(use_hook(5)); h!(use_hook(6)); h!(use_hook(7)); h!(use_hook(8)); h!(use_hook(9));
///         h!(use_hook(10));
///     }
/// );
/// ```
///
/// This limitation also applies to `#[hook]` because
/// traits are only implemented for [`HookTuple<(0, 1, ...)>`](crate::HookTuple)
/// with at most 10 elements.
///
/// ```compile_fail
/// # extern crate hooks_dev as hooks;
/// # use hooks::hook;
/// # hooks_core::hook_fn!( fn use_hook(_: usize) {} );
/// #[hook]
/// fn use_11_hooks() {
///     use_hook(0); use_hook(1); use_hook(2); use_hook(3); use_hook(4);
///     use_hook(5); use_hook(6); use_hook(7); use_hook(8); use_hook(9);
///     use_hook(10);
/// }
/// ```
///
/// </details>
///
/// <details><summary>
///
/// Output type must not be opaque type (impl Trait)
///
/// </summary>
///
/// ```compile_fail
/// # use hooks_core::hook_fn;
/// # use std::future::Future;
/// hook_fn!(
///     fn use_future() -> impl Future<Output = ()> {
///         async {}
///     }
/// );
/// ```
///
/// `#[hook]` allows to do so.
///
/// ```
/// # extern crate hooks_dev as hooks;
/// # use hooks::hook;
/// # use std::future::Future;
/// #[hook]
/// fn use_future() -> impl Future<Output = ()> {
///     async {}
/// }
/// ```
///
/// </details>
#[macro_export]
macro_rules! hook_fn {
    (
        type Bounds = impl $hook_bound:lifetime $(+ $hook_bounds:lifetime)* ;
        $($rest:tt)*
    ) => {
        $crate::__impl_hook_fn_bounds_resolved! {
            { $hook_bound $(+ $hook_bounds)* }
            $($rest)*
        }
    };
    ($($rest:tt)*) => {
        $crate::__impl_hook_fn_bounds_resolved! {
            {}
            $($rest)*
        }
    };
}

/// ```
/// # extern crate hooks_dev as hooks;
/// # use hooks::prelude::*;
/// let closure = hooks_core::transform_hook_fn_body_as_closure! {
///     // options
///     []
///     // code
///     {
///         let (state, _updater) = h![use_shared_set(3)];
///         *state
///     }
/// };
///
/// let mut inner_hook = Default::default();
/// let value = closure(std::pin::Pin::new(&mut inner_hook));
/// assert_eq!(value, 3);
/// ```
#[macro_export]
macro_rules! transform_hook_fn_body_as_closure {
    ( $options:tt $code:tt ) => {
        $crate::__impl_fn_hook_body! {
            // state
            [
                $options
                [
                    __hooks_hook_0
                    __hooks_hook_1
                    __hooks_hook_2
                    __hooks_hook_3
                    __hooks_hook_4
                    __hooks_hook_5
                    __hooks_hook_6
                    __hooks_hook_7
                    __hooks_hook_8
                    __hooks_hook_9
                ]
            ]
            [] // used_ids
            [] // transformed_code
            $code
            $code
        }
    };
}

/// Easily impl traits.
///
/// For example:
///
/// ```
/// # use hooks_core::impl_hook;
/// struct OutputOnce<T>(pub Option<T>);
///
/// impl_hook!(
///     impl<T: Unpin> OutputOnce<T> {
///         /// HookUnmount is implemented with default `fn unmount()`
///         fn unmount() {}
///
///         /// HookPollNextUpdate is implemented
///         fn poll_next_update(self, _cx: _) {
///             std::task::Poll::Ready(self.get_mut().0.is_some())
///         }
///
///         /// HookValue and Hook is implemented
///         /// HookValue::Value is `&'hook mut Option<T>`
///         #[inline]
///         fn use_hook(self) -> &'hook mut Option<T> {
///             &mut self.get_mut().0
///         }
///     }
/// );
/// ```
///
/// ## Just write the methods of the traits you want to impl in one impl block
///
/// ```
/// # use hooks_core::impl_hook;
/// # struct MyType;
/// impl_hook!(
///     impl<__> MyType { // <__> helps rustfmt to format this macro.
///         // write methods here
/// #       fn poll_next_update(self) { false.into() }
///     }
/// );
/// # fn asserts() -> impl hooks_core::HookPollNextUpdate { MyType }
/// ```
///
/// Generics and where clause are supported.
///
/// ```
/// # use hooks_core::impl_hook;
/// # struct MyType<'a, T, F>(&'a T, F);
/// impl_hook!(
///     impl<'a, T: Clone + Default, F: FnMut(&T) -> T> MyType<'a, T, F>
///     where
///         T: Sized,
///     {
///         // write methods here
/// #       fn poll_next_update(self) { false.into() }
///     }
/// );
/// # fn asserts() -> impl hooks_core::HookPollNextUpdate { MyType(&1, Clone::clone) }
/// ```
///
/// ## Supported traits
///
/// <details>
/// <summary>
///
/// impl [`HookUnmount`] with [`unmount`](crate::HookUnmount::unmount)
///
/// </summary>
///
/// With default implementation:
///
/// ```
/// # use hooks_core::impl_hook; struct MyType;
/// impl_hook!(
///     impl<__> MyType {
///         fn unmount() {}
///     }
/// );
/// ```
///
/// With custom implementation:
///
/// ```
/// # use hooks_core::impl_hook; struct MyType;
/// # impl MyType { fn do_something(&self) {} }
/// impl_hook!(
///     impl<__> MyType {
///         fn unmount(self) {
///             self.do_something();
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// impl [`HookPollNextUpdate`] with [`poll_next_update`](crate::HookPollNextUpdate::poll_next_update)
///
/// </summary>
///
/// Argument `cx` is of type `&mut std::task::Context<'_>`.
/// The return type is `std::task::Poll<bool>`
///
/// ```
/// # use std::future::Future;
/// # use hooks_core::impl_hook;
/// # pin_project_lite::pin_project!( struct MyType {
/// #     #[pin]
/// #     inner: std::future::Ready<bool>,
/// # });
/// impl_hook!(
///     impl<__> MyType {
///         fn poll_next_update(self, cx: _) {
/// #           let cx: &mut std::task::Context<'_> = cx;
///             self.project().inner.poll(cx)
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// impl [`HookValue`] and [`Hook`] with [`use_hook`](crate::Hook::use_hook)
///
/// </summary>
///
/// Note that [`Hook`] requires [`HookUnmount`] + [`HookPollNextUpdate`]
///
/// ```
/// # use hooks_core::impl_hook;
/// # #[derive(Clone, Copy)] struct MyValueType; struct MyType(MyValueType);
/// impl_hook!(
///     impl<__> MyType {
///         fn unmount() {}
///         fn poll_next_update(self, cx: _) { todo!() }
///         fn use_hook(self) -> MyValueType {
///             self.0
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// impl [`IntoHook`] with [`into_hook`](crate::IntoHook::into_hook)
///
/// </summary>
///
/// ```
/// # use hooks_core::impl_hook; struct UseMyHook(i32); struct MyHook(i32);
/// # impl_hook!( impl MyHook { fn unmount() {} fn poll_next_update(self, cx: _) { todo!() } fn use_hook(self) {} });
/// impl_hook!(
///     impl<__> UseMyHook {
///         fn into_hook(self) -> MyHook {
///             MyHook(self.0)
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// impl [`UpdateHook`] with [`update_hook`](crate::UpdateHook::update_hook)
///
/// </summary>
///
/// Note that [`UpdateHook`] requires [`IntoHook`].
///
/// ```
/// # use hooks_core::impl_hook; struct UseMyHook(i32); struct MyHook(i32);
/// # impl_hook!( impl MyHook { fn unmount() {} fn poll_next_update(self, cx: _) { todo!() } fn use_hook(self) {} });
/// impl_hook!(
///     impl<__> UseMyHook {
///         fn into_hook(self) -> MyHook {
///             MyHook(self.0)
///         }
///         fn update_hook(self, mut hook: _) {
///             hook.0 = self.0
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// <details><summary>
///
/// impl [`UpdateHookUninitialized`] with [`h`](crate::UpdateHookUninitialized::h)
///
/// </summary>
///
/// Note that [`UpdateHookUninitialized`] requires [`UpdateHook`] + [`IntoHook`].
///
/// ```
/// # use hooks_core::impl_hook; struct UseMyHook(i32); struct MyHook(i32);
/// # #[derive(Default)] struct MyHookUninitialized(Option<i32>);
/// # impl_hook!( impl MyHook { fn unmount() {} fn poll_next_update(self, cx: _) { todo!() } fn use_hook(self) {} });
/// # impl_hook!( impl MyHookUninitialized { fn unmount() {} fn poll_next_update(self, cx: _) { todo!() } });
/// impl_hook!(
///     impl<__> UseMyHook {
///         fn into_hook(self) -> MyHook {
///             MyHook(self.0)
///         }
///         fn update_hook(self, mut hook: _) {
///             hook.0 = self.0
///         }
///         fn h(self, mut hook: MyHookUninitialized) {
///             hook.0.get_or_insert(self.0);
///         }
///     }
/// );
/// ```
///
/// </details>
///
/// [`HookUnmount`]: crate::HookUnmount
/// [`HookPollNextUpdate`]: crate::HookPollNextUpdate
/// [`HookValue`]: crate::HookValue
/// [`Hook`]: trait@crate::Hook
/// [`IntoHook`]: crate::IntoHook
/// [`UpdateHook`]: crate::UpdateHook
/// [`UpdateHookUninitialized`]: trait@crate::UpdateHookUninitialized
#[macro_export]
macro_rules! impl_hook {
    (
        // this empty generic helps with rustfmt
        impl <$(__)?> $($rest:tt)*
    ) => {
        $crate::__impl_impl_hook_generics_consumed! {
            before_gt {}
            gt_and_rest {> $($rest)*}
        }
    };
    (
        impl < $($generics_and_rest:tt)*
    ) => {
        $crate::__private::consume_till_outer_gt! {
            on_finish { $crate::__impl_impl_hook_generics_consumed! }
            input { $($generics_and_rest)* }
        }
    };
    (
        impl $($rest:tt)*
    ) => {
        $crate::__impl_impl_hook_generics_consumed! {
            before_gt {}
            gt_and_rest {> $($rest)*}
        }
    };
}

/// Expands to an opaque type [`impl Hook`](trait@crate::Hook)
/// with type of [`Value`](crate::HookValue::Value).
#[macro_export]
macro_rules! Hook {
    ($value:ty $(, $($bounds:tt)*)? ) => {
        $crate::__impl_capture_lifetimes![
            [
                impl $crate::Hook + for<'hook> $crate::HookValue<'hook, Value = $value>
            ]
            { $($($bounds)*)? }
        ]
    };
}

/// Expands to an opaque type [`impl UpdateHookUninitialized`](trait@crate::UpdateHookUninitialized)
/// with type of [`Hook`](crate::IntoHook::Hook)`::`[`Value`](crate::HookValue::Value).
#[macro_export]
macro_rules! UpdateHookUninitialized {
    ($value:ty $(, $($bounds:tt)*)?) => {
        impl $crate::UpdateHookUninitialized<
            Uninitialized = $crate::__impl_capture_lifetimes![
                [
                    impl $crate::HookPollNextUpdate
                        + $crate::HookUnmount
                        + ::core::default::Default
                ]
                { $($($bounds)*)? }
            ],
            Hook = $crate::Hook![$value $(, $($bounds)*)?]
        >
    };
    // Implementation details
    (@ extract_lifetimes_from_generics {
        value! { $value:ty }
        $(generics_info! {
            $({
                $(lifetime_attrs $lifetime_attrs:tt)?
                lifetime {$lt:lifetime}
                $($rest:tt)*
            })*
            $({
                $(const_attrs $const_attrs:tt)?
                $(type_attrs $type_attrs:tt)?
                $(const $const:tt)?
                name $name:tt
                $($rest2:tt)*
            })*
        })?
        // explicitly specified lifetime bounds
        bounds! { $($bounds:tt)* }
    }) => {
        $crate::UpdateHookUninitialized![
            $value,
            $(
                $( $lt + )*
            )?
            $($bounds)*
        ]
    };
}