rune/
any.rs

Help
1use core::any;
2
3use crate::compile::Named;
4use crate::runtime::{AnyTypeInfo, TypeHash};
5
6/// Macro to mark a value as external, which will implement all the appropriate
7/// traits.
8///
9/// This is required to support the external type as a type argument in a
10/// registered function.
11///
12/// ## `#[rune(item = <path>)]`
13///
14/// Specify the item prefix which contains this time.
15///
16/// This is required in order to calculate the correct type hash, if this is
17/// omitted and the item is defined in a nested module the type hash won't match
18/// the expected path hash.
19///
20/// ```
21/// use rune::Any;
22///
23/// #[derive(Any)]
24/// #[rune(item = ::process)]
25/// struct Process {
26///     /* .. */
27/// }
28///
29/// fn install() -> Result<rune::Module, rune::ContextError> {
30///     let mut module = rune::Module::with_crate("process")?;
31///     module.ty::<Process>()?;
32///     Ok(module)
33/// }
34/// ```
35///
36/// ## `#[rune(name = <ident>)]` attribute
37///
38/// The name of a type defaults to its identifiers, so `struct Foo {}` would be
39/// given the name `Foo`.
40///
41/// This can be overrided with the `#[rune(name = <ident>)]` attribute:
42///
43/// ```
44/// use rune::Any;
45///
46/// #[derive(Any)]
47/// #[rune(name = Bar)]
48/// struct Foo {
49/// }
50///
51/// fn install() -> Result<rune::Module, rune::ContextError> {
52///     let mut module = rune::Module::new();
53///     module.ty::<Foo>()?;
54///     Ok(module)
55/// }
56/// ```
57pub use rune_macros::Any;
58
59/// Derive for types which can be used inside of Rune.
60///
61/// Rune only supports two types, *built-in* types [`String`] and *external*
62/// types which derive `Any`. Before they can be used they must be registered in
63/// [`Context::install`] through a [`Module`].
64///
65/// This is typically used in combination with declarative macros to register
66/// functions and macros, such as:
67///
68/// * [`#[rune::function]`]
69/// * [`#[rune::macro_]`]
70///
71/// [`AnyObj`]: crate::runtime::AnyObj
72/// [`Context::install`]: crate::Context::install
73/// [`Module`]: crate::Module
74/// [`String`]: std::string::String
75/// [`#[rune::function]`]: macro@crate::function
76/// [`#[rune::macro_]`]: crate::macro_
77///
78/// # Examples
79///
80/// ```
81/// use rune::Any;
82///
83/// #[derive(Any)]
84/// struct Npc {
85///     #[rune(get)]
86///     health: u32,
87/// }
88///
89/// impl Npc {
90///     /// Construct a new NPC.
91///     #[rune::function(path = Self::new)]
92///     fn new(health: u32) -> Self {
93///         Self {
94///             health
95///         }
96///     }
97///
98///     /// Damage the NPC with the given `amount`.
99///     #[rune::function]
100///     fn damage(&mut self, amount: u32) {
101///         self.health -= amount;
102///     }
103/// }
104///
105/// fn install() -> Result<rune::Module, rune::ContextError> {
106///     let mut module = rune::Module::new();
107///     module.ty::<Npc>()?;
108///     module.function_meta(Npc::new)?;
109///     module.function_meta(Npc::damage)?;
110///     Ok(module)
111/// }
112/// ```
113pub trait Any: TypeHash + Named + any::Any {
114    /// The compile-time type information know for the type.
115    const ANY_TYPE_INFO: AnyTypeInfo = AnyTypeInfo::new(Self::full_name, Self::HASH);
116}
117
118/// Trait implemented for types which can be automatically converted to a
119/// [`Value`].
120///
121/// We can't use a blanked implementation over `T: Any` because it only governs
122/// what can be stored in any [`AnyObj`].
123///
124/// This trait in contrast is selectively implemented for types which we want to
125/// generate [`ToValue`] and [`FromValue`] implementations for.
126///
127/// [`Value`]: crate::runtime::Value
128/// [`AnyObj`]: crate::runtime::AnyObj
129/// [`ToValue`]: crate::runtime::ToValue
130/// [`FromValue`]: crate::runtime::FromValue
131///
132/// Note that you are *not* supposed to implement this directly. Make use of the
133/// [`Any`] derive instead.
134///
135/// [`Any`]: derive@Any
136pub trait AnyMarker: Any {}
rune/any.rs

rune/
any.rs
