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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

//! Core types and methods in Rune.

use crate as rune;
use crate::alloc::prelude::*;
use crate::compile;
use crate::macros::{quote, FormatArgs, MacroContext, TokenStream};
use crate::parse::Parser;
use crate::runtime::{Panic, Value, VmResult};
use crate::{ContextError, Module};

#[rune::module(::std)]
/// Core types and methods in Rune.
///
/// These are types and methods for which Rune as a language would not work without.
pub fn module() -> Result<Module, ContextError> {
    let mut module = Module::from_meta(self::module_meta)?.with_unique("std");

    module.ty::<bool>()?.docs(docstring! {
        /// The primitive boolean type.
    })?;
    module.ty::<char>()?.docs(docstring! {
        /// The primitive character type.
    })?;
    module.ty::<u64>()?.docs(docstring! {
        /// The unsigned integer type.
    })?;
    module.ty::<i64>()?.docs(docstring! {
        /// The signed integer type.
    })?;
    module.ty::<f64>()?.docs(docstring! {
        /// The primitive float type.
    })?;

    module.function_meta(panic)?;
    module.function_meta(is_readable)?;
    module.function_meta(is_writable)?;

    module.macro_meta(stringify_macro)?;
    module.macro_meta(panic_macro)?;
    Ok(module)
}

/// Cause a vm panic with the given `message`.
///
/// A panic in Rune causes the current execution to unwind and terminate. The
/// panic will not be propagated into Rust, but will instead be signatted
/// through a `VmError`.
///
/// If you want to format a message, consider using the [panic!] macro.
#[rune::function]
fn panic(message: &str) -> VmResult<()> {
    VmResult::err(Panic::custom(vm_try!(message.try_to_owned())))
}

/// Test if the given `value` is readable.
///
/// A value is readable if can be acquired for shared access, such as producing
/// an immutable reference.
///
/// A value that is moved is no longer considered readable.
///
/// # Examples
///
/// ```rune
/// let value = Some(42);
/// assert!(is_readable(value));
/// let value2 = value.map(|v| v + 1);
/// drop(value);
/// assert!(!is_readable(value));
/// assert_eq!(value2, Some(43));
/// ```
#[rune::function]
fn is_readable(value: Value) -> bool {
    value.is_readable()
}

/// Test if the given `value` is writable.
///
/// A value is writable if can be acquired for exclusive access, such as
/// producing a mutable reference or taking ownership.
///
/// # Examples
///
/// ```rune
/// let value = Some(42);
/// assert!(is_writable(value));
/// let value2 = value.map(|v| v + 1);
/// drop(value);
/// assert!(!is_writable(value));
/// assert_eq!(value2, Some(43));
/// ```
#[rune::function]
fn is_writable(value: Value) -> bool {
    value.is_writable()
}

/// Stringify the given argument, causing it to expand to its underlying token
/// stream.
///
/// This can be used by macros to convert a stream of tokens into a readable
/// string.
#[rune::macro_(path = stringify)]
pub(crate) fn stringify_macro(
    cx: &mut MacroContext<'_, '_, '_>,
    stream: &TokenStream,
) -> compile::Result<TokenStream> {
    let lit = cx.stringify(stream)?.try_to_string()?;
    let lit = cx.lit(lit)?;
    Ok(quote!(#lit).into_token_stream(cx)?)
}

/// Cause a vm panic with a formatted message.
///
/// A panic in Rune causes the current execution to unwind and terminate. The
/// panic will not be propagated into Rust, but will instead be signatted
/// through a `VmError`.
#[rune::macro_(path = panic)]
pub(crate) fn panic_macro(
    cx: &mut MacroContext<'_, '_, '_>,
    stream: &TokenStream,
) -> compile::Result<TokenStream> {
    let mut p = Parser::from_token_stream(stream, cx.input_span());
    let args = p.parse_all::<FormatArgs>()?;
    let expanded = args.expand(cx)?;
    Ok(quote!(::std::panic(#expanded)).into_token_stream(cx)?)
}