Add function_reflection example

Author: MrGVSV

Cargo.toml

@@ -1996,6 +1996,17 @@ description = "Demonstrates how reflection in Bevy provides a way to dynamically
 category = "Reflection"
 wasm = false
 
+[[example]]
+name = "function_reflection"
+path = "examples/reflection/function_reflection.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.function_reflection]
+name = "Function Reflection"
+description = "Demonstrates how functions can be called dynamically using reflection"
+category = "Reflection"
+wasm = false
+
 [[example]]
 name = "generic_reflection"
 path = "examples/reflection/generic_reflection.rs"

crates/bevy_reflect/src/func/args/list.rs

@@ -59,6 +59,11 @@ impl<'a> ArgList<'a> {
         self.push(Arg::Owned(arg))
     }
 
+    /// Pop the last argument from the list, if there is one.
+    pub fn pop(&mut self) -> Option<Arg<'a>> {
+        self.0.pop()
+    }
+
     /// Returns the number of arguments in the list.
     pub fn len(&self) -> usize {
         self.0.len()

examples/README.md

@@ -315,6 +315,7 @@ Example | Description
 
 Example | Description
 --- | ---
+[Function Reflection](../examples/reflection/function_reflection.rs) | Demonstrates how functions can be called dynamically using reflection
 [Generic Reflection](../examples/reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection
 [Reflection](../examples/reflection/reflection.rs) | Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types
 [Reflection Types](../examples/reflection/reflection_types.rs) | Illustrates the various reflection types available

examples/reflection/function_reflection.rs

@@ -0,0 +1,156 @@
+//! This example demonstrates how functions can be called dynamically using reflection.
+
+use bevy::reflect::func::args::ArgInfo;
+use bevy::reflect::func::{ArgList, Function, FunctionInfo, IntoFunction, Return, ReturnInfo};
+use bevy::reflect::Reflect;
+
+// Note that the `dbg!` invocations are used purely for reference purposes
+// and are not strictly necessary for the example to work.
+fn main() {
+    // There are times when it may be helpful to store a function away for later.
+    // In Rust, we can do this by storing either a function pointer or a function trait object.
+    // For example, say we wanted to store the following function:
+    fn add(left: i32, right: i32) -> i32 {
+        left + right
+    }
+
+    // We could store it as either of the following:
+    let fn_pointer: fn(i32, i32) -> i32 = add;
+    let fn_trait_object: Box<dyn Fn(i32, i32) -> i32> = Box::new(add);
+
+    // And we can call them like so:
+    let result = fn_pointer(2, 2);
+    assert_eq!(result, 4);
+    let result = fn_trait_object(2, 2);
+    assert_eq!(result, 4);
+
+    // However, you'll notice that we have to know the types of the arguments and return value at compile time.
+    // This means there's not really a way to store or call these functions dynamically at runtime.
+    // Luckily, Bevy's reflection crate comes with a set of tools for doing just that!
+    // We do this by first converting our function into the reflection-based `Function` type
+    // using the `IntoFunction` trait.
+    let mut function: Function = dbg!(add.into_function());
+
+    // This time, you'll notice that `Function` doesn't take any information about the function's arguments or return value.
+    // This is because `Function` checks the types of the arguments and return value at runtime.
+    // Now we can generate a list of arguments:
+    let args: ArgList = dbg!(ArgList::new().push_owned(2_i32).push_owned(2_i32));
+
+    // And finally, we can call the function.
+    // This returns a `Result` indicating whether the function was called successfully.
+    // For now, we'll just unwrap it to get our `Return` value,
+    // which is an enum containing the function's return value.
+    let result: Return = dbg!(function.call(args).unwrap());
+
+    // The `Return` value can be pattern matched or unwrapped to get the underlying reflection data.
+    // For the sake of brevity, we'll just unwrap it here.
+    let result: Box<dyn Reflect> = result.unwrap_owned();
+    assert_eq!(result.take::<i32>().unwrap(), 4);
+
+    // The same can also be done for closures.
+    let mut count = 0;
+    let increment = |amount: i32| {
+        count += amount;
+    };
+    let increment_function: Function = dbg!(increment.into_function());
+    let args = dbg!(ArgList::new().push_owned(5_i32));
+    // Functions containing closures that capture their environment like this one
+    // may need to be dropped before those captured variables may be used again.
+    // This can be done manually with `drop` or by using the `Function::call_once` method.
+    dbg!(increment_function.call_once(args).unwrap());
+    assert_eq!(count, 5);
+
+    // All closures must be `'static`— that is, they take full ownership of any captured variables.
+    let add_closure = |left: i32, right: i32| -> i32 { left + right };
+    let mut count_function = dbg!(add_closure.into_function());
+    let args = dbg!(ArgList::new().push_owned(2_i32).push_owned(2_i32));
+    let result = dbg!(count_function.call(args).unwrap()).unwrap_owned();
+    assert_eq!(result.take::<i32>().unwrap(), 4);
+
+    // As stated before, this works for many kinds of simple functions.
+    // Functions with non-reflectable arguments or return values may not be able to be converted.
+    // Generic functions are also not supported.
+    // Additionally, the lifetime of the return value is tied to the lifetime of the first argument.
+    // However, this means that many methods are also supported:
+    #[derive(Reflect, Default)]
+    struct Data {
+        value: String,
+    }
+
+    impl Data {
+        fn set_value(&mut self, value: String) {
+            self.value = value;
+        }
+
+        // Note that only `&'static str` implements `Reflect`.
+        // To get around this limitation we can use `&String` instead.
+        fn get_value(&self) -> &String {
+            &self.value
+        }
+    }
+
+    let mut data = Data::default();
+
+    let mut set_value = dbg!(Data::set_value.into_function());
+    let args = dbg!(ArgList::new().push_mut(&mut data)).push_owned(String::from("Hello, world!"));
+    dbg!(set_value.call(args).unwrap());
+    assert_eq!(data.value, "Hello, world!");
+
+    let mut get_value = dbg!(Data::get_value.into_function());
+    let args = dbg!(ArgList::new().push_ref(&data));
+    let result = dbg!(get_value.call(args).unwrap());
+    let result: &dyn Reflect = result.unwrap_ref();
+    assert_eq!(result.downcast_ref::<String>().unwrap(), "Hello, world!");
+
+    // Lastly, for more complex use cases, you can always create a custom `Function` manually.
+    // This is useful for functions that can't be converted via the `IntoFunction` trait.
+    // For example, this function doesn't implement `IntoFunction` due to the fact that
+    // the lifetime of the return value is not tied to the lifetime of the first argument.
+    fn get_or_insert(value: i32, container: &mut Option<i32>) -> &i32 {
+        if container.is_none() {
+            *container = Some(value);
+        }
+
+        container.as_ref().unwrap()
+    }
+
+    let mut get_or_insert_function = dbg!(Function::new(
+        |mut args, info| {
+            let container_info = &info.args()[1];
+            let value_info = &info.args()[0];
+
+            // The `ArgList` contains the arguments in the order they were pushed.
+            // Therefore, we need to pop them in reverse order.
+            let container = args
+                .pop()
+                .unwrap()
+                .take_mut::<Option<i32>>(container_info)
+                .unwrap();
+            let value = args.pop().unwrap().take_owned::<i32>(value_info).unwrap();
+
+            Ok(Return::Ref(get_or_insert(value, container)))
+        },
+        FunctionInfo::new()
+            // We can optionally provide a name for the function
+            .with_name("get_or_insert")
+            // Since our function takes arguments, we MUST provide that argument information.
+            // The arguments should be provided in the order they are defined in the function.
+            // This is used to validate any arguments given at runtime.
+            .with_args(vec![
+                ArgInfo::new::<i32>(0).with_name("value"),
+                ArgInfo::new::<&mut Option<i32>>(1).with_name("container"),
+            ])
+            // We can optionally provide return information as well.
+            .with_return_info(ReturnInfo::new::<&i32>()),
+    ));
+
+    let mut container: Option<i32> = None;
+
+    let args = dbg!(ArgList::new().push_owned(5_i32).push_mut(&mut container));
+    let result = dbg!(get_or_insert_function.call(args).unwrap()).unwrap_ref();
+    assert_eq!(result.downcast_ref::<i32>(), Some(&5));
+
+    let args = dbg!(ArgList::new().push_owned(500_i32).push_mut(&mut container));
+    let result = dbg!(get_or_insert_function.call(args).unwrap()).unwrap_ref();
+    assert_eq!(result.downcast_ref::<i32>(), Some(&5));
+}