2017-09-14 16:59:59 -04:00
|
|
|
//! # High-level bindings to Lua
|
|
|
|
//!
|
|
|
|
//! The `rlua` crate provides safe high-level bindings to the [Lua programming language].
|
|
|
|
//!
|
|
|
|
//! # The `Lua` object
|
|
|
|
//!
|
|
|
|
//! The main type exported by this library is the [`Lua`] struct. In addition to methods for
|
|
|
|
//! [executing] Lua chunks or [evaluating] Lua expressions, it provides methods for creating Lua
|
|
|
|
//! values and accessing the table of [globals].
|
|
|
|
//!
|
|
|
|
//! # Converting data
|
|
|
|
//!
|
|
|
|
//! The [`ToLua`] and [`FromLua`] traits allow conversion from Rust types to Lua values and vice
|
|
|
|
//! versa. They are implemented for many data structures found in Rust's standard library.
|
|
|
|
//!
|
|
|
|
//! For more general conversions, the [`ToLuaMulti`] and [`FromLuaMulti`] traits allow converting
|
|
|
|
//! between Rust types and *any number* of Lua values.
|
|
|
|
//!
|
|
|
|
//! Most code in `rlua` is generic over implementors of those traits, so in most places the normal
|
|
|
|
//! Rust data structures are accepted without having to write any boilerplate.
|
|
|
|
//!
|
|
|
|
//! # Custom Userdata
|
|
|
|
//!
|
|
|
|
//! The [`UserData`] trait can be implemented by user-defined types to make them available to Lua.
|
|
|
|
//! Methods and operators to be used from Lua can be added using the [`UserDataMethods`] API.
|
|
|
|
//!
|
|
|
|
//! [Lua programming language]: https://www.lua.org/
|
|
|
|
//! [`Lua`]: struct.Lua.html
|
|
|
|
//! [executing]: struct.Lua.html#method.exec
|
|
|
|
//! [evaluating]: struct.Lua.html#method.eval
|
|
|
|
//! [globals]: struct.Lua.html#method.globals
|
|
|
|
//! [`ToLua`]: trait.ToLua.html
|
|
|
|
//! [`FromLua`]: trait.FromLua.html
|
|
|
|
//! [`ToLuaMulti`]: trait.ToLuaMulti.html
|
|
|
|
//! [`FromLuaMulti`]: trait.FromLuaMulti.html
|
|
|
|
//! [`UserData`]: trait.UserData.html
|
|
|
|
//! [`UserDataMethods`]: struct.UserDataMethods.html
|
|
|
|
|
|
|
|
// Deny warnings inside doc tests / examples. When this isn't present, rustdoc doesn't show *any*
|
|
|
|
// warnings at all.
|
2017-08-02 17:12:34 -04:00
|
|
|
#![doc(test(attr(deny(warnings))))]
|
|
|
|
|
2017-08-02 16:37:30 -04:00
|
|
|
extern crate libc;
|
|
|
|
|
2017-05-22 03:09:59 -04:00
|
|
|
pub mod ffi;
|
Another major API change, out of stack space is not an Err
It, ahem "should not" be possible to exhaust lua stack space in normal usage,
and causing stack errors to be Err is slightly obnoxious. I have been wanting
to make this change for a while, and removing the callback API from tables makes
this sensible *I think*.
I can think of a couple of ways that this is not technically true, but I think
that they are acceptable, or should be handled differently.
One, you can make arbitrarily sized LuaVariadic values. I think this is maybe a
bug already, because there is an argument limit in Lua which is lower than the
stack limit. I'm not sure what happens there, but if it is a stack based panic,
(or any panic?) it is a bug.
Two, I believe that if you recurse over and over between lua -> rust -> lua ->
rust etc, and call rlua API functions, you might get a stack panic. I think for
trusted lua code, this is morally equivalent to a regular stack overflow in
plain rust, which is already.. well it's not a panic but it's some kind of safe
crash I'm not sure, so I think this is acceptable. For *untrusted* lua code,
this could theoretically be a problem if the API provided a callback that would
call back into lua, then some lua script could force a stack based panic. There
are so many concerns with untrusted lua code, and this library is NOT safe
enough yet for untrusted code (it doesn't even provide an option to limit lua to
the safe API subset yet!), so this is not currently an issue. When the library
provides support for "safe lua", it should come with big warnings anyway, and
being able to force a stack panic is pretty minor in comparison.
I think if there are other ways to cause unbounded stack usage, that it is a
bug, or there can be an error just for that situation, like argument count
limits.
This commit also fixes several stupid bugs with tests, stack checking, and
panics.
2017-06-25 16:52:32 -04:00
|
|
|
#[macro_use]
|
2017-05-21 19:50:59 -04:00
|
|
|
mod util;
|
|
|
|
mod error;
|
2017-09-30 01:27:18 -04:00
|
|
|
mod types;
|
2017-05-21 19:50:59 -04:00
|
|
|
mod lua;
|
|
|
|
mod conversion;
|
|
|
|
mod multi;
|
2017-09-15 16:03:14 -04:00
|
|
|
mod string;
|
|
|
|
mod table;
|
2017-09-30 01:08:08 -04:00
|
|
|
mod userdata;
|
2017-05-21 19:50:59 -04:00
|
|
|
|
|
|
|
#[cfg(test)]
|
|
|
|
mod tests;
|
|
|
|
|
2017-10-23 16:42:20 -04:00
|
|
|
pub use error::{Error, ExternalError, ExternalResult, Result};
|
|
|
|
pub use types::{Integer, LightUserData, Number};
|
2017-07-24 07:12:52 -04:00
|
|
|
pub use multi::Variadic;
|
2017-09-15 16:03:14 -04:00
|
|
|
pub use string::String;
|
|
|
|
pub use table::{Table, TablePairs, TableSequence};
|
2017-10-23 16:42:20 -04:00
|
|
|
pub use userdata::{AnyUserData, MetaMethod, UserData, UserDataMethods};
|
|
|
|
pub use lua::{FromLua, FromLuaMulti, Function, Lua, MultiValue, Nil, Thread, ThreadStatus, ToLua,
|
|
|
|
ToLuaMulti, Value};
|
2017-07-24 07:12:52 -04:00
|
|
|
|
|
|
|
pub mod prelude;
|