rune/
exported_macros.rs

1/// Helper to perform the try operation over [`VmResult`].
2///
3/// This can be used through [`rune::function`] by enabling the `vm_result`
4/// option and suffixing an expression with `<expr>.vm?`.
5///
6/// [`rune::function`]: macro@crate::function
7/// [`VmResult`]: crate::runtime::VmResult
8#[macro_export]
9#[doc(hidden)]
10#[deprecated = "Use `?` on `VmResult` instead of this macro."]
11macro_rules! __vm_try {
12    ($expr:expr) => {
13        match $expr {
14            Ok(value) => value,
15            Err(err) => {
16                return Err($crate::VmError::from(err));
17            }
18        }
19    };
20}
21
22/// Helper to perform the try operation over an inner value of a
23/// `Result<Result<T, E>, U>`, this will check an error of type `Result<T, E>`
24/// and return it as `Ok(Err(E))` if it is.
25///
26/// This is useful because functions in Rune can return different kinds of
27/// errors. One is a critical error for the virtual machine, most typically
28/// `VmErro`. And another is a logical error that should be returned and handled
29/// by the program.
30#[macro_export]
31#[doc(hidden)]
32macro_rules! __nested_try {
33    ($expr:expr) => {
34        match $expr {
35            Ok(value) => value,
36            Err(err) => {
37                return Ok(Err(
38                    #[allow(clippy::useless_conversion)]
39                    ::core::convert::From::from(err),
40                ));
41            }
42        }
43    };
44}
45
46/// Helper to cause a panic.
47///
48/// This simply returns a [`VmResult`], but the macro is provided to play nicely
49/// with [`rune::function`], since a regular return would otherwise be
50/// transformed.
51///
52/// [`rune::function`]: macro@crate::function
53/// [`VmResult`]: crate::runtime::VmResult
54///
55/// # Examples
56///
57/// ```
58/// use rune::vm_panic;
59///
60/// #[rune::function(vm_result)]
61/// fn hello(panic: bool) {
62///     if panic {
63///        vm_panic!("I was told to panic");
64///     }
65/// }
66/// ```
67#[macro_export]
68#[doc(hidden)]
69macro_rules! __vm_panic {
70    ($expr:expr) => {{
71        return Err($crate::runtime::VmError::panic($expr));
72    }};
73}
74
75/// Helper macro to perform a `write!` in a context which errors with
76/// [`VmResult`] and returns `VmResult<Result<_, E>>` on write errors.
77///
78/// [`VmResult`]: crate::runtime::VmResult
79#[macro_export]
80#[doc(hidden)]
81#[deprecated = "Convert any relevant errors to `VmError` instead of using this macro using for example `write!(..)?`."]
82macro_rules! __vm_write {
83    ($($tt:tt)*) => {
84        match core::write!($($tt)*) {
85            Ok(()) => Ok(()),
86            Err(err) => Err($crate::runtime::VmError::from(err)),
87        }
88    };
89}
90
91/// Convenience macro for extracting a documentation string from documentation
92/// comments.
93///
94/// # Examples
95///
96/// ```
97/// let docs: [&'static str; 3] = rune::docstring! {
98///     /// Hi, this is some documentation.
99///     ///
100///     /// I hope you like it!
101/// };
102/// ```
103#[macro_export]
104#[doc(hidden)]
105macro_rules! __docstring {
106    ($(#[doc = $doc:expr])*) => {
107        [$($doc),*]
108    };
109}
110
111#[doc(inline)]
112pub use __docstring as docstring;
113#[doc(inline)]
114pub use __nested_try as nested_try;
115#[doc(inline)]
116pub use __vm_panic as vm_panic;
117#[doc(inline)]
118#[allow(deprecated)]
119pub use __vm_try as vm_try;
120#[doc(inline)]
121#[allow(deprecated)]
122pub use __vm_write as vm_write;
rune/exported_macros.rs

rune/
exported_macros.rs
