Struct sandkiste_lua::v5_3::LuaMachine

pub struct LuaMachine<'a> { /* private fields */ }

Virtual machine that executes Lua code

Basic usage

1. A new virtual machine can be created with LuaMachine::new.
2. Use LuaMachine::load_stdlib_sealed to load a sealed version of the Lua standard library; that is a modified version which does not allow breaking out of the sandbox. Alternatively, a full version of the standard library can be loaded with LuaMachine::load_stdlib, which, for example, can be used to load further dependencies, and then be sealed afterwards with LuaMachine::seal. Note, however, that this may introduce security vulnerabilites depending on which libraries have been loaded or how the state has been modified prior to calling seal.
3. Set resource limits with LuaMachine::set_memory_limit and LuaMachine::set_execution_limit, if desired.
4. Use the API provided by the sandkiste crate to compile and execute Lua programs. For a concrete example using Lua, see the top-level module documentation of sandkiste_lua.

Lifetimes

Lifetime argument 'a is a lower bound for closures passed to the Lua machine. It can be inferred automatically.

Implementations

impl<'a> LuaMachine<'a>

pub fn new() -> Self

Create a bare Lua machine

pub fn lua_state(&self) -> *mut lua_State

Retrieve pointer to lua_State

pub fn assert_empty_stack(&self)

Assert that Lua stack is empty

pub fn set_execution_limit(&self, instr: u64)

Set limit for executed instructions

pub fn set_memory_limit(&self, bytes: usize)

Set memory limit

pub fn load_stdlib(&self) -> Result<(), MachineError>

Load standard library

pub fn load_stdlib_sealed(&self) -> Result<(), MachineError>

Load sealed version of standard library

pub fn seal(&self) -> Result<(), MachineError>

Remove certain parts of standard library to seal machine as sandbox

pub fn new_table<'b>(
    &'b self
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create empty table

pub fn get_reference_key<'b>(
    &'b self,
    lua_ref: &LuaReference<'a, 'b>
) -> LuaReferenceKey

Get LuaReferenceKey for LuaReference

pub unsafe fn pop_error_message(&self) -> String

Pop error value from Lua stack and convert into String

pub unsafe fn pop_error(&self, status: c_int) -> Result<(), MachineError>

If status != LUA_OK, pop error value from Lua stack and convert into MachineError

pub unsafe fn pop_error_with_backtrace(
    &self,
    status: c_int
) -> Result<(), MachineError>

Same as LuaMachine::pop_error but also extract traceback (requires cmach_lua_errmsgh to be used during lua_pcall)

pub unsafe fn extract_datum<'b>(
    &'b self,
    index: c_int
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Convert value on Lua stack into LuaDatum

NOTE: requires some free space on Lua stack for operation

pub unsafe fn pop_datum<'b>(
    &'b self
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Pop value from Lua stack and convert into LuaDatum

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_reference<'b>(&'b self, lua_ref: &LuaReference<'a, 'b>)

Push LuaReference on top of Lua stack

pub unsafe fn push_bin(&self, binary: &[u8]) -> Result<(), MachineError>

Push binary data on top of Lua stack

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_str(&self, string: &str) -> Result<(), MachineError>

Push string on top of Lua stack

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_datum<'b, 'c>(
    &'b self,
    datum: &LuaDatum<'a, 'b, 'c>
) -> Result<(), MachineError>

Push LuaDatum on top of Lua stack

NOTE: requires some free space on Lua stack for operation

Trait Implementations

impl<'a> Callback<'a> for LuaMachine<'a>

fn callback<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator,
    F: 'a + Fn(Vec<LuaDatum<'a, 'b, 'static>>) -> Result<R, Box<dyn Error>>, 

Create a Machine::Datum representing a callback (which invokes the func closure)

fn callback_expect_args<'b, 'c, F, R>(
    &'b self,
    argc: usize,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Vec<Self::Datum<'b, 'static>, Global>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects a fixed number of arguments

fn callback_expect_min_args<'b, 'c, F, R>(
    &'b self,
    argc: usize,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Vec<Self::Datum<'b, 'static>, Global>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects a minimum number of arguments

fn callback_1arg<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects exactly one argument

fn callback_2arg<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects exactly two arguments

fn callback_3arg<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects exactly three arguments

fn callback_4arg<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects exactly four arguments

fn callback_5arg<'b, 'c, F, R>(
    &'b self,
    func: F
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    R: IntoIterator<Item = Self::Datum<'b, 'c>>,
    F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,
    <R as IntoIterator>::IntoIter: ExactSizeIterator, 

Same as Callback::callback but expects exactly five arguments

impl<'a, 'b> Compile<'a, &'b str> for LuaMachine<'a>

fn compile(
    &self,
    chunk_name: Option<String>,
    code: &'b str
) -> Result<LuaFunction<'a, '_>, MachineError>

Compiles code, returns the compiled function or a compilation error

impl<'a> Compile<'a, String> for LuaMachine<'a>

fn compile(
    &self,
    chunk_name: Option<String>,
    code: String
) -> Result<LuaFunction<'a, '_>, MachineError>

Compiles code, returns the compiled function or a compilation error

impl<'a> Debug for LuaMachine<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Drop for LuaMachine<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Globals<'a> for LuaMachine<'a>

fn get<'b>(
    &'b self,
    name: &str
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Get global variable

fn set<'b, 'c>(
    &'b self,
    name: &str,
    value: LuaDatum<'a, 'b, 'c>
) -> Result<(), MachineError>

Set global variable

impl<'a> HasArray<'a> for LuaMachine<'a>

fn new_empty_array<'b>(
    &'b self
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create datum that is an empty array

fn new_array<'b, 'c, I>(
    &'b self,
    elements: I
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    I: IntoIterator<Item = Self::Datum<'b, 'c>>,
    Self::Datum<'b, 'static>: MaybeArray,
    <Self::Datum<'b, 'static> as MaybeArray>::Element<'d> == Self::Datum<'b, 'd>, 

Create datum that is an array

impl<'a> HasModules<'a> for LuaMachine<'a>

type Module<'b>
where
    'a: 'b = LuaModule<'a, 'b>

Type of modules and sub-modules

fn module<'b>(&'b self, name: &str) -> Result<LuaModule<'a, 'b>, MachineError>

Open a module (create if non-existent)

impl<'a> HasStringMap<'a> for LuaMachine<'a>

fn new_empty_string_map<'b>(
    &'b self
) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create datum that is an empty string map

fn new_string_map<'b, 'c, 'd, I>(
    &'b self,
    entries: I
) -> Result<Self::Datum<'b, 'static>, MachineError> where
    I: IntoIterator<Item = (&'d str, Self::Datum<'b, 'c>)>,
    Self::Datum<'b, 'static>: MaybeStringMap,
    <Self::Datum<'b, 'static> as MaybeStringMap>::Value<'e> == Self::Datum<'b, 'e>, 

Create datum that is a string map

impl<'a> Hash for LuaMachine<'a>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a> Machine<'a> for LuaMachine<'a>

type Datum<'b, 'c>
where
    Self: 'b = LuaDatum<'a, 'b, 'c>

Data type representing values passed to or returned from machine

type Function<'b>
where
    Self: 'b = LuaFunction<'a, 'b>

Function (for example returned by Compile::compile) which can be executed by the machine

impl<'a> PartialEq<LuaMachine<'a>> for LuaMachine<'a>

A LuaMachine is only equal to itself

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> Eq for LuaMachine<'a>

A LuaMachine is only equal to itself