rune/module/
module_raw_function_builder.rs

Help
1use ::rust_alloc::sync::Arc;
2
3use crate::compile::ContextError;
4use crate::function_meta::{
5    Associated, AssociatedFunctionData, FunctionData, FunctionMetaKind, ToInstance,
6};
7use crate::item::IntoComponent;
8use crate::module::ItemFnMut;
9use crate::runtime::{FunctionHandler, TypeInfo, TypeOf};
10use crate::{Hash, ItemBuf};
11
12use super::Module;
13
14/// Raw function builder as returned by [`Module::raw_function`].
15///
16/// This allows for building a function regularly with
17/// [`ModuleRawFunctionBuilder::build`] or statically associate the function
18/// with a type through [`ModuleRawFunctionBuilder::build_associated::<T>`].
19#[must_use = "Must call one of the build functions, like `build` or `build_associated`"]
20pub struct ModuleRawFunctionBuilder<'a, N> {
21    pub(super) module: &'a mut Module,
22    pub(super) name: N,
23    pub(super) handler: Arc<FunctionHandler>,
24}
25
26impl<'a, N> ModuleRawFunctionBuilder<'a, N> {
27    /// Construct a regular function.
28    ///
29    /// This register the function as a free function in the module it's
30    /// associated with, who's full name is the name of the module extended by
31    /// the name of the function.
32    ///
33    /// # Examples
34    ///
35    /// ```
36    /// use rune::{Any, Module};
37    /// use rune::runtime::VmResult;
38    ///
39    /// let mut m = Module::with_item(["module"])?;
40    /// m.raw_function("floob", |_, _, _, _| VmResult::Ok(())).build()?;
41    /// # Ok::<_, rune::support::Error>(())
42    /// ```
43    #[inline]
44    pub fn build(self) -> Result<ItemFnMut<'a>, ContextError>
45    where
46        N: IntoComponent,
47    {
48        let item = ItemBuf::with_item([self.name])?;
49        self.module
50            .function_from_meta_kind(FunctionMetaKind::Function(FunctionData::from_raw(
51                item,
52                self.handler,
53            )))
54    }
55
56    /// Construct a function that is associated with `T`.
57    ///
58    /// This registers the function as an assocaited function, which can only be
59    /// used through the type `T`.
60    ///
61    /// # Errors
62    ///
63    /// This function call will cause an error in [`Context::install`] if the
64    /// type we're associating it with has not been registered.
65    ///
66    /// [`Context::install`]: crate::Context::install
67    ///
68    /// ```
69    /// use rune::{Any, Module, Context};
70    ///
71    /// #[derive(Any)]
72    /// struct Thing;
73    ///
74    /// let mut m = Module::default();
75    /// m.function("floob", || ()).build_associated::<Thing>()?;
76    ///
77    /// let mut c = Context::default();
78    /// assert!(c.install(m).is_err());
79    /// # Ok::<_, rune::support::Error>(())
80    /// ```
81    ///
82    /// # Examples
83    ///
84    /// ```
85    /// use rune::{Any, Module};
86    /// use rune::runtime::VmResult;
87    ///
88    /// #[derive(Any)]
89    /// struct Thing;
90    ///
91    /// let mut m = Module::default();
92    /// m.ty::<Thing>()?;
93    /// m.raw_function("floob", |_, _, _, _| VmResult::Ok(())).build_associated::<Thing>()?;
94    /// # Ok::<_, rune::support::Error>(())
95    /// ```
96    #[inline]
97    pub fn build_associated<T>(self) -> Result<ItemFnMut<'a>, ContextError>
98    where
99        N: ToInstance,
100        T: TypeOf,
101    {
102        let associated = Associated::from_type::<T>(self.name.to_instance()?)?;
103
104        self.module
105            .function_from_meta_kind(FunctionMetaKind::AssociatedFunction(
106                AssociatedFunctionData::from_raw(associated, self.handler),
107            ))
108    }
109
110    /// Construct a function that is associated with a custom dynamically
111    /// specified container.
112    ///
113    /// This registers the function as an assocaited function, which can only be
114    /// used through the specified type.
115    ///
116    /// [`Hash`] and [`TypeInfo`] are usually constructed through the [`TypeOf`]
117    /// trait. But that requires access to a static type, for which you should
118    /// use [`build_associated`] instead.
119    ///
120    /// # Errors
121    ///
122    /// The function call will error if the specified type is not already
123    /// registered in the module.
124    ///
125    /// [`Hash`]: crate::Hash
126    /// [`build_associated`]: super::ModuleFunctionBuilder::build_associated
127    #[inline]
128    pub fn build_associated_with(
129        self,
130        container: Hash,
131        container_type_info: TypeInfo,
132    ) -> Result<ItemFnMut<'a>, ContextError>
133    where
134        N: ToInstance,
135    {
136        let associated = Associated::new(self.name.to_instance()?, container, container_type_info);
137        self.module
138            .function_from_meta_kind(FunctionMetaKind::AssociatedFunction(
139                AssociatedFunctionData::from_raw(associated, self.handler),
140            ))
141    }
142}
rune/module/module_raw_function_builder.rs

rune/module/
module_raw_function_builder.rs
