rune 0.14.2

The Rune Language, an embeddable dynamic programming language for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

use crate::compile::ContextError;
use crate::function_meta::{Associated, ToInstance};
use crate::item::IntoComponent;
use crate::module::ItemMut;
use crate::runtime::{ToConstValue, TypeHash, TypeOf};

use super::Module;

/// Raw function builder as returned by [`Module::raw_function`].
///
/// This allows for building a function regularly with
/// [`ModuleConstantBuilder::build`] or statically associate the function with a
/// type through [`ModuleConstantBuilder::build_associated::<T>`].
#[must_use = "Must call one of the build functions, like `build` or `build_associated`"]
pub struct ModuleConstantBuilder<'a, N, V> {
    pub(super) module: &'a mut Module,
    pub(super) name: N,
    pub(super) value: V,
}

impl<'a, N, V> ModuleConstantBuilder<'a, N, V>
where
    V: TypeHash + TypeOf + ToConstValue,
{
    /// Add the free constant directly to the module.
    ///
    /// # Examples
    ///
    /// ```
    /// use rune::{Any, Module};
    /// use rune::runtime::VmResult;
    ///
    /// let mut m = Module::with_item(["module"])?;
    /// m.constant("NAME", "Hello World").build()?;
    /// # Ok::<_, rune::support::Error>(())
    /// ```
    pub fn build(self) -> Result<ItemMut<'a>, ContextError>
    where
        N: IntoComponent,
    {
        self.module.insert_constant(self.name, self.value)
    }

    /// Build a constant that is associated with the static type `T`.
    ///
    /// # Errors
    ///
    /// This function call will cause an error in [`Context::install`] if the
    /// type we're associating it with has not been registered.
    ///
    /// [`Context::install`]: crate::Context::install
    ///
    /// ```
    /// use rune::{Any, Context, Module};
    ///
    /// #[derive(Any)]
    /// struct Thing;
    ///
    /// let mut m = Module::default();
    /// m.constant("CONSTANT", "Hello World").build_associated::<Thing>()?;
    ///
    /// let mut c = Context::default();
    /// assert!(c.install(m).is_err());
    /// # Ok::<_, rune::support::Error>(())
    /// ```
    ///
    /// # Examples
    ///
    /// ```
    /// use rune::{docstring, Any, Module};
    ///
    /// let mut module = Module::default();
    ///
    /// #[derive(Any)]
    /// struct Thing;
    ///
    /// module.constant("TEN", 10)
    ///     .build_associated::<Thing>()?
    ///     .docs(docstring! {
    ///         /// Ten which is an associated constant.
    ///     });
    /// # Ok::<_, rune::support::Error>(())
    /// ```
    pub fn build_associated<T>(self) -> Result<ItemMut<'a>, ContextError>
    where
        T: TypeOf,
        N: ToInstance,
    {
        let name = self.name.to_instance()?;
        let associated = Associated::from_type::<T>(name)?;
        self.module
            .insert_associated_constant(associated, self.value)
    }
}