luau 0.732.0

Safe lifetime-bound Rust embedding API for the Luau runtime
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

use bstr::{BStr, ByteSlice};
use luau_vm::debug::LuaDebug;
use luau_vm::thread::StackGuard;

use super::{Lua, LuaRef};
use crate::{Error, LuaString};

/// Borrowed information about one active Luau call frame.
#[derive(Debug)]
pub struct StackInfo<'frame> {
    source: &'frame BStr,
    short_source: &'frame BStr,
    name: Option<&'frame BStr>,
    what: &'frame BStr,
    current_line: Option<usize>,
    line_defined: Option<usize>,
    parameter_count: u8,
    upvalue_count: u8,
    is_vararg: bool,
}

impl Lua {
    /// Inspects the active stack frame at `level`.
    ///
    /// Level zero is the currently executing Luau function and higher levels
    /// walk its callers. The borrowed [`StackInfo`] is valid only during
    /// `inspect`.
    pub fn inspect_stack<R>(
        &self,
        level: usize,
        inspect: impl FnOnce(&StackInfo<'_>) -> R,
    ) -> Result<Option<R>, Error> {
        self.lua_ref().inspect_stack(level, inspect)
    }

    /// Creates a traceback for the current Luau thread.
    pub fn traceback(&self, message: Option<&str>, level: usize) -> Result<LuaString<'_>, Error> {
        self.lua_ref().traceback(message, level)
    }
}

impl<'lua> LuaRef<'lua> {
    /// Inspects the active stack frame at `level`.
    ///
    /// Level zero is the currently executing Luau function and higher levels
    /// walk its callers. The borrowed [`StackInfo`] is valid only during
    /// `inspect`.
    pub fn inspect_stack<R>(
        &self,
        level: usize,
        inspect: impl FnOnce(&StackInfo<'_>) -> R,
    ) -> Result<Option<R>, Error> {
        let level =
            i32::try_from(level).map_err(|_| Error::runtime("stack level is out of range"))?;
        unsafe {
            let thread = self.as_vm();
            let _stack = StackGuard::new(thread);
            let mut debug = LuaDebug::default();
            if thread
                .get_info(level, "slnua", &mut debug)
                .map_err(|exit| Error::from_thread_exit(thread, exit))?
                == 0
            {
                return Ok(None);
            }
            let info = StackInfo::from_debug(&debug);
            Ok(Some(inspect(&info)))
        }
    }

    /// Creates a traceback for the current Luau thread.
    pub fn traceback(&self, message: Option<&str>, level: usize) -> Result<LuaString<'lua>, Error> {
        let level =
            i32::try_from(level).map_err(|_| Error::runtime("stack level is out of range"))?;
        unsafe {
            let thread = self.as_vm();
            let _stack = StackGuard::new(thread);
            thread
                .traceback(
                    Some(thread),
                    message.map(|value| value.as_bytes().as_bstr()),
                    level,
                )
                .map_err(|exit| Error::from_thread_exit(thread, exit))?;
            LuaString::from_stack(&self.current_thread(), -1)
                .map_err(|exit| Error::from_thread_exit(thread, exit))
        }
    }
}

impl<'frame> StackInfo<'frame> {
    fn from_debug(debug: &'frame LuaDebug) -> Self {
        Self {
            source: debug.source.as_bytes().as_bstr(),
            short_source: debug.short_src().as_bstr(),
            name: debug.name.as_ref().map(|name| name.as_bytes().as_bstr()),
            what: debug.what.as_bytes().as_bstr(),
            current_line: usize::try_from(debug.currentline).ok(),
            line_defined: usize::try_from(debug.linedefined).ok(),
            parameter_count: debug.nparams,
            upvalue_count: debug.nupvals,
            is_vararg: debug.is_vararg,
        }
    }

    /// Returns the function's source name.
    pub fn source(&self) -> &BStr {
        self.source
    }

    /// Returns a shortened form of the source name.
    pub fn short_source(&self) -> &BStr {
        self.short_source
    }

    /// Returns the function name when one is known.
    pub fn name(&self) -> Option<&BStr> {
        self.name
    }

    /// Returns the kind of function represented by this frame.
    pub fn what(&self) -> &BStr {
        self.what
    }

    /// Returns the current source line.
    pub const fn current_line(&self) -> Option<usize> {
        self.current_line
    }

    /// Returns the line where the function was defined.
    pub const fn line_defined(&self) -> Option<usize> {
        self.line_defined
    }

    /// Returns the number of fixed parameters.
    pub const fn parameter_count(&self) -> u8 {
        self.parameter_count
    }

    /// Returns the number of upvalues.
    pub const fn upvalue_count(&self) -> u8 {
        self.upvalue_count
    }

    /// Returns whether the function accepts variadic arguments.
    pub const fn is_vararg(&self) -> bool {
        self.is_vararg
    }
}