luars 0.22.0

A library for lua 5.5 runtime implementation in 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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

use std::ffi::c_void;

mod chunk;
mod function;
mod lua;
mod lua_state;
mod lua_string;
mod scope;
mod table;
mod test;
mod util;
mod value;

pub use chunk::Chunk;
pub use function::Function;
pub use lua::Lua;
pub use lua_string::LuaString;
pub use scope::{Scope, ScopedFunction, ScopedUserData};
pub use table::Table;
pub use value::Value;

#[cfg(feature = "sandbox")]
use crate::SandboxConfig;
use crate::{
    FromLua, FromLuaMulti, IntoLua, LuaEnum, LuaError, LuaFullError, LuaRegistrable, LuaResult,
    LuaValueKind, Stdlib, UserDataRef, UserDataTrait,
    lua_vm::{LuaTypedAsyncCallback, LuaTypedCallback},
};

/// High-level, embedding-oriented API shared by safe host-side Lua handles.
///
/// This trait intentionally covers the typed, ergonomic surface. Low-level raw
/// runtime escape hatches such as `global_state` stay on the concrete type.
pub trait LuaApi {
    fn open_stdlib(&mut self, lib: Stdlib) -> LuaResult<()>;
    fn load_stdlibs(&mut self, lib: Stdlib) -> LuaResult<()>;
    fn collect_garbage(&mut self) -> LuaResult<()>;
    fn execute(&mut self, source: &str) -> LuaResult<()>;
    fn eval<R: FromLua>(&mut self, source: &str) -> LuaResult<R>;
    fn eval_multi<R: FromLuaMulti>(&mut self, source: &str) -> LuaResult<R>;
    fn set_global<T: IntoLua>(&mut self, name: &str, value: T) -> LuaResult<()>;
    fn globals(&mut self) -> Table;
    fn get_global<T: FromLua>(&mut self, name: &str) -> LuaResult<Option<T>>;
    fn call_global<A: IntoLua, R: FromLuaMulti>(&mut self, name: &str, args: A) -> LuaResult<R>;
    fn call_global1<A: IntoLua, R: FromLua>(&mut self, name: &str, args: A) -> LuaResult<R>;
    fn register_function<F, Args, R>(&mut self, name: &str, f: F) -> LuaResult<()>
    where
        F: LuaTypedCallback<Args, R>;
    fn create_function<F, Args, R>(&mut self, f: F) -> LuaResult<Function>
    where
        F: LuaTypedCallback<Args, R>;
    fn register_async_function<F, Args, R>(&mut self, name: &str, f: F) -> LuaResult<()>
    where
        F: LuaTypedAsyncCallback<Args, R>;
    fn register_type_of<T: LuaRegistrable>(&mut self, name: &str) -> LuaResult<()>;
    fn register_type<T: LuaRegistrable>(&mut self, name: &str) -> LuaResult<Table>;
    fn register_enum_of<T: LuaEnum>(&mut self, name: &str) -> LuaResult<()>;
    fn load<'lua>(&'lua mut self, source: &str) -> Chunk<'lua, Self>
    where
        Self: Sized + chunk::ChunkHost;
    fn load_function(&mut self, source: &str) -> LuaResult<Function>;
    fn create_string(&mut self, value: &str) -> LuaResult<LuaString>;
    fn create_table(&mut self) -> LuaResult<Table>;
    fn create_table_with_capacity(&mut self, narr: usize, nrec: usize) -> LuaResult<Table>;
    fn create_userdata<T: UserDataTrait + 'static>(&mut self, data: T)
    -> LuaResult<UserDataRef<T>>;
    /// # Safety
    /// The caller must ensure that the provided reference is valid for the lifetime of the Lua value
    unsafe fn create_userdata_ref<T: UserDataTrait + 'static>(
        &mut self,
        reference: &mut T,
    ) -> LuaResult<UserDataRef<T>>;
    fn create_table_from<K, V, I>(&mut self, iter: I) -> LuaResult<Table>
    where
        K: IntoLua,
        V: IntoLua,
        I: IntoIterator<Item = (K, V)>;
    fn create_sequence_from<T, I>(&mut self, iter: I) -> LuaResult<Table>
    where
        T: IntoLua,
        I: IntoIterator<Item = T>;
    fn get_function(&mut self, name: &str) -> LuaResult<Option<Function>>;
    fn get_table(&mut self, name: &str) -> LuaResult<Option<Table>>;
    fn set_global_table(&mut self, name: &str, table: &Table) -> LuaResult<()>;
    fn set_global_function(&mut self, name: &str, function: &Function) -> LuaResult<()>;
    fn table_set<T: IntoLua>(&mut self, table: &Table, key: &str, value: T) -> LuaResult<()>;
    fn table_seti<T: IntoLua>(&mut self, table: &Table, key: i64, value: T) -> LuaResult<()>;
    fn table_get<T: FromLua>(&mut self, table: &Table, key: &str) -> LuaResult<T>;
    fn table_geti<T: FromLua>(&mut self, table: &Table, key: i64) -> LuaResult<T>;
    fn table_push<T: IntoLua>(&mut self, table: &Table, value: T) -> LuaResult<()>;
    fn table_pairs<K: FromLua, V: FromLua>(&mut self, table: &Table) -> LuaResult<Vec<(K, V)>>;
    fn table_array<T: FromLua>(&mut self, table: &Table) -> LuaResult<Vec<T>>;
    fn get_metatable<T: IntoLua>(&mut self, value: T) -> LuaResult<Option<Table>>;
    fn set_metatable<T: IntoLua>(&mut self, value: T, metatable: Option<&Table>) -> LuaResult<()>;
    fn pack<T: IntoLua>(&mut self, value: T) -> LuaResult<Value>;
    fn unpack<T: FromLua>(&mut self, value: Value) -> LuaResult<T>;
    fn convert<T: IntoLua, U: FromLua>(&mut self, value: T) -> LuaResult<U>;
    fn create_lightuserdata(&mut self, pointer: *mut c_void) -> Value;
    fn to_pointer<T: IntoLua>(&mut self, value: T) -> LuaResult<Option<*const c_void>>;
    fn registry(&mut self) -> Table;
    fn registry_get<T: FromLua>(&mut self, key: &str) -> LuaResult<Option<T>>;
    fn registry_set<T: IntoLua>(&mut self, key: &str, value: T) -> LuaResult<()>;
    fn registry_geti<T: FromLua>(&mut self, key: i64) -> LuaResult<Option<T>>;
    fn registry_seti<T: IntoLua>(&mut self, key: i64, value: T) -> LuaResult<()>;
    fn get_type_metatable(&mut self, kind: LuaValueKind) -> Option<Table>;
    fn set_type_metatable(
        &mut self,
        kind: LuaValueKind,
        metatable: Option<&Table>,
    ) -> LuaResult<()>;
    fn get_error_message(&mut self, error: LuaError) -> LuaFullError;
    fn gc_stop(&mut self);
    fn gc_restart(&mut self);
}

/// Async high-level API shared by safe host-side Lua handles.
#[allow(async_fn_in_trait)]
pub trait LuaAsyncApi {
    async fn exec_async(&mut self, source: &str) -> LuaResult<()>;
    async fn eval_async<R: FromLua>(&mut self, source: &str) -> LuaResult<R>;
    async fn eval_multi_async<R: FromLuaMulti>(&mut self, source: &str) -> LuaResult<R>;
    async fn call_async<A: IntoLua, R: FromLuaMulti>(
        &mut self,
        function: &Function,
        args: A,
    ) -> LuaResult<R>;
    async fn call_async1<A: IntoLua, R: FromLua>(
        &mut self,
        function: &Function,
        args: A,
    ) -> LuaResult<R>;
    async fn call_async_global<A: IntoLua, R: FromLuaMulti>(
        &mut self,
        name: &str,
        args: A,
    ) -> LuaResult<R>;
    async fn call_async_global1<A: IntoLua, R: FromLua>(
        &mut self,
        name: &str,
        args: A,
    ) -> LuaResult<R>;
}

/// Sandbox-oriented high-level API shared by safe host-side Lua handles.
#[cfg(feature = "sandbox")]
pub trait LuaSandboxApi {
    fn load_sandboxed<'lua>(
        &'lua mut self,
        source: &str,
        config: &SandboxConfig,
    ) -> Chunk<'lua, Self>
    where
        Self: Sized + chunk::ChunkHost;
    fn execute_sandboxed(&mut self, source: &str, config: &SandboxConfig) -> LuaResult<()>;
    fn eval_sandboxed<R: FromLua>(&mut self, source: &str, config: &SandboxConfig) -> LuaResult<R>;
    fn eval_multi_sandboxed<R: FromLuaMulti>(
        &mut self,
        source: &str,
        config: &SandboxConfig,
    ) -> LuaResult<R>;
    fn sandbox_capture_global(&mut self, config: &mut SandboxConfig, name: &str) -> LuaResult<()>;
    fn sandbox_insert_global<T: IntoLua>(
        &mut self,
        config: &mut SandboxConfig,
        name: &str,
        value: T,
    ) -> LuaResult<()>;
}