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]
9macro_rules! vm_try {
10 ($expr:expr) => {
11 match $crate::runtime::try_result($expr) {
12 $crate::runtime::VmResult::Ok(value) => value,
13 $crate::runtime::VmResult::Err(err) => {
14 return $crate::runtime::VmResult::Err(err);
15 }
16 }
17 };
18}
19
20/// Helper to cause a panic.
21///
22/// This simply returns a [`VmResult`], but the macro is provided to play nicely
23/// with [`rune::function`], since a regular return would otherwise be
24/// transformed.
25///
26/// [`rune::function`]: macro@crate::function
27/// [`VmResult`]: crate::runtime::VmResult
28///
29/// # Examples
30///
31/// ```
32/// use rune::vm_panic;
33///
34/// #[rune::function(vm_result)]
35/// fn hello(panic: bool) {
36/// if panic {
37/// vm_panic!("I was told to panic");
38/// }
39/// }
40/// ```
41#[macro_export]
42macro_rules! vm_panic {
43 ($expr:expr) => {{
44 return $crate::runtime::VmResult::panic($expr);
45 }};
46}
47
48/// Helper macro to perform a `write!` in a context which errors with
49/// [`VmResult`] and returns `VmResult<Result<_, E>>` on write errors.
50///
51/// [`VmResult`]: crate::runtime::VmResult
52#[macro_export]
53macro_rules! vm_write {
54 ($($tt:tt)*) => {
55 match core::write!($($tt)*) {
56 Ok(()) => $crate::runtime::VmResult::Ok(()),
57 Err(err) => $crate::runtime::VmResult::Err($crate::runtime::VmError::from(err)),
58 }
59 };
60}
61
62/// Convenience macro for extracting a documentation string from documentation
63/// comments.
64///
65/// # Examples
66///
67/// ```
68/// let docs: [&'static str; 3] = rune::docstring! {
69/// /// Hi, this is some documentation.
70/// ///
71/// /// I hope you like it!
72/// };
73/// ```
74#[macro_export]
75macro_rules! docstring {
76 ($(#[doc = $doc:expr])*) => {
77 [$($doc),*]
78 };
79}